API 设计检查清单

使用方式：新 API 评审逐条打勾；存量系统治理按章节批量扫描。每条后标注了教程章节，争议时回章查依据。

A. URI 与资源

• [ ] 资源名复数、小写 kebab-case，无动词（/user-profiles ✅，/getUser ❌）——URI 设计
• [ ] 从属路径 ≤ 2 层；深层关系用扁平 URI ——资源与资源层次
• [ ] 无 .json 扩展名、无尾斜杠、大小写全局一致 ——URI 设计
• [ ] 过滤/分页/排序/字段选择用查询参数，不进路径 ——分页过滤排序
• [ ] 路径参数值含特殊字符时百分号编码（RFC 3986）；不用 #；避免裸 %2F
• [ ] 动作端点最后手段：优先状态资源（PUT /status）或子资源（POST /{id}/publications）——方法语义
• [ ] ID 不可被枚举业务规模与遍历（对外用 UUID/雪花）——资源与资源层次

B. 方法与状态码

• [ ] 读=GET（确认无副作用）、创建=POST(201+Location)、全量替换=PUT、局部=PATCH、删除=DELETE ——方法语义
• [ ] 204/304 响应无 body；HEAD 响应有头部无 body
• [ ] 405 带 Allow；401 带 WWW-Authenticate；429/503 带 Retry-After ——状态码详解
• [ ] 校验失败用 400/422；冲突用 409；并发用 412；限流 429；永久删除 410 ——状态码详解
• [ ] 不返回自定义 5xx/6xx 状态码；成功不用 3xx 代替 2xx ——状态码详解
• [ ] GET/HEAD/OPTIONS 可被网关安全重试；POST 重试策略明确

C. 请求与表示

• [ ] Content-Type/Accept 显式声明与校验；非 application/json 的请求体明确媒体类型（merge-patch 等）——表示与媒体类型
• [ ] 集合响应 items + 分页字段 + links；空集合返回 [] 非 null ——响应结构与命名
• [ ] 时间 RFC 3339（UTC 或显式偏移）；金额字符串/分；大整数（>2^53）字符串 ——表示与媒体类型
• [ ] 字段命名全局一致（camel 或 snake 二选一）；布尔/ID/计数字段遵守命名细则 ——响应结构与命名
• [ ] 枚举小写字符串；文档要求客户端容忍未知值；状态机成文 ——响应结构与命名
• [ ] 未知请求字段默认拒绝（400），白名单放开特例 ——认证与授权（API2/API6）

D. 可靠性

• [ ] 所有 POST 支持 Idempotency-Key（或 clientRequestId），重放语义文档化 ——安全与幂等
• [ ] 并发敏感的写接口强制 If-Match（缺→428，旧→412）或显式"后写覆盖"声明 ——缓存与条件请求
• [ ] 超时与重试指引发布：哪些方法可重试、退避策略、Retry-After 支持 ——状态码详解
• [ ] 长任务：202 + 作业资源 + 轮询（Retry-After/304）或 SSE/Webhook ——异步操作
• [ ] 批量：上限 + clientRef + 逐条状态（禁静默跳过）；大批量走作业 ——批量操作

E. 缓存与性能

• [ ] 全部 GET 支持强 ETag；私有数据 private/no-store；错误 no-store ——缓存与条件请求
• [ ] 协商响应正确 Vary；集合缓存短 TTL 或 stale-while-revalidate + purge 联动
• [ ] pageSize 钳制上限；默认排序稳定（含唯一 tie-breaker）——分页过滤排序
• [ ] 列表不携带巨型字段（正文/base64），需要时 ?fields= 或子资源

F. 安全

• [ ] HTTPS + HSTS；HTTP 308 升级 ——限流与安全
• [ ] 对象级授权（每个端点校验 owner/scope），401/403/404 防枚举策略一致 ——认证与授权
• [ ] JWT：固定算法白名单、校验 iss/aud/exp、短 TTL + 刷新旋转；令牌不进 URL ——认证与授权
• [ ] 出站 URL 参数（回调/抓取）白名单防 SSRF；?url= 类参数全部审计
• [ ] 安全头部：nosniff、CSP（frame-ancestors 'none'）、收紧 CORS、剥离 Server/X-Powered-By ——限流与安全
• [ ] 错误响应不回显堆栈/SQL/内部路径；5xx 带 traceId ——错误处理
• [ ] 限流头部 + 配额资源可查；写端点独立配额 ——限流与安全

G. 错误处理

• [ ] 错误一律 application/problem+json（RFC 9457），status 与实际一致 ——错误处理
• [ ] type 指向错误码目录；一码一义；errors[] 批量返回字段级校验错误
• [ ] 校验"报告全部问题"而非第一个；深层嵌套结构用 JSON Pointer 定位 field

H. 演进与治理

• [ ] 版本策略明确（URI major）；新增字段/枚举值=非破坏性，双方达成共识 ——版本设计
• [ ] 弃用三件套：Deprecation/Sunset 头 + Link 迁移文档 + 时间线公告 ——版本设计
• [ ] 路由变更 308 重定向保方法；下线端点 410 ——URI 设计
• [ ] OpenAPI 为单一事实源：CI 跑 spectral（风格）+ oasdiff（破坏性变更门禁）——OpenAPI 实战
• [ ] 20 条协议合规自动化测试进 CI ——API 测试
• [ ] CHANGELOG 记录契约变更；SDK/示例代码同步更新