Agent skill · software engineering · affaan-m
api-design
REST API设计模式，包括资源命名、状态码、分页、过滤、错误响应、版本控制和生产API的速率限制。
Why this skill is useful
Provides specific REST API design patterns and conventions that the AI wouldn't reliably generate on its own.
What it needs
About 5k tokens when loaded. Last updated 2026-08-06. 238,342 stars on the source repository.
What this skill does
API 设计模式 用于设计一致、对开发者友好的 REST API 的约定和最佳实践。 何时启用 设计新的 API 端点时 审查现有的 API 契约时 添加分页、过滤或排序功能时 为 API 实现错误处理时 规划 API 版本策略时 构建面向公众或合作伙伴的 API 时 资源设计 URL 结构 命名规则 HTTP 方法和状态码 方法语义 方法 幂等性 安全性 用途 -------- ----------- ------ --------- GET 是 是 检索资源 POST 否 否 创建资源，触发操作 PUT 是 否 完全替换资源 PATCH 否\ 否 部分更新资源 DELETE 是 否 删除资源 \通过适当的实现，PATCH 可以实现幂等 状态码参考 常见错误 响应格式 成功响应 集合响应（带分页） 错误响应 响应包装器变体 分页 基于偏移量（简单） 优点： 易于实现，支持“跳转到第 N 页” 缺点： 在大偏移量时速度慢（例如 OFFSET 100000），并发插入时结果不一致 基于游标（可扩展） 优点： 无论位置如何，性能一致；在并发插入时结果稳定 缺点： 无法跳转到任意页面；游标是不透明的 何时使用哪种 用例 分页类型 ---------- ---------------- 管理仪表板，小数据集 (<10K) 偏移量 无限滚动，信息流，大数据集 游标 公共 API 游标（默认）配合偏移量（可选） 搜索结果 偏移量（用户期望有页码） 过滤、排序和搜索 过滤 排序 全文搜索 稀疏字段集 认证和授权 基于令牌的认证 授权模式 速率限制 响应头 速率限制层级 层级 限制 时间窗口 用例 ------ ------- -------- ---------- 匿名用户 30/分钟 每个 IP 公共端点 认证用户 100/分钟 每个用户 标准 API 访问 高级用户 1000/分钟 每个 API 密钥 付费 API 套餐 内部服务 10000/分钟 每个服务 服务间调用 版本控制 URL 路径版本控制（推荐） 优点： 明确，易于路由，可缓存 缺点： 版本间 URL 会变化 请求头版本控制 优点： URL 简洁 缺点： 测试更困难，容易忘记 版本控制策略 实现模式 TypeScript (Next.js API 路由) Python (Django REST Framework) Go (net/http) API 设计清单 发布新端点前请检查： \[ ] 资源 URL 遵循命名约定（复数、短横线连接、不含动词） \[ ] 使用了正确的 HTTP 方法（GET 用于读取，POST 用于创建等） \[ ] 返回了适当的状态码（不要所有情况都返回 200） \[ ] 使用模式（Zod, Pydantic, Bean Validation）验证了输入 \[ ] 错误响应遵循带代码和消息的标准格式 \[ ] 列表端点实现了分页（游标或偏移量） \[ ] 需要认证（或明确标记为公开） \[ ] 检查了授权（用户只能访问自己的资源） \[ ] 配置了速率限制 \[ ] 响应未泄露内部细节（堆栈跟踪、SQL 错误） \[ ] 与现有端点命名一致（camelCase 对比 snake\case） \[ ] 已记录（更新了 OpenAPI/Swagger 规范）
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills affaan-m/api-design--b0a516