name: 设计APIs description: 设计REST和GraphQL API，包括端点、错误处理、版本控制和文档。在创建新API、设计端点、审查API合同或被问及REST、GraphQL或API模式时使用。

设计APIs

API设计工作流程

复制此清单并跟踪进度：

API设计进度：
- [ ] 第1步：定义资源和关系
- [ ] 第2步：设计端点结构
- [ ] 第3步：定义请求/响应格式
- [ ] 第4步：计划错误处理
- [ ] 第5步：添加认证/授权
- [ ] 第6步：用OpenAPI规范文档化
- [ ] 第7步：根据清单验证设计

REST API设计

URL结构

# 基于资源的URL（名词，而不是动词）
GET    /users              # 用户列表
GET    /users/:id          # 获取用户
POST   /users              # 创建用户
PUT    /users/:id          # 替换用户
PATCH  /users/:id          # 更新用户
DELETE /users/:id          # 删除用户

# 嵌套资源
GET    /users/:id/orders   # 用户的订单
POST   /users/:id/orders   # 为用户创建订单

# 查询参数用于过滤/分页
GET    /users?role=admin&status=active
GET    /users?page=2&limit=20&sort=-createdAt

HTTP状态代码

代码	含义	用例
200	正常	成功的GET、PUT、PATCH
201	已创建	成功的POST
204	无内容	成功的DELETE
400	错误请求	无效输入
401	未授权	缺少/无效认证
403	禁止	有效认证，无权限
404	未找到	资源不存在
409	冲突	重复，状态冲突
422	无法处理	验证失败
429	请求过多	速率限制
500	内部错误	服务器错误

响应格式

成功响应：

{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  },
  "meta": {
    "requestId": "abc-123"
  }
}

列表响应带分页：

{
  "data": [...],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "totalPages": 5
  },
  "links": {
    "self": "/users?page=1",
    "next": "/users?page=2",
    "last": "/users?page=5"
  }
}

错误响应：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "无效的输入数据",
    "details": [
      {
        "field": "email",
        "message": "必须是有效的电子邮件地址"
      }
    ]
  },
  "meta": {
    "requestId": "abc-123"
  }
}

API版本控制

URL版本控制（推荐）：

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

头部版本控制：

Accept: application/vnd.api+json; version=1

认证模式

JWT Bearer Token：

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API密钥：

X-API-Key: your-api-key

速率限制头部

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200
Retry-After: 60

GraphQL模式

模式设计：

type Query {
  user(id: ID!): User
  users(filter: UserFilter, pagination: Pagination): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): UserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UserPayload!
}

type User {
  id: ID!
  name: String!
  email: String!
  orders(first: Int, after: String): OrderConnection!
}

input CreateUserInput {
  name: String!
  email: String!
}

type UserPayload {
  user: User
  errors: [Error!]
}

OpenAPI规范模板

见OPENAPI-TEMPLATE.md以获取完整的OpenAPI 3.0规范模板。

API设计验证

设计完成后，根据此清单进行验证：

验证清单：
- [ ] 所有端点使用名词，而不是动词
- [ ] HTTP方法与操作正确匹配
- [ ] 端点间一致的响应格式
- [ ] 错误响应包括可操作的细节
- [ ] 列表端点实现分页
- [ ] 保护端点定义认证
- [ ] 文档化速率限制头部
- [ ] OpenAPI规范完整且有效

如果验证失败，请返回相关设计步骤并解决问题。

安全清单

[ ] 仅HTTPS
[ ] 所有端点认证
[ ] 授权检查
[ ] 输入验证
[ ] 速率限制
[ ] 请求大小限制
[ ] CORS正确配置
[ ] URL中无敏感数据
[ ] 审计日志