如何设计幂等API

幂等的概念

幂等（idempotency）是一个设计稳定和健壮API的关键属性，特别是在分布式系统环境中，这些环境中，由于网络问题或者客户端重试等原因，相同的请求被发送多次是很常见的。一个幂等的API对于相同的请求，始终产生相同的结果，无论这个API被调用多少次。

如何设计幂等API

下面是设计幂等API的步骤：

1.使用唯一的请求ID

这个ID要满足：

• 客户端提供：通常和推荐的做法是，对于客户端的请求，生成一个唯一ID（比如UUID），作为请求的一部分，放到Header或者其他地方。
• 服务端跟踪：服务器应该储存每一个唯一请求ID的状态和请求的结果。
• 请求顺序：当服务器收到请求后, 如果存在一个唯一请求ID相同的前请求：
  • 如果前请求已经成功执行完毕，服务器返回前请求的结果，不用重新执行请求；
  • 如果前请求已经失败，服务器返回前请求的错误结果并执行潜在的重试操作；
  • 如果前请求正在执行中，服务器可以等待前请求执行结束，然后根据执行结果返回结果。
    如果可以满足上述要求，我们可以定义它为幂等码。

2.跟踪操作状态

• 数据库或缓存：服务器需要一个机制去跟踪相应幂等码请求产生的结果，这个结果可能是数据库表的变化，或者分布式缓存的变化；
• 状态码：需要存储每一个原始请求对应的 HTTP 状态码和返回值

3.处理不同的 HTTP 方法

• GET：GET 请求天然就是幂等的，读取数据不应该有任何副作用；
• PUT：PUT 请求也是是幂等的，因为 PUT 是针对特定数据做特点的修改；
• DELETE：DELETE 请求通常也被认为是幂等的，调用多次 DELETE 方法删除特定资源，虽然可能会碰到资源不存在的错误，但执行结果依然可以被认为是成功的（因为结果是相同的，没有多删除资源）。
• POST：POST 通常都不是幂等的，因为它经常被用来创建新的资源。为了保证 POST 方法的幂等性，你需要实施幂等码机制。

4.设计幂等操作原则

• 聚集最终状态：设计的操作应该聚集在如何得到最终状态，而不是考虑如何从当前状态通过一些操作变到最终状态。举例来说，使用“设置计数器值到 X”，而不是“当前计数器值加 1”。（因为当前值可能已经不可靠了）
• 避免多次调用的副作用：确保重复调用不会导致无意的累计副作用。

5.返回合适的 HTTP 状态码

• 200 OK: 成功执行幂等操作.
• 201 Created: 成功执行创建操作（使用幂等码）.
• 204 No Content: 成功执行 DELET 或 PUT 操作，不返回 Body.
• 409 Conflict: 可以被用来表示当前请求和前一个有相同幂等码的请求有冲突 (尽管这应该在执行的时候被小心处理，但小概率情况下还是发生了).

作者：Bearalise
出处：如何设计幂等API
版权：本文版权归作者所有
转载：欢迎转载，但未经作者同意，必须保留此段声明，必须在文章中给出原文链接。