API 设计师

概览

这项技能提供了全面的设计、记录和实现现代 API 的指导。它涵盖了 REST 和 GraphQL 范式，强调行业最佳实践、清晰的文档和可维护的架构。利用这项技能创建可扩展、安全、对开发者友好的生产就绪 API 设计。

核心能力

REST API 设计

以资源为导向的端点设计，具有适当的 URL 结构
HTTP 方法语义和状态码使用
请求/响应有效负载设计，具有一致的命名
分页、过滤和排序策略
错误处理和验证模式

GraphQL API 设计

具有类型系统和关系的模式定义
查询和变更设计，具有适当的输入类型
解析器模式和性能优化
片段使用和指令实现
N+1 问题预防策略

API 文档

OpenAPI 3.0 规范生成
带有 Swagger UI 的交互式文档
认证和授权文档
带有多个场景的示例请求/响应
从规范生成代码

认证与授权

OAuth 2.0 流程（授权码、客户端凭据、PKCE）
JWT 令牌设计、验证和轮换
API 密钥管理和轮换策略
基于角色的访问控制（RBAC）实现
速率限制和节流模式

API 版本控制

URL 版本控制和基于头的版本控制策略
API 版本控制的语义版本控制
弃用计划和沟通
向后兼容性维护
迁移路径设计

使用此技能时

当以下情况时使用此技能：

从头开始设计新 API 或重构现有端点
为文档创建 OpenAPI/Swagger 规范
实施认证和授权流程
规划 API 版本控制和弃用策略
设计 GraphQL 模式和解析器
建立 API 治理和最佳实践

REST API 设计工作流程

第 1 步：确定资源

确定 API 将公开的核心资源（名词）：

资源：用户、帖子、评论

集合：
- GET    /users              （列出所有用户）
- POST   /users              （创建新用户）

单个资源：
- GET    /users/{id}         （获取特定用户）
- PUT    /users/{id}         （替换用户 - 完整更新）
- PATCH  /users/{id}         （更新用户 - 部分）
- DELETE /users/{id}         （删除用户）

嵌套资源：
- GET    /users/{id}/posts   （获取用户的帖子）
- POST   /users/{id}/posts   （为用户创建帖子）

第 2 步：设计 URL 结构

遵循 RESTful 命名约定：

最佳实践：

使用复数名词：/users, /posts（而不是 /user, /post）
对多词使用连字符：/blog-posts（而不是 /blogPosts 或 /blog_posts）
保持 URL 小写
将嵌套限制在最多 2 级
使用查询参数进行过滤：/posts?status=published&author=123

快速示例：

✅ 好的：
GET /users
GET /users/123/posts
GET /posts?published=true&limit=10

❌ 不好的：
GET /getUsers
GET /users/123/posts/comments/likes  （嵌套太深）
GET /posts/published  （使用查询参数代替）

第 3 步：选择 HTTP 方法

将操作映射到标准 HTTP 方法：

GET：检索资源（s）- 安全的，幂等的，可缓存的
POST：创建新资源 - 返回 201 创建带有 Location 头
PUT：替换整个资源 - 幂等的，完全替换
PATCH：部分更新 - 只更新特定字段
DELETE：移除资源 - 幂等的，返回 204 或 200

第 4 步：设计请求/响应有效负载

一致地结构化 JSON 有效负载：

命名约定：

对 JSON 字段名称使用 camelCase
对时间戳使用 ISO 8601（UTC）
使用一致的 ID 格式和前缀：usr_, post_
包括元数据：createdAt, updatedAt

示例响应：

{
  "id": "usr_1234567890",
  "username": "johndoe",
  "email": "john@example.com",
  "profile": {
    "firstName": "John",
    "lastName": "Doe"
  },
  "createdAt": "2025-10-25T10:30:00Z",
  "updatedAt": "2025-10-25T10:30:00Z"
}

第 5 步：实现错误处理

设计全面的错误响应：

错误响应格式：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "email",
        "message": "Email format is invalid"
      }
    ],
    "requestId": "req_abc123xyz",
    "timestamp": "2025-10-25T10:30:00Z"
  }
}

关键状态码：

200 OK：成功的 GET, PUT, PATCH
201 Created：成功的 POST
204 No Content：成功的 DELETE
400 Bad Request：无效的请求数据
401 Unauthorized：缺少/无效的认证
403 Forbidden：已认证但未授权
404 Not Found：资源不存在
422 Unprocessable Entity：验证错误
429 Too Many Requests：速率限制超出
500 Internal Server Error：服务器错误

第 6 步：添加分页和过滤

基于游标的分页（推荐用于大数据集）：

GET /posts?limit=20&cursor=eyJpZCI6MTIzfQ

响应：
{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTQzfQ",
    "hasMore": true
  }
}

基于偏移量的分页（对于小数据集更简单）：

GET /posts?limit=20&offset=40&sort=-createdAt

响应：
{
  "data": [...],
  "pagination": {
    "total": 500,
    "limit": 20,
    "offset": 40
  }
}

有关详细的分页策略和过滤模式，请参见 references/rest_best_practices.md。

GraphQL API 设计工作流程

第 1 步：定义模式类型

为您的领域创建类型定义：

type User {
  id: ID!
  username: String!
  email: String!
  profile: Profile
  posts(limit: Int = 10): [Post!]!
  createdAt: DateTime!
}

type Post {
  id: ID!
  title: String!
  content: String!
  published: Boolean!
  author: User!
  tags: [String!]!
  createdAt: DateTime!
}

第 2 步：设计查询

定义具有过滤的读取操作：

type Query {
  user(id: ID!): User
  post(id: ID!): Post

  users(
    limit: Int = 10
    offset: Int = 0
    search: String
  ): UserConnection!

  posts(
    limit: Int = 10
    published: Boolean
    authorId: ID
    tags: [String!]
  ): PostConnection!
}

第 3 步：设计变更

定义写入操作，输入类型和错误处理：

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

input CreateUserInput {
  username: String!
  email: String!
  password: String!
}

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

有关完整的 GraphQL 模式示例，请参见 examples/graphql_schema.graphql。

认证模式

OAuth 2.0 快速参考

授权码流程（带有后端的 web 应用）：

1. 重定向到 /oauth/authorize 带有 client_id, redirect_uri, scope
2. 用户认证并授权
3. 通过重定向接收授权码
4. 在 /oauth/token 交换代码以获取访问令牌
5. 在 Authorization 头中使用访问令牌

客户端凭据流程（服务到服务）：

POST /oauth/token
{
  "grant_type": "client_credentials",
  "client_id": "CLIENT_ID",
  "client_secret": "SECRET"
}

PKCE 流程（移动/SPA - 对于公共客户端最安全）：

1. 生成 code_verifier 和 code_challenge
2. 请求授权带有 code_challenge
3. 使用 code_verifier 交换代码以获取令牌（不需要 client_secret）

JWT 令牌设计

令牌结构：

{
  "header": { "alg": "RS256", "typ": "JWT" },
  "payload": {
    "sub": "usr_1234567890",
    "iat": 1698336000,
    "exp": 1698339600,
    "scope": ["read:posts", "write:posts"],
    "roles": ["user", "editor"]
  }
}

使用：

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

API 密钥认证

X-API-Key: sk_live_abcdef1234567890

最佳实践：

为不同环境（开发，测试，生产）使用不同的密钥
支持每个账户多个密钥以进行轮换
实施密钥过期和使用日志记录
永远不要在客户端代码中暴露密钥

有关包括刷新令牌、MFA 和安全最佳实践在内的全面认证模式，请参见 references/authentication.md。

API 版本控制策略

URL 版本控制（推荐）

/v1/users
/v2/users

优点：清晰，显式，易于缓存和路由缺点：URL 泛滥，多个代码库

头版本控制

Accept: application/vnd.myapi.v2+json
API-Version: 2

优点：干净的 URL，相同的端点缺点：不太明显，浏览器中测试更难

何时版本控制

创建新版本的原因：

移除端点或字段
更改字段类型或名称
修改认证方法
破坏现有客户端合同

不要版本控制的原因：

添加新的可选字段
添加新的端点
错误修复或性能改进

有关详细的版本控制策略、弃用流程和迁移模式，请参见 references/versioning-strategies.md。

OpenAPI 规范

基本结构

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
  description: API 描述

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: 列出用户
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

components:
  schemas:
    User:
      type: object
      required:
        - username
        - email
      properties:
        id:
          type: string
        username:
          type: string
        email:
          type: string
          format: email

有关完整的 OpenAPI 规范示例，请参见 examples/openapi_spec.yaml。

生成文档

使用辅助脚本来生成和验证规范：

# 从代码生成 OpenAPI 规范
python scripts/api_helper.py generate --input api.py --output openapi.yaml

# 验证现有规范
python scripts/api_helper.py validate --spec openapi.yaml

# 生成文档网站
python scripts/api_helper.py docs --spec openapi.yaml --output docs/

最佳实践总结

一致性

在所有端点中使用一致的命名约定
标准化错误响应格式
在任何地方应用相同的认证模式
使用统一的时间戳格式（ISO 8601 与 UTC）

安全性

生产中始终使用 HTTPS
彻底验证所有输入数据
每个用户/密钥/IP 实施速率限制
为所有端点使用适当的认证
在 URL 或日志中永远不要暴露敏感数据
实施适当的 CORS 配置

性能

对大数据集使用分页
实施缓存头（ETag, Cache-Control）
支持压缩（gzip）
对实时数据使用基于游标的分页
实施字段选择以用于稀疏字段集

文档

使用 OpenAPI 记录所有端点
提供示例请求和响应
文档错误代码和含义
包括认证说明
保持文档与代码同步

可维护性

适当版本控制 API，并提供清晰的弃用时间表
在删除功能之前提供弃用警告
为所有端点编写集成测试
监控 API 使用情况、错误和性能
尽可能保持向后兼容性

常见模式

健康检查

GET /health
响应：{ "status": "ok", "timestamp": "2025-10-25T10:30:00Z" }

批量操作

POST /users/batch
{
  "operations": [
    { "method": "POST", "path": "/users", "body": {...} },
    { "method": "PATCH", "path": "/users/123", "body": {...} }
  ]
}

Webhooks

POST /webhooks/configure
{
  "url": "https://your-app.com/webhook",
  "events": ["user.created", "post.published"],
  "secret": "webhook_secret_key"
}

有关包括幂等性、长运行操作、文件上传和软删除在内的其他模式，请参见 references/common-patterns.md。

快速参考清单

REST 端点设计

[ ] 使用集合的复数名词
[ ] 将 URL 嵌套限制为 2 级
[ ] 使用适当的 HTTP 方法
[ ] 返回正确的状态码
[ ] 实施一致的错误格式
[ ] 为集合添加分页
[ ] 包括过滤和排序
[ ] 使用 OpenAPI 文档记录
[ ] 实施认证
[ ] 添加速率限制

GraphQL 模式设计

[ ] 定义清晰的类型层次结构
[ ] 适当使用可空类型
[ ] 实施分页（连接）
[ ] 设计带有输入类型的变更
[ ] 在负载中返回错误
[ ] 用描述记录模式
[ ] 实施认证/授权
[ ] 优化 N+1 查询（DataLoader）

附加资源

综合参考

references/rest_best_practices.md - 完整的 REST API 模式、状态码和实施细节
references/authentication.md - OAuth 2.0, JWT, API 密钥, MFA 和安全最佳实践
references/versioning-strategies.md - 版本控制方法、弃用和迁移策略
references/common-patterns.md - 健康检查、Webhooks、批量操作等

示例

examples/openapi_spec.yaml - 博客 API 的完整 OpenAPI 3.0 规范
examples/graphql_schema.graphql - 完整的 GraphQL 模式，包括查询、变更和订阅

工具

scripts/api_helper.py - API 规范生成、验证和文档实用工具