用途:这是一份面向 REST API 的设计约定与最佳实践集合,用于新建端点、评审既有接口契约、补充分页/过滤/排序、设计错误处理、规划版本策略,以及构建公开或合作伙伴 API。
主要能力:
- 资源设计:URL 中使用名词、复数、小写和 kebab-case;用嵌套资源表达归属关系;对无法映射为 CRUD 的动作谨慎使用动词(如 /orders/:id/cancel、/auth/login)。给出正反例(避免 getUsers、单数 user、snake_case 等)。
- HTTP 方法与状态码:说明 GET/POST/PUT/PATCH/DELETE 的幂等性与安全性,并列出常用状态码:200/201/204,400/401/403/404/409/422/429,500/502/503;强调不要一律返回 200,也不要对校验错误返回 500,创建成功应返回 201 与 Location 头。
- 响应格式:成功响应使用 data 包裹;集合响应带 meta(total/page/per_page/total_pages)与 links(self/next/last);错误响应包含 error.code、message 与字段级 details。还提供“带 data 包裹”与“扁平响应”两种封装变体。
- 分页:偏移分页(page/per_page)适合管理后台和小数据集,但大偏移慢且并发插入时不一致;游标分页(cursor/limit,多取一条判断 has_next)性能稳定、适合信息流和大数据集;公开 API 建议默认游标、可选偏移;搜索结果适合偏移以支持页码跳转。
- 过滤、排序与搜索:支持等值过滤、括号比较操作符(price[gte]、created_at[after])、逗号多值、点号嵌套字段;排序用 - 前缀表示降序,支持多字段;提供 q 全文搜索与字段级搜索;支持 sparse fieldsets(fields、include)减少载荷。
- 认证与授权:Authorization: Bearer 令牌、X-API-Key 服务间调用;给出资源级归属检查与基于角色的权限控制示例代码。
- 限流:返回 X-RateLimit-Limit/Remaining/Reset 头;超限返回 429 与 Retry-After,并给出匿名、已认证、付费、内部四档示例限流。
- 版本控制:推荐 URL 路径版本(/api/v1);也介绍 Accept 头版本;策略包括从 v1 起步、最多维护两个活跃版本、弃用通知与 Sunset 头、到期返回 410、区分非破坏性与破坏性变更。
- 实现模式:提供 TypeScript(Next.js API Route + Zod)、Python(Django REST Framework)、Go(net/http)的示例代码,覆盖校验、201/Location、错误响应等。
- 发布检查清单:涵盖命名、方法、状态码、输入校验、错误格式、分页、认证与授权、限流、响应不泄露内部细节、命名一致性和 OpenAPI/Swagger 文档更新。
使用方式:资料未提供安装命令或运行步骤;内容以约定、代码片段和清单形式呈现,可对照现有接口逐项落地。
适用场景:设计新端点、评审 API 契约、补齐分页/过滤/排序、统一错误处理、规划版本与弃用、构建公开或合作方 API、在 TypeScript、Python、Go 服务中实现约定。
限制:资料未说明授权协议、收费、价格或特定平台支持范围;示例代码仅作模式参考,未给出完整项目配置或测试说明。