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

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）。若明确全量属性可设计为幂等。

​如何保证幂等性​：

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

---

​三、其他关键设计规范​

1. ​URI 设计​：

   • 使用名词复数形式（如 /users 而非 /user）。
   • 避免动词，通过 HTTP 方法表达操作（如 DELETE /users/123）。
   • 嵌套资源用 / 分隔（如 /users/123/posts）。

2. ​版本控制​：

   • 在 URI 或 Header 中显式声明版本（如 /v1/users 或 Accept: application/vnd.api.v1+json）。

3. ​过滤与分页​：

   • 使用查询参数：/users?role=admin&page=2&limit=10。

4. ​HATEOAS​：

   • 在响应中嵌入链接（如 "self": { "href": "/users/1" }），引导客户端发现后续操作。

---

​四、错误响应格式​

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

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

---

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