HOWTO · Java
Java 中的幂等
本教程演示了在 Java 中使用幂等性。
本页内容
当某个操作应用一次或多次后,对相关状态产生的预期效果都相同,该操作就是幂等的。响应或返回值可以不同;关键在于最终状态。客户端请求超时后可能会重试,因为它无法确定第一次尝试是否已到达服务器;幂等性有助于处理这种情况。
Java 中幂等性的含义
设想一个将用户状态设为 "active" 的操作。无论设置一次还是重复设置,状态都会保持为 active,因此这种状态变更是幂等的。相比之下,每次递增计数器都会改变其值,所以重复执行会产生额外影响。
这里的区别在于操作产生的效果,而不是代码是否再次运行或是否返回相同消息。设置操作仍可能触发独立的副作用,例如每次调用都发送一封电子邮件;这些副作用也必须纳入对整个操作的考量。
实现幂等的 Java 操作
重复赋值 true 本身就是幂等的:第一次调用后,订阅状态变为 active,之后每次调用都会让它保持 active。下面的完整程序演示了这一行为。
运行下面这个完整的 Java 程序:
本节中的代码以及显示的标签或输出仍为英文。
public class IdempotentActivation {
private boolean active;
public void activate() {
active = true;
}
public boolean isActive() {
return active;
}
public static void main(String[] args) {
IdempotentActivation subscription = new IdempotentActivation();
subscription.activate();
subscription.activate();
System.out.println("Active: " + subscription.isActive());
}
}
程序在打印订阅状态前调用了两次 activate()。输出如下:
Active: true
在服务中,状态变更通常应放在数据库事务中。请求标识符也可以防止重复处理,但必须将该标识符和处理结果与状态变更原子地存储。仅使用内存集合会在服务重启后丢失,也无法协调多个服务实例。
测试重复调用及其影响
可以通过多次执行同一操作,并在每次调用后检查状态来验证幂等性。对于上面的程序,第一次调用后 isActive() 应返回 true,第二次调用后仍应返回 true。测试实际服务时,还要检查持久化状态及任何副作用,例如发出的消息或产生的扣款;仅观察到相同的打印值,并不能证明这些影响在重复调用时得到安全处理。
一种有效的测试方法是比较调用一次与连续多次相同操作后的状态。如果第二次调用再次改变了预期状态,该操作就不是幂等的。如果状态仍符合预期,重试会更安全;不过,并发和事务行为仍需单独测试。
HTTP 方法中的幂等性
HTTP 幂等性描述的是服务器对重复的相同请求所产生的预期效果。它不要求每次响应都具有相同的状态码或正文。例如,资源已被删除后,再次发送 DELETE 可能会得到不同的响应,但预期效果仍然相同。
| 方法 | 按定义是否幂等? | 实际含义 |
|---|---|---|
| GET | 是 | 获取资源表示;不应请求更改状态。 |
| HEAD | 是 | 类似 GET,但只返回标头,不返回响应正文。 |
| OPTIONS | 是 | 报告目标资源支持的通信选项。 |
| TRACE | 是 | 为诊断目的,返回收到的请求。 |
| PUT | 是 | 使用提供的状态创建或替换目标资源表示。 |
| DELETE | 是 | 请求删除目标资源;重复执行的预期效果相同。 |
| POST | 通常不是 | 常用于创建资源或触发操作;API 可以额外提供去重行为。 |
| PATCH | 不一定 | 应用部分变更;重复执行是否安全取决于补丁操作。 |
具体 API 可以定义额外的保护措施,但只有在服务器正确实现这些语义时,客户端才应依赖方法语义。如果每次重试都会再次递增某个值,那么仅仅使用 PUT 或 PATCH 并不会让该请求变成幂等请求。
常见误解与限制
幂等并不意味着什么都没有发生:第一次调用可能会改变状态。它也不保证响应相同,不会阻止并发更新,也不会使多步流程自动成为原子操作。某个操作对一个资源是幂等的,仍可能重复触发与该资源无关的副作用。
设计可重试操作时,应先明确哪些状态和副作用属于其结果,然后使用条件更新,或借助持久化存储对请求去重。测试最终状态和相关副作用。这些检查有助于明确预期保证,而不必假设每种重复调用都无害。