RESTful设计规范（状态码、幂等性）

最新推荐文章于 2025-07-09 21:28:25 发布

原创最新推荐文章于 2025-07-09 21:28:25 发布 · 733 阅读

6 ·

CC 4.0 BY-SA版权

文章标签：

#restful #设计规范 #后端

测试专栏收录该内容

40 篇文章

订阅专栏

RESTful API （Representational State Transfer（表述性状态转移））设计规范的核心在于遵循 HTTP 协议的特性，确保接口的简洁性、可预测性和可扩展性。以下是关于状态码和幂等性的关键规范：

一、HTTP 状态码规范

状态码用于表示请求的处理结果，客户端可根据状态码快速判断问题。常用状态码分类：

分类	状态码	场景
2xx	200 OK	通用成功状态（GET/PUT/PATCH）
	201 Created	资源创建成功（POST），响应中应包含 `Location` 头指向新资源
	204 No Content	成功但无返回体（DELETE 或 PUT/PATCH 无需返回数据时）
3xx	301 Moved Permanently	资源永久重定向
	304 Not Modified	缓存有效（条件请求如 `If-Modified-Since`）
4xx	400 Bad Request	请求格式错误（如参数校验失败）
	401 Unauthorized	未认证（需提供身份凭证）
	403 Forbidden	无权限访问资源（认证成功但权限不足）
	404 Not Found	资源不存在
	405 Method Not Allowed	请求方法不支持（如对只读资源发送 POST）
	409 Conflict	资源冲突（如重复创建或版本冲突）
5xx	500 Internal Server Error	服务器内部错误（应避免暴露敏感信息）
	503 Service Unavailable	服务不可用（如维护或过载）

最佳实践：

避免滥用 200 OK 返回错误信息（如 { "error": "Not Found" }），应使用正确的状态码。
对客户端错误（4xx）和服务端错误（5xx）严格区分。

二、幂等性（Idempotency）

幂等性指同一请求多次执行的效果与一次执行相同，是 RESTful 设计的重要原则。

HTTP 方法	幂等性	解释
GET	是	多次读取同一资源不会改变服务器状态。
PUT	是	多次更新同一资源会得到相同结果（全量替换）。
DELETE	是	第一次删除资源后，后续请求返回 `404` 或 `410`，但效果不变。
POST	否	每次调用可能创建新资源（如重复提交订单）。
PATCH	通常否	部分更新可能依赖当前资源状态（如 `amount=-10`）。若明确全量属性可设计为幂等。

如何保证幂等性：

客户端：对非幂等操作（如 POST）生成唯一请求 ID（X-Request-ID），服务端通过缓存结果避免重复处理。
服务端：
- 使用条件请求（如 If-Match 头部和 ETag 校验资源版本）。
- 对更新操作采用 PUT 替代 PATCH（若业务允许）。
- 实现乐观锁（如版本号或时间戳）。

三、其他关键设计规范

URI 设计：
- 使用名词复数形式（如 /users 而非 /user）。
- 避免动词，通过 HTTP 方法表达操作（如 DELETE /users/123）。
- 嵌套资源用 / 分隔（如 /users/123/posts）。
版本控制：
- 在 URI 或 Header 中显式声明版本（如 /v1/users 或 Accept: application/vnd.api.v1+json）。
过滤与分页：
- 使用查询参数：/users?role=admin&page=2&limit=10。
HATEOAS：
- 在响应中嵌入链接（如 "self": { "href": "/users/1" }），引导客户端发现后续操作。

四、错误响应格式

统一错误格式，包含明确的信息：

{
  "error": {
    "code": "invalid_parameter",
    "message": "Email format is invalid",
    "details": {
      "field": "email",
      "expected": "valid email address"
    }
  }
}

通过遵循以上规范，API 可提升可维护性、降低客户端复杂度，并减少因误解导致的错误。