API 反模式是什么
反模式指在多个团队反复出现、看似能快速交付但长期抬高维护成本的设计习惯。它与「写得不够漂亮」不同，代价是可量化的：接入方要额外写适配代码、网关无法做缓存与限流、故障定位只能靠翻日志猜。识别反模式的价值在于把踩过的坑沉淀成评审清单，在设计阶段提出改进项。
为什么评审常漏掉
评审往往聚焦字段命名与文档格式，忽略错误语义、兼容策略与资源建模这些更难撤回的决定。接口一旦被下游使用，改动就要走废弃与迁移流程，成本比评审时改一行高一个数量级。评审清单应覆盖资源语义、状态码与错误结构、版本与废弃、幂等与安全边界四类问题，并在合并前用自动化规则兜底。
反模式清单
| 反模式 | 症状 | 改法 |
|---|---|---|
| 单端点隧道 | 所有调用走同一个路径，动作写在请求体里 | 按资源拆分接口，用方法表达意图 |
| 表驱动资源 | 资源名与表名一一对应，字段直接暴露 | 按领域语义建模，隔离内部存储 |
| 全员成功码 | 业务失败也返回成功，错误藏在响应体里 | 用状态码表达结果并配统一错误结构 |
| 静默变更 | 字段语义改变没有公告与迁移期 | 建立兼容策略与废弃流程 |
| 参数语义漂移 | 同一过滤参数在不同接口含义不同 | 统一约定并写进接口规范 |
典型使用场景
- 新接口设计评审时按清单逐项过一遍，把问题挡在开发之前
- 接手历史接口前先盘点反模式，评估改造与兼容成本
- 把清单固化成流水线检查规则，合并前自动拦截偏差
- 为对外开放的接口做版本规划时，确认哪些约定必须保留
基本信息
| 影响范围 | 接入方适配成本、网关治理能力、故障定位效率 |
|---|---|
| 高发阶段 | 交付压力大、接口由多方并行开发时最容易出现 |
| 治理手段 | 评审清单、接口规范文档、自动化规则检查 |
| 修复成本 | 已被下游使用的接口改动需走废弃与迁移流程 |
评审清单化比反复讲道理有效：把反模式整理成检查项，每次评审按清单过一遍，新人对齐的速度会很不一样。
历史接口无人敢改、新需求继续叠加特例，最终形成只有原作者能维护的接口；约定越晚收敛，后续每一次改动的成本越高。