api-designer

API 设计师

擅长设计健壮、可扩展且易于维护的 REST 和 GraphQL API。

此技能的激活时机

在以下情况下激活：

• 设计新 API
• 审查 API 设计
• 改进现有 API
• 创建 API 规范

REST API 设计原则

1. 面向资源的设计

推荐：

GET    /users          # List users
POST   /users          # Create user
GET    /users/{id}     # Get specific user
PATCH  /users/{id}     # Update user
DELETE /users/{id}     # Delete user

避免：

POST   /getUsers       # Should be GET
POST   /users/create  # Redundant
GET    /users/get/{id} # Redundant

2. HTTP 方法

方法	安全	幂等	用途
GET	✓	✓	读取资源
POST	✗	✗	创建资源
PUT	✗	✓	替换资源
PATCH	✗	✗	更新资源
DELETE	✗	✓	删除资源

3. 状态码

代码	含义	用法
200	成功	GET、PATCH、DELETE 请求成功
201	已创建	POST 请求成功
204	无内容	DELETE 请求成功且无响应正文
400	错误请求	输入无效
401	未授权	缺少身份验证信息或身份验证信息无效
403	禁止访问	已通过身份验证，但未获授权
404	未找到	资源不存在
409	冲突	资源已存在
422	无法处理	语法有效，但存在语义错误
429	请求过多	超出速率限制
500	服务器内部错误	服务器错误

4. 命名约定

• URL：kebab-case（/user-preferences）
• JSON：camelCase（{"userId": "123"}）
• 查询参数：snake_case 或 camelCase（?page_size=10）

5. 分页

GET /users?page=1&page_size=20

Response:
{
  "data": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 100,
    "total_pages": 5
  }
}

6. 筛选与排序

GET /users?status=active&sort=-created_at,name

# -created_at = descending
# name = ascending

GraphQL API 设计

架构设计

type Query {
  user(id: ID!): User
  users(limit: Int, offset: Int): UserConnection!
}

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

type User {
  id: ID!
  email: String!
  profile: Profile
  posts(first: Int, after: String): PostConnection!
}

type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
}

type UserEdge {
  node: User!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

最佳实践

• 可空性：默认使用非空类型，仅在适当时使用可空类型
• 连接：列表使用基于游标的分页
• 负载：使用变更负载，以便统一处理错误
• 描述：为所有类型和字段编写文档

API 版本控制

方式

URL 版本控制（推荐）：

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

标头版本控制：

GET /users
Accept: application/vnd.myapi.v2+json

版本控制指南

• 从 v1 开始
• 尽可能保持向后兼容
• 提前通知用户弃用旧版本
• 记录会造成不兼容的变更

身份验证与授权

身份验证方式

1. JWT Bearer Token

Authorization: Bearer <token>

2. API Key

X-API-Key: <key>

3. OAuth 2.0

Authorization: Bearer <access_token>

授权

• 使用角色/权限
• 记录各端点所需的权限
• 授权失败时返回 403

速率限制

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1631234567

建议的限制：

• 公共 API：每小时 100-1000 次请求
• 已通过身份验证的 API：每小时 1000-10000 次请求
• Webhook：每分钟 10-100 次请求

文档要求

• 记录所有端点
• 请求/响应示例
• 身份验证要求
• 错误响应格式
• 速率限制
• SDK 示例（如有）

脚本

生成 API 脚手架：

python3 scripts/generate_api.py --name <resource-name> --output api-design.md

验证 API 设计：

python3 scripts/validate_api.py --input api-design.md

参考资料

• references/rest-patterns.md - REST 设计模式
• references/graphql-patterns.md - GraphQL 设计模式
• REST API 教程
• GraphQL 最佳实践