-
前言：为什么大多数后端系统会被“接口混乱”反噬？
- 新旧 API 并存
- 字段越加越多
- 返回结构不一致
- 文档缺失、多人风格混乱
- 需求迭代后接口不可扩展
-
API 设计的核心原则（从工程角度）
- 稳定性优先（Backward Compatible）
- 明确的领域语义（Domain Friendly）
- 可扩展（Extensible）
- 自解释（Self-Describing）
- 一致性（Consistent）
-
接口版本治理
- API 版本粒度（系统级 / 功能级 / 模块级）
- Version in Path vs Header
- API 老版本寿命周期管理
- 无破坏性演进（Additive Only）
-
返回结构统一化
- 一个成熟的 API 必须有统一响应格式
- 错误码体系（ErrorCode 规范）
- 分页结构统一
- 枚举统一格式（code + name）
-
工程支撑能力
- API Linter（接口自动校验）
- 自动文档（OpenAPI / Swagger）
- API Mock Server
- API Diff 检查（新旧版本比对）
-
案例：订单系统 API 从“组件混乱”到“统一治理平台”
- 字段清洗
- 接口聚合
- 领域化拆分
- 版本策略落地
-
总结
- API 不是写出来的，是治理出来的
- API 好坏直接决定系统生命周期
