RESTful API 设计指南

1. 什么是 RESTful API？

RESTful API（Representational State Transfer）是一种基于 HTTP 规范的架构风格，专注于通过标准化的请求方法和 URL 结构，提供一致性强、可扩展性高的 Web 服务接口。

RESTful API 通过 资源（Resource）、HTTP 方法（Methods） 和 状态表示（Representation） 进行交互，使 API 设计更加直观、清晰，并遵循无状态（Stateless）的原则。

2. RESTful API 设计原则

（1）基于资源（Resource-Oriented）

在 REST 中，一切都是资源，每个资源都有一个唯一的 URI（Uniform Resource Identifier），通常使用 名词（noun） 进行定义。例如：

• GET /users → 获取所有用户
• GET /users/{id} → 获取指定用户
• POST /users → 创建新用户
• PUT /users/{id} → 更新用户
• DELETE /users/{id} → 删除用户

资源命名规范

• 资源名称应该使用 复数 形式，如 /users、/orders、/products。
• 避免使用动词，如 /getUser、/createOrder（错误示例）。
• 通过 URL 结构表示资源层级：
  • GET /users/{id}/orders → 获取某个用户的所有订单
  • POST /users/{id}/orders → 为指定用户创建订单

（2）使用标准 HTTP 方法

RESTful API 依赖 HTTP 方法来描述操作：

HTTP 方法	作用
GET	获取资源
POST	创建资源
PUT	更新整个资源
PATCH	局部更新资源
DELETE	删除资源

例如：

GET /products/123       # 获取 ID 为 123 的产品
POST /products         # 创建新产品
PUT /products/123      # 更新 ID 为 123 的产品（完整更新）
PATCH /products/123    # 更新 ID 为 123 的产品（部分更新）
DELETE /products/123   # 删除 ID 为 123 的产品

（3）无状态（Stateless）

RESTful API 设计要求服务器不存储客户端状态信息，每个请求都必须包含完成该请求所需的所有信息。例如：

• 认证信息通常使用 Token（如 JWT），而不是依赖 Session：

  Authorization: Bearer <token>

• 请求参数应该携带在 URL 或请求体 中，而不是依赖服务器状态。

（4）使用合适的状态码

RESTful API 应该使用标准 HTTP 状态码来反映请求的执行结果：

状态码	说明
200 OK	请求成功（GET、PUT、PATCH、DELETE 成功时）
201 Created	资源创建成功（POST）
204 No Content	请求成功，但没有返回内容（DELETE 成功）
400 Bad Request	客户端请求错误（如参数缺失或格式错误）
401 Unauthorized	认证失败或未提供身份验证信息
403 Forbidden	资源访问被禁止
404 Not Found	资源不存在
409 Conflict	资源冲突（如创建重复数据）
500 Internal Server Error	服务器内部错误

（5）返回合适的数据格式

RESTful API 主要使用 JSON 作为数据交换格式，返回数据应结构化且清晰。例如：

{
  "id": 123,
  "name": "Laptop",
  "price": 999.99,
  "stock": 50
}

推荐的数据返回结构

• 单个资源：

{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com"
}

• 多个资源：

{
  "users": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ],
  "total": 2
}

（6）分页、筛选、排序

对于大量数据，RESTful API 应支持分页、筛选和排序。

分页

使用 limit 和 offset 控制分页：

GET /users?limit=10&offset=20

返回结果：

{
  "users": [
    { "id": 21, "name": "User 21" },
    { "id": 22, "name": "User 22" }
  ],
  "total": 100
}

筛选

按条件筛选数据：

GET /products?category=electronics&min_price=100

排序

按字段排序：

GET /products?sort=price&order=desc

（7）错误处理

API 返回错误时，应该提供详细的错误信息：

{
  "error": "Invalid request",
  "message": "The 'email' field is required",
  "code": 400
}

这样可以帮助客户端更好地处理错误。

（8）使用 HATEOAS

HATEOAS（Hypermedia As The Engine Of Application State）允许 API 在响应中提供相关链接，方便客户端发现可执行的操作。例如：

{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "links": {
    "self": "/users/123",
    "orders": "/users/123/orders"
  }
}

3. RESTful API 设计最佳实践

• 使用 HTTPS 以确保数据传输安全。
• 避免在 URL 中暴露敏感信息，如：

# ❌ 不安全：
GET /users?token=123abc

# ✅ 推荐：
Authorization: Bearer 123abc

保持 API 版本化，如：

GET /v1/users

返回标准时间格式，如 ISO 8601：

"created_at": "2024-02-01T12:00:00Z"

4. RESTful API 设计示例

假设我们要设计一个用户管理 API，遵循 RESTful 规范：

需求	方法	URL	说明
获取所有用户	GET	/users	返回所有用户数据
获取单个用户	GET	/users/{id}	获取 ID 为 {id} 的用户信息
创建用户	POST	/users	创建新用户
更新用户	PUT	/users/{id}	完整更新用户信息
修改用户部分信息	PATCH	/users/{id}	仅修改部分字段
删除用户	DELETE	/users/{id}	删除用户
获取用户的订单	GET	/users/{id}/orders	获取用户的订单

示例请求：

POST /users
Content-Type: application/json

{
  "name": "Alice",
  "email": "alice@example.com",
  "password": "securepassword"
}

返回：

{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "created_at": "2024-02-01T12:00:00Z"
}

5. 总结

RESTful API 设计强调资源、标准 HTTP 方法、无状态交互、清晰的错误处理和一致的 URL 结构。遵循这些最佳实践可以提高 API 的可读性、可维护性和扩展性。