什么是 API 幂等性？

在线付款时，避免重复收费是至关重要的。如果发生重复收费，不仅会导致负面的客户体验，还可能使客户流失，从而对公司造成长期的损失。

在处理支付的 API 开发中，幂等性功能可以有效防止这种问题的发生。本文将探讨幂等 API 及其在构建 REST API 过程中的重要性，提供有价值的见解，帮助创造更好的客户体验。

幂等 REST API 简介

在开发过程中，需要确保向服务器发送相同的请求时能够获得一致的结果，避免最终结果发生变化。这是构建能够有效从故障中恢复的弹性 API 的核心理念。以下是示例 API 调用过程的说明。

在示例中，客户端向服务器发出 API 调用。对于“创建付款”这一 API 调用，可能会收到多种响应，例如成功、失败、依赖性问题或无响应。在本例中，收到的是“无响应”消息。

遇到“无响应”时，重试 API 调用是一种常见做法，这通常有助于服务器从处理多个请求等问题中恢复。然而，如何确认“创建付款”的原始请求在后端实际是否成功处理呢？

如果在没有收到响应后重试 API 调用，可能会出现重复处理的情况，例如实际生成了两笔付款但只期望一笔。这种情况可能会引发问题。因此，构建弹性 API 时需要支持自动重试机制，并确保 API 具备幂等性，以避免此类问题的发生。

什么是幂等 API？

幂等性指的是某个操作可以多次执行，而不会改变最终结果。换句话说，这类似于将一个数字乘以零，不管执行多少次，结果始终为 0。要改变结果，需要改变操作本身。

在上述示例中，无论“创建付款”操作被调用多少次，最终结果仍应只生成一笔付款。这就是幂等操作所支持的行为。

什么是幂等 REST API？

在 REST API 中，当 HTTP 方法具有幂等性时，发送多个相同的请求只会导致初始请求产生更改。因此，返回给用户的结果将不会因该方法被调用的次数而变化。

幂等 HTTP 方法

一些 REST API 方法天生具备幂等性，而另一些则不具备。要判断一个方法是否具备幂等性，需要考虑服务器的后端状态。下表展示了不同 HTTP 方法及其幂等性状态。

从表中可以看出，POST 和 PATCH 方法不具备幂等性，而 HEAD、OPTIONS、GET、PUT、TRACE 和 DELETE 方法则具备幂等性。接下来，将详细分析这些方法，以了解它们的幂等性状态原因。

GET | HEAD | OPTIONS | TRACE

GET 是一种幂等方法，因为它仅用于读取操作，不会对后端状态造成任何改变。如果对 GET 端点发出多个相同的请求，每次都会收到与第一次相同的响应。

HEAD 和 OPTIONS 方法也遵循相同的原则，因为它们用于检索数据，不会改变服务器上的资源状态。

TRACE 方法可以是幂等的，但这一点并不总是得到保证。这更多的是一种期望，而非强制要求。

POST

POST 方法不是幂等的，因为多次调用它可能导致重复或错误的更新。通常，POST API 会在服务器上创建新资源。如果使用相同的请求主体多次调用 POST 端点，将会创建多个记录。为避免这种情况，需要在应用中实现自定义逻辑来防止重复记录的产生。

PUT

PUT 方法是幂等的，因为它执行的是更新操作。如果多次使用相同的请求调用 PUT 端点，除了首次请求外，不会引发任何状态变化。

DELETE

DELETE 是一种幂等方法，因为连续的相同请求不会改变删除状态。第一次调用 DELETE 可能返回 200（OK），而后续的 DELETE 请求可能返回 404（未找到）。虽然第一次请求后的响应可能不同，但状态不会再发生变化。

PATCH

PATCH 通常不是幂等方法，因为对同一有效负载执行一系列连续的操作可能导致不同的结果。例如，对 JSON 树执行一系列移动操作（如 {“op”:“move”, “from”:“/tags/main”, “path”:“/tags/sub”}），第一次操作会成功移动资源，而连续操作可能会引发错误。与更新整个记录的 PUT 方法不同，PATCH 方法用于更新记录中的某些字段。

为什么幂等 API 很重要？

遵循幂等性准则对 REST API 至关重要，因为这是一个常见的行业标准。API 的用户会期望端点的行为符合这一标准。支持幂等性的 API 可以安全地重试请求，而不会错误地执行两次相同的操作。如果同行提到需要使端点具备幂等性，现在可以准确理解他们的意思。