API 设计一致性：错误码、分页与幂等头的团队规范

API 的一致性是团队效率的乘数

同一个团队里，A 服务的错误返回 {code: 500, msg: "fail"}，B 服务返回 {error: {type, message}}，C 服务直接抛 HTTP 状态码——调用方每接一个服务都要重学一遍错误处理。API 设计规范的价值不在「风格高级」，在于调用方可以形成稳定预期：看到结构就知道怎么解析、出错就知道怎么重试。一、错误码：三段式结构

1. HTTP 状态码管大类：2xx 成功、4xx 调用方问题（参数、权限、不存在）、5xx 服务端问题——不要全部 200 包一层（会杀死网关与SDK的重试语义）；
2. 业务错误码管细节：USER_NOT_FOUND 这类可读字符串比纯数字好（排查不用查表）；格式统一 域_问题；
3. 错误响应结构统一：{code, message, requestId, details?}——requestId 必须返回，排障时调用方与服务的日志能对上。

三个易错点：401（未认证）与 403（未授权）不能混用；删除幂等接口返回 204 还是 200+body 要全局统一；限流返回 429 并带 Retry-After 头。

二、分页：游标优先

1. 偏移分页（page/size）：实现简单，但深翻页性能差（LIMIT 100000, 20 要扫前 10 万行），且数据变动时会出现重复/漏读；
2. 游标分页（cursor/limit）：cursor 是上一页末尾的排序键（如 ID 或时间戳），性能稳定、结果一致，代价是不能跳页；
3. 规范决策：面向用户的列表（允许跳页）用偏移，面向程序/无限滚动的接口用游标；分页响应统一 {items, nextCursor/total, hasMore} 结构；单页上限强制（如 size ≤ 100），防止一次拉爆。

三、幂等头与并发控制

1. 写接口带 Idempotency-Key：客户端为每个写请求生成唯一键，服务端按键去重（支付、下单类接口必配）——重试风暴与双击提交的统一解；
2. 乐观并发：更新接口带 version/ETag，版本不符返回 409——比分布式锁轻量得多；
3. 重试语义写进文档：哪些错误码可重试（429/503/超时）、退避策略、哪些绝不重试（400 参数错）——调用方的重试行为失控是很多雪崩的源头。

四、规范怎么落地

1. OpenAPI 契约先行：接口文档即代码，CI 里校验实现与契约一致（Spectral lint）；
2. 脚手架固化：错误处理、分页、幂等做成框架中间件/内部库——靠 review 逐条盯规范必失效，工具化才稳定；
3. 评审清单：新接口评审过五关：状态码语义、错误结构、分页方式、幂等键、鉴权模型。

API 规范的本质是给调用方「可预期的行为契约」。规范文档只完成 30%，剩下 70% 靠中间件固化与 CI 校验——让不合规的接口无法上线，规范才算真正落地。