幂等性指同一个操作执行一次和执行多次，对系统最终状态的影响相同。它是接口设计中很重要的稳定性概念。

HTTP 方法与幂等性

按照语义，GET、PUT、DELETE 通常应是幂等的，POST 通常不是。

  • GET /users/1 多次查询，不改变状态；
  • PUT /users/1 多次提交同一份完整数据，最终状态相同；
  • DELETE /users/1 多次删除，最终都是不存在；
  • POST /orders 多次提交，可能创建多个订单。

这只是语义约定，真正是否幂等还取决于实现。

为什么幂等重要

网络请求可能超时、重试、重复提交。如果接口不具备幂等性，重试就可能造成重复创建、重复扣减或状态错乱。

因此关键写操作通常需要明确幂等设计。

常见方案

一种常见做法是使用幂等键。客户端为一次业务操作生成唯一标识，服务端记录处理结果。相同幂等键再次提交时，直接返回已有结果。

另一种做法是让资源标识由客户端确定，例如 PUT /resources/{id}，这样重复请求会落到同一个资源上。

幂等不等于无副作用

DELETE 第一次执行可能删除资源，当然有副作用。但第二次、第三次执行不会继续产生新的状态变化，所以它仍然可以是幂等的。

小结

幂等性是为了让系统面对重试和重复请求时保持稳定。接口设计时应明确哪些操作可以重试，哪些操作必须带幂等键。