给一个客户打的补丁,可能弄坏另外三个
语义化版本、变更日志和维护窗口,让每个客户提前知道何时升级、会变什么。
要点速览
- 按 SemVer,重命名客户读取的字段属于 MAJOR 变更,哪怕代码只改了一行。
- 为每个客户锁定版本,并把每项破坏性变更封装在一个模块里,让客户自己选择升级日期。
- 维护窗口只规定开始时间,工作仍可能超出结束时间。
周五,你为客户 A 修复了连接器里的一个时区 bug。补丁很小,测试全部通过,于是你把它推送给共用这个连接器的全部五个客户。周一早上来了三个工单:客户 B 的报表差了一天,客户 C 的数据管道抛出解析错误,客户 D 问为什么没人提前通知。
代码本身没有 bug。出问题的是发布流程:它从没考虑过一次变更会同时影响多个客户,而每个客户都有自己的运维节奏和风险承受能力。
对前线部署工程师(FDE)来说,这种情况来得比很多人预想的早。你为第一个客户写的集成一旦被搬到第二个、第三个客户那里,你就是在维护一个产品,哪怕还没人这么叫它。有三样工具值得掌握:版本号、变更日志和维护窗口。
版本号是承诺,不是流水号
语义化版本(Semantic Versioning)2.0.0 定义了三个数字,各有含义。做了不兼容的 API 变更,递增 MAJOR;以向后兼容的方式新增功能,递增 MINOR;做了向后兼容的 bug 修复,递增 PATCH。
难点在于,“兼容”必须从客户的角度来判断。拿上面那个当前版本为 2.3.1 的连接器来套用:
| 变更 | 客户看到什么 | 新版本 |
|---|---|---|
| 修复空文件导致的崩溃 | 原本坏掉的功能能用了 | 2.3.2 |
新增可选字段 region |
数据多了,旧的不变 | 2.4.0 |
将 customer_id 重命名为 account_id |
正在运行的查询报错 | 3.0.0 |
| 时间戳从本地时间改为 UTC | 字段相同,值不同 | 3.0.0 |
最后一行就是周五那个补丁。在你看来它是 bug 修复,但客户 B 的报表是基于旧行为搭建的。如果一项变更改动了客户依赖的结果,稳妥的做法是把它当作 MAJOR,或者加一个配置开关,让客户自己决定何时启用新行为。
SemVer 还有一条很多团队会忘的规则:版本一旦发布,内容就不能再改。任何修改都必须以新版本发布。
如果有几个客户锁定了 2.3.1,而你悄悄重新构建并覆盖了 2.3.1 这个 tag,就会出现两个客户都在跑“2.3.1”,实际运行的却是两样东西。
等到出事故时,你已经说不清谁在跑什么。
让每个客户自己选升级日期
Stripe 的做法值得研究。一个账户第一次调用 API 时,会被锁定在当时的最新版本。此后客户按自己的时间表升级,而不是按 Stripe 的。
在后台,每项向后不兼容的变更都封装在一个版本变更模块里。这样旧版本可以继续工作,兼容逻辑也不会散落在整个代码库中。
如今 Stripe 每月发布一个不含破坏性变更的新版本,每年两次发布包含破坏性变更的大版本。Webhook 端点也可以单独锁定版本,客户可以一次只升级一个集成。
为少数几个客户维护连接器的 FDE 不需要搭建这样的系统。每个客户一行配置,记录其运行的版本,就够了。
把 customer_id 重命名为 account_id 时,不要到处写 if version < 3。写一个适配函数,为仍在 2.x 的客户把新格式转换回旧格式。
等到停止支持 2.x 的那天,你只需删掉一个文件。
讲清楚支持多老的版本
不加限制地锁定版本,最后你会同时维护十个版本。Kubernetes 用一条公开政策解决这个问题:kubelet 最多可以比 kube-apiserver 落后三个次版本。发布分支只保留最近三个次版本,从 1.19 起,每个版本大约获得一年的补丁支持。
有了这个数字,客户知道自己还有多少时间,可以分步升级,而不是一夜之间全部换掉。
为你的连接器也写一段类似的说明,例如:“为当前次版本及之前两个次版本提供安全修复;新的主版本发布后,旧主版本继续支持六个月。”具体数字由团队决定,前提是写下来,并且客户读过。
变更日志是写给客户运维人员看的
Keep a Changelog 开篇就提出一条原则:变更日志是给人看的,不是给机器看的。把 git log 原样贴出来不算变更日志。这里的读者是客户的运维工程师,他们只需要知道两件事:要不要做什么,以及在什么时候之前做。
这套规范把变更归入固定类别,其中 Deprecated 表示即将移除的功能,Removed 表示已经移除的功能。它还规定了底线:就算别的都不做,至少要列出弃用、移除和每一项破坏性变更。对上面的连接器,一条合格的变更日志如下:
## [3.0.0] - 2026-12-01
### Changed
- BREAKING:`customer_id` 重命名为 `account_id`。
需要操作:更新读取该字段的查询。2.x 将持续获得 bug 修复,直至 2027-06-01。
- BREAKING:时间戳改为返回 UTC,不再返回本地时间。
### Deprecated
- `legacy_auth` 参数,将在 4.0.0 中移除。
### Fixed
- 输入文件为空时不再崩溃。
每一行 BREAKING 都写明客户需要做什么,以及截止日期。如果客户 D 在周五之前读到这样一条记录,就不会有第三个工单。
维护窗口只规定开始时间
最后一块是何时部署。Amazon RDS 使用每周 30 分钟的维护窗口;如果你不指定,RDS 会随机分配一周中的某一天。AWS 文档也写得很直白:维护不保证在窗口结束前完成,可能超出结束时间。
设想客户 C 给你的窗口是周日凌晨 02:00 到 02:30。在预发环境中,字段重命名的迁移需要 40 分钟。如果照原计划执行,到 02:40 系统还在半途,而客户的值班人员已经下班了。
合理的选择有两个:申请更长的窗口;或者把迁移拆出一个后台步骤,提前几天运行,窗口内只做开关切换。
RDS 还有一个细节值得借鉴。对于强制升级,过了强制执行日期后,RDS 可能在客户所选窗口之外进行升级。调整窗口不等于可以无限期推迟。停止支持 2.x 时,你同样需要这样一个日期,提早通知客户,并在变更日志里反复写明。
最常见的错误
最常见的错误是按 diff 的大小而不是对客户的影响来分类,就像开头那个 UTC 补丁。第二个是为省时间覆盖旧 tag,这正是 SemVer 明令禁止的。第三个是把窗口结束时间当作保证完成的时间,结果工作超时时没人值班。
第四个较少被提及:同时部署到全部五个客户。应该按顺序推出,先从最能承受风险的客户或某个客户的预发环境开始,等一个完整的数据周期跑完,再继续。
把这项技能写进简历、带进面试
简历上写一句“为多个客户维护带版本管理的连接器,配有支持政策和公开的变更日志”,能让招聘方看出你承担过自己代码的后果。条件允许的话,附上那份变更日志或支持政策页面的链接。
看 FDE 招聘启事时,留意“rollout”“upgrade”“multi-tenant”这类词,然后在面试中问团队要向多少客户交付、节奏如何。讲一讲你曾把某项变更错归为 PATCH、事后又如何改进流程,通常比背出任何定义都更有说服力。
客户并不要求你永不出错。他们需要提前知道你何时会改什么;万一出了问题,也有办法回退到上一个版本。
这篇文章对你有帮助吗?
感谢你的反馈!