开发者对幂等性的误解

发布: 3天前 (2026年2月19日 GMT+8 00:38)

5 分钟阅读

I’m happy to translate the article for you, but I’ll need the full text you’d like translated. Could you please paste the content (or the portion you want translated) here? I’ll keep the source line, formatting, markdown, and any code blocks exactly as you specify.

快速提问

DELETE 接口在后续调用返回 404，它是幂等的吗？

如果你因为响应变化而说 no，本文适合你。

幂等性是一个经常被误解的概念，即使是拥有多年经验的开发者也是如此。

什么是幂等性

维基百科定义：

幂等性是数学和计算机科学中某些操作的属性，这些操作可以多次应用而不会在初始应用之外改变结果。

在计算机科学中我们可以这样表述：

幂等性是操作的属性，即它可以多次应用而不会在初始应用之外改变结果。

示例 GET 操作

GET 请求通常是幂等的，因为它不会修改数据库。
例如：

GET /api/v1/users

无论调用多少次，响应都是相同的，并且没有副作用。

POST、PUT、PATCH 和 DELETE 操作

关于 POST、PUT、PATCH 和 DELETE 常常会产生混淆。它们是否幂等取决于具体实现，而不仅仅是 HTTP 方法本身。

POST 操作

考虑一个用于创建用户的 POST 端点。

class User {
    final UUID id;
    final String username;
}

请求

POST /api/v1/users
Content-Type: application/json

{
  "username": "manuelarte"
}

响应（首次调用）

200 OK
Content-Type: application/json

{
  "id": "f2f7734c-1082-43cf-9b66-9161349ef154",
  "username": "manuelarte"
}

场景 A – 每次都会创建新用户

再次使用相同的负载调用该端点会返回一个不同的用户：

200 OK
Content-Type: application/json

{
  "id": "c6fab354-c559-460b-a66c-5d0bad8f6aba",
  "username": "manuelarte"
}

该端点 不是幂等的，因为每个请求都会创建一个新资源。

场景 B – 与首次调用返回相同的响应

如果第二次调用返回的用户 与第一次相同：

200 OK
Content-Type: application/json

{
  "id": "f2f7734c-1082-43cf-9b66-9161349ef154",
  "username": "manuelarte"
}

该端点 是幂等的：系统状态在第一次请求后不再改变。

场景 C – 响应码不同但状态未变

假设第二次调用返回一个错误，表明用户已存在：

400 Bad Request
Content-Type: application/json

{
  "code": "USER_CREATED",
  "message": "user already created"
}

即使 HTTP 状态码不同，端点仍然幂等，因为底层状态（单个用户）保持不变。幂等性关注的是最终状态，而不是响应码。

DELETE 端点

典型的 DELETE 请求是幂等的，无论响应码为何：

DELETE /api/v1/users/{id}

第一次调用删除资源 → 204 No Content。
随后调用发现资源不存在 → 404 Not Found（或 204 No Content）。

因为第一次成功删除后的状态对后续所有调用都是相同的，所以该端点是幂等的。

非幂等的删除示例

DELETE /api/v1/users/last

如果每次调用都删除当前最后的用户（例如，第一次调用删除用户 5，第二次调用删除用户 4，……），则状态随每个请求而变化，因此该端点不是幂等的。

摘要与要点

幂等性意味着对相同数据的连续调用在第一次成功请求之后不会改变系统的状态。
它关注的是状态，而不是 HTTP 方法或响应码。
理解这一点有助于：
- API 设计 – 构建能够安全重试请求的服务。
- 客户端实现 – 正确处理不同的响应码。
- 契约测试 – 为 API 行为编写准确的测试。

下次设计或使用 API 时，请记住：

幂等性 = 第一次请求后状态不再改变
HTTP 方法暗示幂等性，但实现上才是保证。

欲了解更多细节，请参阅 RFC 9110 以及关于使用头部实现幂等性的相关资源。