api-design-patterns

API 设计模式

资源命名

• 使用复数名词：/users、/orders、/products
• 按关系嵌套：/users/{id}/orders
• 最大嵌套深度：2 层。超过此深度时，使用查询参数或顶层资源
• 使用 kebab-case：/user-profiles，而不是 /userProfiles
• URL 中绝不使用动词：/users/{id}/activate 是错误的，应使用 POST /users/{id}/activation

HTTP 方法

方法	用途	幂等	请求正文	成功代码
GET	读取资源	是	否	200
POST	创建资源	否	是	201
PUT	完全替换	是	是	200
PATCH	部分更新	否	是	200
DELETE	删除资源	是	否	204

POST 请求应返回 Location 标头，其中包含已创建资源的 URL。

状态代码

200 OK              - Successful read/update
201 Created         - Successful creation
204 No Content      - Successful delete
400 Bad Request     - Validation error (include field-level errors)
401 Unauthorized    - Missing or invalid authentication
403 Forbidden       - Authenticated but not authorized
404 Not Found       - Resource does not exist
409 Conflict        - State conflict (duplicate, version mismatch)
422 Unprocessable   - Semantically invalid (valid JSON, bad values)
429 Too Many Reqs   - Rate limited (include Retry-After header)
500 Internal Error  - Unhandled server error (never expose stack traces)

错误响应格式

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Must be a valid email address" },
      { "field": "age", "message": "Must be at least 18" }
    ]
  }
}

在整个 API 中使用一致的错误代码。在 API 参考文档中记录每个代码。

基于游标的分页（首选）

GET /users?limit=20&cursor=eyJpZCI6MTAwfQ

Response:
{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIwfQ",
    "has_more": true
  }
}

对于大型或经常变化的数据集，使用游标分页。将游标编码为不透明的 base64 字符串。绝不在游标中暴露原始 ID。

基于偏移量的分页（仅限简单场景）

GET /users?page=3&per_page=20

Response:
{
  "data": [...],
  "pagination": {
    "page": 3,
    "per_page": 20,
    "total": 245,
    "total_pages": 13
  }
}

仅当总数计算成本低且数据集较小时，才使用偏移量分页。

筛选与排序

GET /orders?status=pending&created_after=2025-01-01&sort=-created_at,+total
GET /products?category=electronics&price_min=100&price_max=500
GET /users?search=john&fields=id,name,email

使用字段选择（fields 参数）来减小负载大小。降序排序时，在排序字段前加上 -。

版本控制

为简洁起见，优先使用 URL 路径版本控制：

/api/v1/users
/api/v2/users

规则：

• 发布后绝不破坏 v1。可以添加字段，但不要删除字段。
• 新增必填字段 = 新版本
• 使用 Sunset 标头和 6 个月的通知期弃用旧版本
• 同时最多支持 2 个活跃版本

请求／响应标头

Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>
X-Request-Id: <uuid>          # For tracing
X-RateLimit-Limit: 100        # Requests per window
X-RateLimit-Remaining: 47     # Remaining in window
X-RateLimit-Reset: 1700000000 # Window reset Unix timestamp
Retry-After: 30               # Seconds until rate limit resets

响应中始终返回 X-Request-Id，以便进行调试。

OpenAPI 规范指南

• 先编写规范，再进行实现（规范驱动开发）
• 使用 $ref 引用共享架构：$ref: '#/components/schemas/User'
• 为每个端点定义 examples
• 对多态响应使用 oneOf／anyOf
• 根据规范生成客户端 SDK，绝不手动编写
• 在中间件中根据规范验证请求

paths:
  /users/{id}:
    get:
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'

速率限制策略

• 按用户和端点分别设置限制
• 使用滑动窗口算法（而不是固定窗口）
• 返回 429 和 Retry-After 标头
• 健康检查和身份验证端点不受速率限制
• 记录受到速率限制的请求，以便检测滥用