api-patterns

# API 模式 > 2025 年 API 设计原则与决策。 > **学会思考，而不是复制固定的模式。** ## ? 选择性阅读规则 **仅阅读与请求相关的文件！** 查看内容地图，找到你需要的内容。 --- ## ? 内容地图 | 文件 | 描述 | 阅读时机 | |------|-------------|--------------| | `api-style.md` | REST vs GraphQL vs tRPC 决策树 | 选择 API 类型时 | | `rest.md` | 资源命名，HTTP 方法，状态码 | 设计 REST API 时 | | `response.md` | 信封模式，错误格式，分页 | 响应结构设计时 | | `graphql.md` | Schema 设计，使用场景，安全性 | 考虑 GraphQL 时 | | `trpc.md` | TypeScript monorepo，类型安全 | TS 全栈项目时 | | `versioning.md` | URI/Header/Query 版本控制 | API 演进规划时 | | `auth.md` | JWT, OAuth, Passkey, API Keys | 认证模式选择时 | | `rate-limiting.md` | 令牌桶，滑动窗口 | API 保护时 | | `documentation.md` | OpenAPI/Swagger 最佳实践 | 文档编写时 | | `security-testing.md` | OWASP API Top 10，认证/授权测试 | 安全审计时 | --- ## ? 相关技能 | 需求 | 技能 | |------|-------| | API 实现 | `@[skills/backend-development]` | | 数据结构 | `@[skills/database-design]` | | 安全细节 | `@[skills/security-hardening]` | --- ## ✅ 决策清单 在设计 API 之前： - [ ] **是否询问过用户关于 API 消费者的信息？** - [ ] **是否为当前上下文选择了 API 风格？** (REST/GraphQL/tRPC) - [ ] **是否定义了统一的响应格式？** - [ ] **是否规划了版本控制策略？** - [ ] **是否考虑了认证需求？** - [ ] **是否规划了速率限制？** - [ ] **是否定义了文档编写方法？** --- ## ❌ 反模式 **不要：** - 默认对所有场景使用 REST - 在 REST 端点中使用动词 (/getUsers) - 返回不一致的响应格式 - 向客户端暴露内部错误 - 跳过速率限制 **要：** - 根据上下文选择 API 风格 - 询问客户端需求 - 详尽记录文档 - 使用适当的状态码 --- ## 脚本 | 脚本 | 用途 | 命令 | |--------|---------|---------| | `scripts/api_validator.py` | API 端点验证 | `python scripts/api_validator.py ` |