api-design

Topics in the source

• API 设计模式
• 何时启用
• 资源设计
• URL 结构
• 命名规则
• HTTP 方法和状态码
• 方法语义
• 状态码参考

用于设计一致、对开发者友好的 REST API 的约定和最佳实践。 设计新的 API 端点时 审查现有的 API 契约时 添加分页、过滤或排序功能时 为 API 实现错误处理时 规划 API 版本策略时 构建面向公众或合作伙伴的 API 时 | 方法 | 幂等性 | 安全性 | 用途 | |--------|-----------|------|---------| | GET | 是 | 是 | 检索资源 | | POST | 否 | 否 | 创建资源，触发操作 | | PUT | 是 | 否 | 完全替换资源 | | PATCH | 否\ | 否 | 部分更新资源 | | DELETE | 是 | 否 | 删除资源 | \通过适当的实现，PATCH 可以实现幂等 优点： 易于实现，支持“跳转到第 N 页” 缺点： 在大偏移量时速度慢（例如 OFFSET 100000），并发插入时结果不一致 优点： 无论位置如何，性能一致；在并发插入时结果稳定 缺点： 无法跳转到任意页面；游标是不透明的 | 用例 | 分页类型 | |----------|----------------| | 管理仪表板，小数据集 (<10K) | 偏移量 | | 无限滚动，信息流，大数据集 | 游标 | | 公共 API | 游标（默认）配合偏移量（可选） | | 搜索结果 | 偏移量（用户期望有页码） | | 层级 | 限制 | 时间窗口 | 用例 | |------|-------|--------|----------| | 匿名用户 | 30/分钟 | 每个 IP | 公共端点 | | 认证用户 | 100/分钟 | 每个用户 | 标准 API 访问 | | 高级用户 | 1000/分钟 | 每个 API 密钥 | 付费 API 套餐 | | 内部服务 | 10000/分钟 | 每个服务 | 服务间调用 | 优点： 明确，易于路由，可缓存 缺点： 版本间 URL 会变化 优点： URL 简洁 缺点： 测试更困难，容易忘记 发布新端点前请检查： \[ ] 资源 URL 遵循命名约定（复数、短横线连接、不含动词） \[ ] 使用了正确的 HTTP 方法（GET 用于读取，POST 用于创建等） \[ ] 返回了适当的状态码（不要所有情况都返回 200） \[ ] 使用模式（Zod, Pydantic, Bean Validation）验证了输入 \[ ] 错误响应遵循带代码和消息的标准格式 \[ ] 列表端点实现了分页（游标或偏移量） \[ ] 需要认证（或明确标记为公开） \[ ] 检查了授权（用户只能访问自己的资源） \[ ] 配置了速率限制 \[ ] 响应未泄露内部细节（堆栈跟踪、SQL 错误） \[ ] 与现有端点命名一致（camelCase 对比 snake\case）

This is an excerpt. Refer to the complete source and its current requirements.