api-design

API 设计

概述

通过引导式探索设计结构化 API 端点。生成一致且文档完善的 API 设计，并提供 OpenAPI/Swagger 规范。涵盖资源建模、身份验证、分页、错误处理和版本控制，确保在开始实现之前以消费者为中心进行设计。

开始时声明：“我正在使用 api-design 技能来设计 API。”

阶段 1：探索

每次只问一个问题：

资源问题

#	问题	确定内容
1	此 API 管理哪些实体/资源？	资源命名
2	它们之间存在什么关系？	嵌套路由、包含项
3	每种资源需要哪些操作？（CRUD、搜索、批量操作）	HTTP 方法、端点

消费者问题

#	问题	确定内容
4	谁会使用此 API？（前端、移动端、第三方、内部）	响应结构、身份验证模型
5	需要哪些身份验证/授权机制？	安全方案
6	适用哪些速率限制或配额？	速率限制标头

约束问题

#	问题	确定内容
7	REST、GraphQL 还是 tRPC？	API 范式
8	版本控制策略是什么？（URL 路径、标头、查询参数）	URL 结构
9	采用哪种分页方式？（游标、偏移量、键集）	列表响应结构
10	代码库中现有的 API 约定是什么？	一致性约束

API 范式决策表

因素	选择 REST	选择 GraphQL	选择 tRPC
消费者	多样化的多个消费者	以为前端服务为主，查询灵活	TypeScript 单体仓库
缓存需求	强（HTTP 缓存）	中等（客户端缓存）	低（仅限内部）
数据结构	可预测、以资源为导向	嵌套、结构可变	类型安全的 RPC
团队熟悉度	普遍	需要了解 schema	需要使用 TypeScript
实时需求	WebSocket 插件	内置订阅	支持订阅

探索结束后停止——总结资源、操作和约束。获得确认后再设计端点。

阶段 2：设计端点

为每个端点定义：

### [METHOD] /api/v1/[resource]

**Purpose:** [what this endpoint does]

**Request:**
- Headers: `Authorization: Bearer <token>`
- Query params: `?page=1&limit=20&sort=created_at:desc`
- Body:
  ```json
  {
    "field": "type — description"
  }

响应（200）：

{
  "data": [...],
  "meta": { "total": 100, "page": 1, "limit": 20 }
}

错误响应：

状态码	代码	描述
400	VALIDATION_ERROR	请求正文无效
401	UNAUTHORIZED	缺少令牌或令牌无效
404	NOT_FOUND	资源不存在
409	CONFLICT	资源已存在

授权：[谁可以访问此端点]

### HTTP Method Decision Table

| Operation | Method | Status (success) | Idempotent |
|-----------|--------|-----------------|------------|
| List resources | GET | 200 | Yes |
| Get single resource | GET | 200 | Yes |
| Create resource | POST | 201 | No |
| Full replace | PUT | 200 | Yes |
| Partial update | PATCH | 200 | No |
| Delete resource | DELETE | 204 | Yes |
| Bulk create | POST | 201 | No |
| Search (complex) | POST | 200 | Yes (safe) |

### Pagination Decision Table

| Approach | When to Use | Pros | Cons |
|----------|------------|------|------|
| **Cursor** | Real-time feeds, large datasets | Consistent, no skipping | Cannot jump to page N |
| **Offset** | Small datasets, admin panels | Simple, jumpable | Skips/duplicates on insert |
| **Keyset** | Time-series, logs | Efficient on large tables | Requires sortable key |

### Error Response Format

All endpoints must use a consistent error shape:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

状态码参考

代码	含义	使用场景
200	成功	GET、PUT、PATCH 成功
201	已创建	POST 成功并创建资源
204	无内容	DELETE 成功
400	错误请求	验证失败
401	未授权	缺少凭据或凭据无效
403	禁止访问	凭据有效，但权限不足
404	未找到	资源不存在
409	冲突	重复项或状态冲突
422	无法处理的实体	JSON 有效，但存在语义错误
429	请求过多	超出速率限制
500	内部服务器错误	服务器发生意外故障

端点设计完成后停止——逐一提交端点以供审查和批准。

阶段 3：生成 OpenAPI 规范

openapi: 3.1.0
info:
  title: [API Name]
  version: 1.0.0
  description: [API description]

servers:
  - url: http://localhost:3000/api/v1
    description: Development
  - url: https://api.example.com/v1
    description: Production

paths:
  /resource:
    get:
      summary: List resources
      parameters: [...]
      responses: [...]
    post:
      summary: Create resource
      requestBody: [...]
      responses: [...]

components:
  schemas: [...]
  securitySchemes: [...]

规范生成后停止——验证 YAML 并提交以供最终批准。

阶段 4：保存并过渡

获得明确批准后：

1. 将 OpenAPI 规范保存到 docs/api/YYYY-MM-DD-<api-name>.yaml
2. 使用提交消息：docs(api): add OpenAPI spec for <api-name>
3. 根据用户意图确定下一步

转换决策表

用户意图	下一项技能	理由
“我们来实现这个”	planning	根据 API 规范制定实现计划
“为此编写规范”	spec-writing	为每个端点编写行为规范
“生成客户端 SDK”	手动	使用 OpenAPI 代码生成工具
“只保存设计”	无	API 设计本身就是交付成果
“添加测试”	testing-strategy	定义 API 测试方案

设计原则

原则	规则
命名一致	集合使用复数名词（/users，而不是 /user）
正确使用 HTTP 方法	GET 用于读取，POST 用于创建，PUT 用于替换，PATCH 用于更新，DELETE 用于删除
使用正确的状态码	针对不同情况使用正确的状态码（见上表）
错误格式一致	所有端点使用相同的错误结构
默认分页	所有列表端点都应分页
筛选和排序	列表端点使用查询参数
幂等性	PUT 和 DELETE 始终具有幂等性
HATEOAS	包含链接以便于发现（适用时）

反模式 / 常见错误

错误	错误原因	应采取的做法
URL 使用动词（/getUsers）	不符合 REST 风格，违反惯例	使用名词：GET /users
单复数使用不一致	让使用者困惑	集合名称始终使用复数
错误时返回 200	向客户端掩盖失败	使用正确的状态码
列表端点没有分页	大数据集上的性能隐患	始终进行分页
每个端点使用不同的错误格式	客户端无法构建通用错误处理	所有端点使用统一的错误结构
在 URL 中暴露内部 ID	存在安全和耦合风险	使用 UUID 或 slug
没有版本控制策略	破坏性变更会影响客户端	从第一天起就进行版本控制
不了解使用者就进行设计	API 无法很好地服务任何人	先进行探索阶段

防止自我合理化的规则

• 不要跳过探索阶段——先了解使用者和限制条件
• 不要在未定义错误响应的情况下设计端点
• 不要跳过任何列表端点的分页
• 不要在各个端点中使用不一致的命名
• 不要在用户批准端点设计之前生成 OpenAPI 规范
• 不要在没有明确理由的情况下混用 API 范式（REST + GraphQL）

集成点

技能	关系
spec-writing	下游：API 设计为行为规范提供依据
planning	下游：API 端点转化为实现任务
tech-docs-generator	下游：OpenAPI 规范用于生成 API 参考文档
testing-strategy	下游：API 设计为集成测试策略提供依据
security-review	下游：审查 auth/authz 模型是否存在漏洞
database-schema-design	上游：数据模型为资源设计提供依据
prd-generation	上游：PRD 需求推动 API 资源识别

验证关卡

在宣称 API 设计完成之前：

1. 验证所有端点都定义了请求/响应架构
2. 验证所有错误响应都以一致的格式记录
3. 验证每个端点都指定了身份验证方式
4. 验证所有列表端点都定义了分页
5. 验证 OpenAPI 规范是有效的 YAML
6. 验证用户已逐一批准各个端点

技能类型

灵活——根据项目需求调整 API 范式、分页风格和身份验证模型，同时保留优先探索的方法、一致的错误处理和以使用者为中心的设计原则。