api-design-patterns

API 设计模式

构建一致且对开发者友好的 API 的 RESTful API 设计原则。包含 7 个类别的 38 条规则，涵盖资源设计、错误处理、安全性、分页、版本控制、响应格式和文档。

元数据

• 版本： 2.0.0
• 规则数量： 7 个类别共 38 条规则
• 许可证： MIT

适用场景

在以下情况下可参考这些指南：

• 设计新的 API 端点
• 审查现有 API 结构
• 实施错误处理和验证
• 设置分页、筛选和排序
• 规划 API 版本控制策略
• 配置 API 安全性（身份验证、CORS、速率限制）
• 编写 API 文档（OpenAPI/Swagger）

按优先级划分的规则类别

优先级	类别	影响	前缀
1	资源设计	严重	rest-
2	错误处理	严重	error-
3	安全性	严重	sec-
4	分页与筛选	高	page-、filter-、sort-
5	版本控制	高	ver-
6	响应格式	中	resp-
7	文档	中	doc-

快速参考

1. 资源设计（严重）

• rest-nouns-not-verbs - 端点使用名词，而非动词
• rest-plural-resources - 使用复数资源名称
• rest-http-methods - 正确使用 HTTP 方法（GET、POST、PUT、PATCH、DELETE）
• rest-nested-resources - 正确嵌套资源（最多 2 层）
• rest-status-codes - 使用恰当的 HTTP 状态码
• rest-idempotency - 使用幂等键实现幂等操作
• rest-hateoas - 使用超媒体链接以便于发现
• rest-resource-actions - 将非 CRUD 操作作为子资源

2. 错误处理（严重）

• error-consistent-format - 保持错误响应结构一致
• error-meaningful-messages - 提供有帮助且可操作的错误消息
• error-validation-details - 提供字段级验证错误
• error-error-codes - 提供机器可读的错误代码
• error-no-stack-traces - 绝不在生产环境中暴露堆栈跟踪
• error-request-id - 包含请求 ID 以便调试

3. 安全性（严重）

• sec-authentication - 正确实施身份验证（OAuth2/JWT）
• sec-authorization - 设置资源级权限（RBAC）
• sec-rate-limiting - 通过速率限制防止滥用
• sec-input-validation - 验证并清理所有输入
• sec-cors-config - 使用白名单配置 CORS
• sec-https-only - 强制所有流量使用 HTTPS
• sec-sensitive-data - 保护密码、令牌和个人身份信息

4. 分页与筛选（高）

• page-cursor-based - 对大型数据集使用游标分页
• page-offset-based - 在简单场景中使用偏移分页
• page-consistent-params - 保持参数命名一致
• page-metadata - 在响应中包含分页元数据
• filter-query-params - 通过查询参数进行筛选
• sort-flexible - 支持灵活排序，使用 - 前缀表示降序

5. 版本控制（高）

• ver-url-path - 在 URL 路径中指定版本（/api/v1/）
• ver-header-based - 通过 Accept 标头指定版本
• ver-backward-compatible - 保持向后兼容
• ver-deprecation - 使用 Sunset 标头制定弃用策略

6. 响应格式（中）

• resp-consistent-structure - 保持响应封装结构一致
• resp-json-conventions - 遵循 JSON 命名约定
• resp-partial-responses - 支持选择字段（稀疏字段集）
• resp-compression - 压缩响应（gzip/Brotli）

7. 文档（中）

• doc-openapi - 提供 OpenAPI/Swagger 规范
• doc-examples - 提供请求/响应示例
• doc-changelog - 提供 API 更新日志

基本指南

资源命名

# ❌ Verbs in URLs
GET    /getUsers
POST   /createUser

# ✅ Nouns with HTTP methods
GET    /users          # List users
POST   /users          # Create user
GET    /users/123      # Get user
PUT    /users/123      # Update user (full)
PATCH  /users/123      # Update user (partial)
DELETE /users/123      # Delete user

错误响应格式

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid data",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Please provide a valid email address"
      }
    ],
    "request_id": "req_abc123"
  }
}

分页

{
  "data": [...],
  "meta": {
    "current_page": 2,
    "per_page": 20,
    "total_pages": 10,
    "total_count": 195
  },
  "links": {
    "first": "/users?page=1&per_page=20",
    "prev": "/users?page=1&per_page=20",
    "next": "/users?page=3&per_page=20",
    "last": "/users?page=10&per_page=20"
  }
}

速率限制标头

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1640995200

使用方法

阅读各条规则文件，了解详细说明：

rules/rest-http-methods.md
rules/error-consistent-format.md
rules/page-cursor-based.md
rules/sec-authentication.md
rules/ver-url-path.md
rules/doc-openapi.md

参考资料

• RESTful API 指南
• Zalando RESTful API 指南
• Microsoft API 指南
• Google API 设计指南
• OpenAPI 规范

完整编译文档

完整指南（包含展开后的所有规则）：AGENTS.md