幂等

如果一个 HTTP 方法的预期服务器效果,在发送单个请求时与发送多个相同请求时相同,则该方法是幂等的。

HTTP 规范定义了多种 HTTP 方法及其语义,其中包括它们是否幂等。所有安全方法都是幂等的,PUTDELETE 方法也是。而 POSTPATCH 方法则不保证幂等。

客户端可以安全地重试使用幂等方法的请求,例如,在不确定请求是否已到达服务器的情况下。如果多个相同的请求碰巧到达服务器,只要方法是幂等的,就不会造成任何损害。

HTTP 规范仅根据客户端对服务器的**预期**效果来定义幂等性。例如,POST 请求旨在向服务器发送数据,而 DELETE 请求旨在删除服务器上的资源。实际上,服务器有责任确保其公开的路由符合这些语义。

注意: 虽然强烈建议服务器遵循 HTTP 规范所规定的语义,但规范并未强制要求。在实际环境中,没有什么能阻止服务器在幂等 HTTP 方法下暴露一个非幂等的端点,尽管这可能会让客户端感到惊讶。

此外,请记住

  • 使用幂等方法的请求不一定意味着请求对服务器没有副作用,而仅表示客户端没有预期任何副作用:例如,服务器可能会记录接收每个请求的时间。
  • 每次请求返回的响应可能不同:例如,第一次调用 DELETE 可能会返回 200,而后续调用则可能返回 404

示例

GET /pageX HTTP/1.1 是幂等的,因为它是一个安全(只读)方法。如果服务器上的数据在此期间更新,连续调用可能会向客户端返回不同的数据。

POST /add_row HTTP/1.1 不是幂等的;如果多次调用,它会添加多行。

http
POST /add_row HTTP/1.1
POST /add_row HTTP/1.1   -> Adds a 2nd row
POST /add_row HTTP/1.1   -> Adds a 3rd row

DELETE /idX/delete HTTP/1.1 是幂等的,即使返回的状态码在不同请求之间可能会改变。

http
DELETE /idX/delete HTTP/1.1   -> Returns 200 if idX exists
DELETE /idX/delete HTTP/1.1   -> Returns 404 as it just got deleted
DELETE /idX/delete HTTP/1.1   -> Returns 404

另见