RESTful

介绍

一句话理解：

REST 是一种架构风格，不是框架或严格的接口规范；RESTful 通常指遵循其资源导向思想设计的接口。日常 API 设计中，应使用 URI 标识资源，以 HTTP 方法表达请求意图，并用状态码说明处理结果。

URI 描述资源，不描述动作；动作优先由 HTTP 方法表达。具体的资源关系、响应结构和错误格式仍需要由 API 契约明确。

常见资源风格：

• 资源集合：/users
• 单个资源：/users/{id}

创建 (Create)

• HTTP 方法：POST
• URI 示例：/resources
• 常见状态码：
  • 201 Created：创建成功。应通过 Location 指出主要新资源的地址；响应体可返回该资源或请求处理结果。
  • 400 Bad Request：参数格式不对或缺少必要字段。
  • 409 Conflict：要创建的数据和现有数据冲突（比如唯一键重复）。

响应示例：

POST /resources HTTP/1.1
Content-Type: application/json

{
  "name": "New Resource"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /resources/123

{
  "id": 123,
  "name": "New Resource",
  "created_at": "2024-06-27T12:34:56Z"
}

读取 (Read)

• HTTP 方法：GET
• URI 示例：/resources 或 /resources/{id}
• 常见状态码：
  • 200 OK：查询成功。
  • 404 Not Found：按 id 查单个资源时，资源不存在。

响应示例：

GET /resources/123 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "name": "Existing Resource",
  "created_at": "2024-06-27T12:34:56Z"
}

实战里最容易混淆的一点：

• 搜索列表没查到数据：返回 200，body 给空数组，比如 []。
• 按 id 查单个资源没查到：返回 404。

更新 (Update)

• HTTP 方法：PUT（以请求表示替换目标资源状态）或 PATCH（对目标资源应用部分修改）
• URI 示例：/resources/{id}
• 常见状态码：
  • 200 OK：更新成功，并返回处理结果或更新后的资源。
  • 204 No Content：更新成功，但不返回 body。
  • 201 Created：使用 PUT 向尚不存在、且由客户端指定的 URI 成功创建资源。
  • 400 Bad Request：参数有问题。
  • 404 Not Found：要更新的资源不存在。
  • 412 Precondition Failed：If-Match 等条件请求不满足；可用于基于 ETag 的并发更新控制。

响应示例：

PUT /resources/123 HTTP/1.1
Content-Type: application/json

{
  "name": "Updated Resource"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "name": "Updated Resource",
  "updated_at": "2024-06-27T12:45:00Z"
}

PUT 的语义是替换目标资源的状态，而非机械要求传入数据库中的每一个字段；服务端应在 API 契约中定义请求表示包含哪些字段。PATCH 的补丁格式也应明确，例如 JSON Merge Patch 或 JSON Patch。PATCH 不保证幂等，是否可安全重试取决于具体补丁操作。

也可以只返回状态码：

HTTP/1.1 204 No Content

删除 (Delete)

• HTTP 方法：DELETE
• URI 示例：/resources/{id}
• 常见状态码：
  • 202 Accepted：已接受删除请求，但操作尚未完成。
  • 204 No Content：删除操作已完成，不返回 body。
  • 200 OK：删除成功，并返回一段确认信息。
  • 404 Not Found：资源不存在；是否将重复删除视为 404 或成功响应，应由 API 契约统一规定。

响应示例：

DELETE /resources/123 HTTP/1.1

HTTP/1.1 204 No Content

补充：幂等性（面试常问）

• 幂等指同一请求重复执行时，对服务端的预期效果与执行一次相同；不要求每次返回相同的状态码或响应体。
• GET：安全且幂等。
• PUT：幂等。
• DELETE：幂等；首次删除可返回 204，后续请求是否返回 404 由接口契约决定。
• POST：通常非幂等（重复提交可能创建多条数据）。
• PATCH：不保证幂等，取决于补丁的定义与实现。

补充：错误响应建议统一

建议给前端统一的错误格式，方便处理和展示：

{
  "code": "VALIDATION_ERROR",
  "message": "name is required",
  "details": [
    {
      "field": "name",
      "reason": "required"
    }
  ]
}

总结

• 创建：POST + 201 Created（最好带 Location）。
• 读取：GET + 200；按 id 查不到用 404。
• 更新：PUT/PATCH + 200 或 204。
• 删除：DELETE + 204（或 200）。
• 列表为空返回 200 + 空数组，不要返回 404。

参考

• RFC 9110：HTTP Semantics
• RFC 5789：PATCH Method for HTTP