改一个字段就有人挂：目录站对外接口的版本该怎么管

目录站开放接口的对象通常有两类：合作方在拉条目数据，以及自己开发的小程序或扩展在用。这两类调用方有个共同点——你改接口的时候没人会提前告诉你他依赖了哪个字段。

所以版本管理的核心不是版本号本身，而是先分清哪些改动会打断别人。

图片来源：网络，版权归原作者所有，侵权请联系删除

什么算破坏性变更

判断标准很朴素：调用方不改代码，原来能跑通的请求现在会不会出错、或者结果变了。

破坏性（要升版本）	非破坏性（原地加就行）
删除或重命名字段	新增可选字段
改字段类型（数字变字符串）	新增接口端点
改字段语义（同一名字意思变了）	新增可选查询参数
改枚举取值或默认值	放宽校验（原来报错现在接受）
收紧鉴权、改错误码含义	补充文档性描述

有一条经常被漏掉：给枚举加新值对调用方可能是破坏性的。如果对方的解析逻辑是穷举匹配，遇到不认识的值就抛异常，那你加一个值等于让他的程序崩溃。稳妥做法是新增值只在新版本里出现，或者提前公告并给一个月的缓冲。

版本号放哪里

三种常见放法：URL 路径（/api/v1/items）、请求头（Accept: application/vnd.example.v1+json）、查询参数（?version=1）。

目录站这类规模，选 URL 路径最省心：日志里一眼能看出是哪个版本，缓存键天然分开，调试时浏览器直接敲地址就能看结果。请求头方案更讲究但可读性差，查询参数方案容易被缓存层忽略，不推荐。

版本号的粒度是整个接口一个版本，不要每个端点各编各的号。后者看着灵活，实际上没人记得住哪个端点是 v3。

弃用要走完整流程

确定要下线一个版本，按顺序做五件事：

• 公告：写明下线日期、替代版本、迁移要点，发给所有登记过的调用方
• 响应头：在旧版本的响应里带上弃用标记和下线时间（Sunset 头，RFC 8594，2019 年发布，就是为这个场景定义的）
• 监控：按版本号统计调用量，看哪些调用方还没迁——这条是唯一可靠的数据来源
• 灰度提醒：对还在用旧版本的调用方返回告警字段，或者在响应里插一条提示
• 到期才关：确认调用量降到零或只剩可接受的个位数，再关掉

并存期给多长没有标准答案，业界的做法是三到十二个月，取决于调用方的数量和他改造的难度。合作方是外部公司的，按合同来，别单方面定。

内部接口别过度版本化

只有自己人用的接口不要搞版本。前端和后端一起发版，改了字段直接改调用方就行，加版本号只会制造一堆没人清理的历史包袱。判断界限很简单：有没有你控制不了的调用方。有，就版本化；没有，就别。

接口一旦对外开放，改动成本就是别人的改造成本之和。上线前多花半小时想清楚哪些字段会被依赖、哪些可以随便改，比事后发十封迁移公告便宜。