API 设计
服务与消费者间的契约——为稳定、清晰和演进设计。
为什么
API 是比内部函数难改得多的发布接口——每个破坏性变更同时破坏每个消费者。好 API 设计（一致命名、版本、分页、错误模型）让 API 几分钟可学、数年可演不破客户端。差 API 设计逼每个消费者写脆弱胶水代码，让每次改进成协调迁移。API 也是开发者真读的文档；清晰的把集成支持工单降一个数量级。
何时使用
任何消费者集成前。核心契约 1-2 天。每主版本重访。
如何做
1. 选风格：REST（资源导向）、gRPC（性能+类型）、GraphQL（灵活读）
- 默认 REST 除非有特定理由
2. 资源用名词（/users、/orders/{id}），动作用子资源（/orders/{id}/cancel）
3. 一致用标准动词（GET/POST/PUT/PATCH/DELETE）；别重载 POST
4. 分页：大列表用游标（offset 在插入下会破）
5. 错误：一致 {code, message, details} 信封 + 标准 HTTP 状态
6. 版本：/v1/ 前缀；版本内永不破坏，变更加新端点
7. 用 OpenAPI 文档；从 spec 生成客户端，非手写
8. 任何非安全 POST（支付、发送）加幂等键示例
POST /v1/orders
body: { user_id, items[], idempotency_key }
201 → { id, status, total, created_at }
409 → { code: "DUPLICATE", message: "idempotency_key 已用", details: { existing_id } }
GET /v1/orders?cursor=abc&limit=20
200 → { items[], next_cursor }
错误信封（所有端点一致）：
{ "code": "VALIDATION_ERROR", "message": "items 必填", "details": { "field": "items" } }常见问题
- ⚠用 offset/limit 分页——页间插入时跳行或重行；用游标。
最佳实践
- ✓版本内永不删字段——弃用（仍返回）并在下主版本删。
- ✓把 OpenAPI spec 当事实来源；代码与 spec 不符时 spec 胜，代码是 bug。