API 错误码规范与诊断清单（2025）
# API 错误码规范与诊断清单（2025）
统一错误码与诊断流程让跨团队协作更高效。
## 一、结构与分类
- 结构：`code`/`message`/`traceId`/`details`。
- 分类：客户端/服务端/依赖错误细分与范围编码。
## 二、诊断与重试
- 诊断清单：必采集字段与上下文、用户影响与复现路径。
- 重试与退避：按错误类别设定可重试策略。
## 三、观测与告警
API设计与开发
API 限流与请求签名（HMAC、时间窗与防重放）
结合令牌桶/漏桶限流与HMAC请求签名, 通过时间窗与Nonce复用检测实现防重放与审计, 并提供服务端/客户端实现与验证流程。
API分页与游标设计最佳实践
为高数据量与高并发场景设计可靠分页，采用游标与稳定排序、限制偏移与窗口，提供一致性与性能策略与验证方法。
API幂等与去重：Idempotency-Key与去重表实践
通过幂等键与去重表保障至少一次投递下的正确性，减少重试与网络抖动带来的副作用。
API幂等性设计：Idempotency-Key与去重治理
通过 Idempotency-Key 与请求签名建立幂等保障，配合唯一约束与去重窗口实现安全重试与一致响应。
API授权Scope最小权限治理（层级/匹配）最佳实践
通过层级化Scope与资源-动作匹配、最小权限原则与拒绝默认策略，统一治理API授权并降低越权风险。
API版本治理：URI、Header与内容协商
系统化比较路径版本、请求头版本与媒体类型内容协商方案，指导在演进中保持后向兼容与清晰的变更边界。
API版本管理策略：语义化与兼容设计
围绕语义化版本与兼容路由，设计可演进的 API 版本策略与弃用流程，降低客户端破坏性影响。
API签名与重放防护：HMAC与时间窗
通过 HMAC 计算与时间窗/Nonce 抑制重放攻击，提升公共 API 的安全性与可审计性。
API网关多租户治理与策略路由实践
以网关的租户维度策略路由与配额治理实现安全与弹性，对接鉴权与灰度发布，并提供可验证的规则与监控。
API网关选型：Nginx、Envoy与Kong的对比
对比三类主流网关的能力与扩展性，从路由、鉴权到可观测性给出工程选型建议。
API网关限流与配额策略对比实践
对比Kong、Envoy与APISIX的限流与配额策略，提供可验证的配置片段与命令，确保公正与稳定的流量治理。
API设计规范与OpenAPI 3.1实践
基于 OpenAPI 3.1 规范化 API 设计，涵盖资源建模、分页与错误码、幂等与安全实践，并给出可验证的示例。
