RESTful API 设计规范

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。