用途：为设计新的 API 端点、评审既有 API 契约、添加分页/过滤/排序、实现 API 错误处理、规划版本化策略提供统一规范，帮助产出风格一致的 REST API。
主要能力与规范要点： 资源命名：资源用名词、复数、小写、kebab-case，例如 /api/v1/users；子资源表示关系如 /api/v1/users/:id/orders；不映射到 CRUD 的动作可少量用动词，如 POST /api/v1/orders/:id/cancel。避免 URL 中出现动词、单数资源名或 snake_case。
HTTP 方法与状态码：GET 安全且幂等；POST 创建资源或触发动作；PUT 全量替换且幂等；PATCH 部分更新；DELETE 删除。成功码用 200、201（含 Location 头）、204；客户端错误用 400、401、403、404、409、422、429；服务端错误用 500（不暴露细节）、503（含 Retry-After）。
响应格式：成功返回 data 包裹单个对象；集合返回 data 数组加 meta（total、page、per_page、total_pages）与 links（self、next、last）；错误返回 error 对象，含 code、message 和 details 字段级错误。
分页：offset 方式（?page=2&per_page=20）简单、支持跳页，但大偏移慢且并发插入下不一致；cursor 方式（?cursor=...&limit=20）性能稳定、适合并发，但不能任意跳页。选择建议：管理后台/小数据集与搜索结果用 offset；无限滚动、信息流、大数据集与公开 API 默认用 cursor。
过滤、排序与搜索：支持等值查询、比较运算符如 price[gte]=10、多值逗号分隔、排序前缀 - 表示降序（sort=-created_at,price）、全文搜索 q=、稀疏字段集 fields=id,name,email。
认证与限流：使用 Bearer Token 或 X-API-Key；限流头含 X-RateLimit-Limit、Remaining、Reset；按匿名/认证/付费分层（30/min、100/min、1000/min）。
版本化：推荐 URL 路径版本 /api/v1/，按需版本化，最多同时维护两个活跃版本；新增字段或端点属非破坏性，删除或重命名字段需新版本。
使用方式：作为设计或评审检查清单使用，涵盖命名、HTTP 方法、状态码、输入校验（Zod、Pydantic 等）、错误格式、列表分页、认证与授权、限流、不泄漏内部细节（堆栈、SQL 错误）、与既有端点命名一致、并补充文档（OpenAPI/Swagger）。
限制：本资料为设计约定与最佳实践指南，非可直接运行的工具或库；未提供具体安装命令、代码实现、收费或平台信息。