RESTful API 设计规范

转载说明：本文转载自 CSDN 博客 @m0_65095770，遵循 CC 4.0 BY-SA 版权协议，版权归原作者所有。

核心思想：REST

REST（Representational State Transfer）是一种架构风格，而不是严格的标准。其核心思想是资源。API 被设计为对网络上的资源进行操作，每个资源都有一个唯一的标识符（URI），并通过标准的 HTTP 方法进行操作。

1.面向资源设计（Resource-Oriented）

这是最重要的概念，将API视为对资源（名词）的操作，而不是对动作（动词）的调用。

• 资源：任何可以命名的对象（用户，订单，产品等）。

/users ——> 用户集合

• 集合：同一类型资源的集合（如users是一组user）。

/users/123 ——> id为123的用户实例

• 实例：集合中的单个特定资源（如id为123的用户）。

/users/123/orders ——> 用户123的订单集合（一种子资源）。

2.使用HTTP方法（动词）进行操作

利用HTTP方法定义对资源的操作意图，这是REST的精髓。

HTTP 方法描述通常对应的 SQLGET检索（Fetch） 资源。请求不应改变服务器状态。幂等、安全。SELECTPOST创建（Create） 新资源。通常返回新创建的资源。非幂等。INSERTPUT完整更新（Update） 资源。客户端提供完整的更新后资源。幂等。UPDATEPATCH部分更新（Partial Update） 资源。客户端只提供需要修改的字段UPDATEDELETE删除（Delete） 资源。幂等。DELETE示例：

• GET /users -> 获取所有用户列表
• GET /users/123 -> 获取 ID 为 123 的用户详情
• POST /users -> 创建一个新用户
• PUT /users/123 -> 整体更新用户 123 的信息
• PATCH /users/123 -> 部分更新用户 123 的信息（如只更新邮箱）
• DELETE /users/123 -> 删除用户 123

3.使用名词（复数形式），而非动词

URL应该标识资源，而不是操作。避免在URL中使用动词。

不推荐 (Bad)推荐 (Good)说明GET /getUser/123GET /users/123URI 中不应有动词POST /createUserPOST /users使用 HTTP 方法表示动作POST /updateUser/123PUT /users/123使用 HTTP 方法表示动作GET /deleteUser/123DELETE/users/123绝对禁止用 GET 请求执行删除操作4.返回合适的HTTP状态码

使用标准 HTTP 状态码向客户端表明请求的结果。

状态码范围类别常用状态码说明2xx成功（Success）200 OK通用成功状态201 Created资源创建成功（常用于 POST 响应）204 No Content成功，但无内容返回（常用于 DELETE 或 PUT 响应）3xx重定向 (Redirection)304 Not Modified资源未修改（用于缓存）4xx客户端错误 (Client Error)400 Bad Request请求格式错误、参数错误401 Unauthorized未认证（身份未知）403 Forbidden无权限（身份已知但无权限）404 Not Found资源不存在429 Too Many Requests请求过于频繁（限流）5xx服务器错误 (Server Error)500 Internal Server Error通用服务器错误502 Bad Gateway网关或代理服务器错误503 Service Unavailable服务不可用（维护或过载）5.提供清晰的数据格式

请求体和响应体应使用JSON作为主要数据交换数据格式。确保设置正确的Content\_Type头（如application/json）。

示例：创建用户

请求： POST /users

• Headers: Content-Type: application/json
• Body:

{
  "name": "John Doe",
  "email": "john@example.com"
}

响应： 201 Created

Body:

{
  "id": 123, // 服务器生成的ID
  "name": "John Doe",
  "email": "john@example.com",
  "createdAt": "2023-10-25T08:00:00Z"
}

6.版本化（Versioning）

将 API 版本号放入 URI 或 Header 中，这是管理重大变更的最佳实践，不会破坏现有客户端。

• URI 路径 (最常见): https://api.example.com/v1/users
• 查询参数 (Query String): https://api.example.com/users?version=1
• Accept 头 (更优雅): Accept: application/vnd.example.v1+json

推荐使用 URI 路径方式，因为它最直观、最简单。

7.过滤、排序、搜索和分页

对于返回集合的 API（如 GET /articles），必须提供这些参数来限制返回结果。

• 过滤 (Filter): GET /users?role=admin -> 只获取管理员用户
• 排序 (Sort): GET /users?sort=-created_at,name -> 按 created_at 降序，再按 name 升序排序
• 搜索 (Search): GET /users?q=john -> 搜索名字或邮箱包含 "john" 的用户
• 分页 (Pagination): 必须提供！ 防止返回海量数据。

- **Limit/Offset:** `GET /users?limit=20&offset=40` -> 获取第 3 页（每页 20 条）
- **Page-based:** `GET /users?page=3&per_page=20`
- **Cursor-based (推荐):** `GET /users?cursor=abc123&limit=20` -> 更适合大型、动态数据集

响应中应包含分页元数据：

{
  "data": [ ... ], // 当前页的数据
  "pagination": {
    "total_count": 100,
    "page": 3,
    "per_page": 20,
    "has_next_page": true
  }
}

8.使用HTTPS

始终使用 HTTPS 来保护传输中的数据，确保认证信息和请求/响应体的安全。这是现代 API 的必备要求。