RESTful API 设计原则

RESTful API 是现代 Web 应用的基础。本文总结了设计优雅、易用、可维护的 RESTful API 的最佳实践。

1. 资源命名规范

使用名词复数形式表示资源：

✅ 推荐
GET    /api/users          # 获取用户列表
GET    /api/users/123      # 获取特定用户
POST   /api/users          # 创建用户
PUT    /api/users/123      # 更新用户
DELETE /api/users/123      # 删除用户

❌ 不推荐
GET /api/getUsers
POST /api/createUser
POST /api/user/delete/123

2. HTTP 方法使用

正确使用 HTTP 动词：

• GET: 获取资源（幂等、安全）
• POST: 创建资源
• PUT: 完整更新资源（幂等）
• PATCH: 部分更新资源
• DELETE: 删除资源（幂等）

3. HTTP 状态码

使用语义化的状态码：

// 成功响应
200 OK           - GET、PUT、PATCH 成功
201 Created      - POST 创建成功
204 No Content   - DELETE 成功

// 客户端错误
400 Bad Request      - 请求参数错误
401 Unauthorized     - 未认证
403 Forbidden        - 无权限
404 Not Found        - 资源不存在
409 Conflict         - 资源冲突
422 Unprocessable    - 验证失败

// 服务器错误
500 Internal Server Error
503 Service Unavailable

4. 请求和响应格式

统一的 JSON 响应格式：

// 成功响应
{
  "data": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com"
  },
  "meta": {
    "timestamp": "2024-12-03T10:00:00Z"
  }
}

// 错误响应
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  }
}

5. 分页、过滤和排序

使用查询参数实现：

// 分页
GET /api/users?page=1&size=20

// 过滤
GET /api/users?status=active&role=admin

// 排序
GET /api/users?sort=createdAt:desc,name:asc

// 字段选择
GET /api/users?fields=id,name,email

分页响应格式：

{
  "data": [...],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 150,
    "pages": 8
  }
}

6. API 版本管理

三种常见的版本管理方式：

// 1. URL 路径版本（推荐）
GET /api/v1/users
GET /api/v2/users

// 2. 请求头版本
GET /api/users
Accept: application/vnd.myapi.v1+json

// 3. 查询参数版本
GET /api/users?version=1

7. 认证和授权

使用 JWT 或 OAuth 2.0：

// JWT 认证
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

// API Key
X-API-Key: your-api-key-here

8. 速率限制

通过响应头告知客户端限流信息：

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1543489787

9. HATEOAS

在响应中包含相关资源链接：

{
  "id": 123,
  "name": "John Doe",
  "_links": {
    "self": "/api/users/123",
    "orders": "/api/users/123/orders",
    "avatar": "/api/users/123/avatar"
  }
}

10. 文档化

使用 OpenAPI/Swagger 生成交互式文档：

/**
 * @swagger
 * /api/users:
 *   get:
 *     summary: Get all users
 *     parameters:
 *       - name: page
 *         in: query
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: Success
 */

实战示例

设计一个电商 API：

// 商品管理
GET    /api/v1/products
GET    /api/v1/products/123
POST   /api/v1/products
PUT    /api/v1/products/123
DELETE /api/v1/products/123

// 嵌套资源
GET    /api/v1/products/123/reviews
POST   /api/v1/products/123/reviews

// 批量操作
POST   /api/v1/products/batch
DELETE /api/v1/products/batch

总结

优秀的 API 设计需要考虑易用性、一致性、可扩展性和安全性。遵循这些最佳实践，可以设计出开发者友好的 RESTful API。