api-patterns 是做什么的？
API 设计原则与决策指南：涵盖 REST、GraphQL 与 tRPC 的选择、响应格式、版本控制及分页策略。
核心原则
- 一致性：保持 API 行为与命名规则一致。
- 可扩展性：设计时考虑未来的迭代与版本管理。
- 面向客户端：根据客户端使用场景选择最优的交互模式。
协议对比
| 特性 | REST | GraphQL | tRPC |
|---|---|---|---|
| 数据获取 | 多端点，按资源获取 | 单一端点，客户端指定字段 | 函数调用式，类型安全 |
| 类型安全 | 依赖工具/文档 | 通过 Schema 实现 | 原生类型安全（全栈） |
| 缓存 | HTTP 原生缓存支持 | 需手动实现 | 需自定义缓存策略 |
| 适用场景 | 标准 CRUD 与资源型 API | 复杂数据聚合与灵活查询 | 全栈 TypeScript 项目 |
响应格式
推荐使用统一的 JSON 响应结构：
{
"success": true,
"data": {},
"error": null,
"meta": {
"timestamp": "2024-01-01T00:00:00Z",
"requestId": "abc123"
}
}
版本控制策略
- URI 路径版本化（如
/v1/resource）：简单直接，但可能导致重复代码。 - 请求头版本化（如
Accept: application/vnd.api+json;version=1）：更优雅，但实现复杂度稍高。 - 查询参数版本化（如
?version=1）：不推荐，容易造成混淆。
分页模式
- 基于游标的分页（Cursor-based）：推荐用于实时数据与性能敏感场景。
- 基于偏移的分页（Offset-based）：适用于简单列表，但大偏移量下性能较差。
- 基于时间戳的分页：适合按时间顺序排列的日志或事件数据。
示例：游标分页响应
{
"data": [...],
"pagination": {
"cursor": "next_cursor_value",
"hasMore": true,
"total": 100
}
}