api-design

API 设计

为 REST、GraphQL、gRPC 和 CLI 接口设计一致且文档完善的 API。

适用场景

• 设计新的 API 端点或命令
• 检查现有 API 契约的一致性
• 制定 API 命名和版本控制规范
• 规划向后兼容的 API 变更
• 生成 API 文档或 OpenAPI 规范

原则

1. 一致性 - 各处采用相同模式（命名、错误格式、分页）
2. 易于发现 - 开发者无需阅读文档，也能猜到正确的端点或标志
3. 向后兼容 - 添加内容是安全的；移除和重命名需要进行版本控制
4. 精简接口 - 仅公开使用者需要的内容；内部细节应保留在内部
5. 错误自描述 - 错误响应应告知调用方出了什么问题，以及如何修复

REST API 检查清单

命名

• 资源使用复数名词：/users、/tasks
• 多词路径使用 kebab-case：/user-settings
• 表示归属关系时使用嵌套路径：/users/{id}/tasks
• 仅在操作无法映射到 CRUD 时使用动词：/tasks/{id}/approve

HTTP 方法

方法	用途	幂等
GET	读取	是
POST	创建 / 操作	否
PUT	完全替换	是
PATCH	部分更新	是
DELETE	删除	是

响应格式

{
  "data": { ... },
  "meta": { "page": 1, "total": 42 }
}

错误格式：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      { "field": "email", "reason": "required" }
    ]
  }
}

状态码

代码	用途
200	成功（带响应正文）
201	已创建
204	成功（无响应正文）
400	客户端错误（验证失败）
401	未通过身份验证
403	未获授权
404	未找到
409	冲突（重复、状态不匹配）
422	无法处理（语义无效）
500	服务端错误

分页

大型数据集使用基于游标的分页；简单场景使用基于偏移量的分页：

GET /tasks?cursor=abc123&limit=20
GET /tasks?page=2&per_page=20

版本控制

• 优先使用 URL 前缀：/v1/tasks、/v2/tasks
• 仅在 URL 版本控制不切实际时使用基于标头的版本控制

CLI API 检查清单

命令结构

<tool> <noun> <verb> [args] [--flags]

示例：synapse send gemini "Review code" --wait

标志约定

• 长格式：--output、--verbose
• 常用标志使用短格式：-o、-v
• 布尔标志：--force、--no-color
• 可重复使用：--attach file1 --attach file2
• 互斥组选项：--wait | --notify | --silent

输出

• 默认：便于人类阅读
• --json：机器可读的 JSON
• --quiet / -q：最简输出
• 退出码：0 = 成功，1 = 错误，2 = 用法错误

工作流

步骤 1：定义资源 / 命令

列出 API 必须支持的实体和操作。

步骤 2：映射到端点 / 子命令

应用命名约定，确定 API 接口。

步骤 3：定义请求 / 响应架构

指定必需和可选字段、类型及验证规则。

步骤 4：记录错误情况

为每个端点列出可能的错误响应及其含义。

步骤 5：检查一致性

交叉检查所有端点的命名、错误格式和分页方式。