RESTful

介绍

一句话理解：

RESTful 不是某个框架，而是一种接口设计习惯。核心就是用清晰的 URI + 合适的 HTTP 方法 + 准确的状态码，让前后端一看就知道这个接口在干什么。

常见资源风格：

• 资源集合：/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: http://example.com/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。
  • 400 Bad Request：参数有问题。
  • 404 Not Found：要更新的资源不存在。
  • 412 Precondition Failed：并发更新校验失败（常见于 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"
}

或者：

HTTP/1.1 204 No Content

删除 (Delete)

• HTTP 方法：DELETE
• URI 示例：/resources/{id}
• 常见状态码：
  • 204 No Content：删除成功，不返回 body（最常见）。
  • 200 OK：删除成功，并返回一段确认信息。
  • 404 Not Found：资源不存在。

响应示例：

DELETE /resources/123 HTTP/1.1

HTTP/1.1 204 No Content

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

• GET：幂等。
• PUT：幂等（同样的请求重复执行，结果一致）。
• DELETE：通常按结果看也是幂等。
• 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。