# 给一个客户打的补丁，可能弄坏另外三个

> 语义化版本、变更日志和维护窗口，让每个客户提前知道何时升级、会变什么。

原文: https://fdetimes.net/zh/guides/versioning-changelogs-maintenance-windows-multiple-clients/

周五，你为客户 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 表示已经移除的功能。它还规定了底线：就算别的都不做，至少要列出弃用、移除和每一项破坏性变更。对上面的连接器，一条合格的变更日志如下：

```markdown
## [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、事后又如何改进流程，通常比背出任何定义都更有说服力。

客户并不要求你永不出错。他们需要提前知道你何时会改什么；万一出了问题，也有办法回退到上一个版本。

**本周动手试试:**

- 取你维护的某个连接器或 SDK 最近 10 次提交，逐一归为 MAJOR、MINOR 或 PATCH，再与实际发布的版本号对照
- 按 Added、Changed、Deprecated、Removed 和 Fixed 重写最近一次发布的变更日志，把 Deprecated 和 Removed 放在最前面
- 写一段版本支持政策，说明你仍为哪些版本打补丁、持续到何时，然后发给团队负责人征求意见

## 信源

- [Semantic Versioning 2.0.0](https://semver.org/)

- [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)

- [APIs as infrastructure: future-proofing Stripe with versioning](https://stripe.com/blog/api-versioning)

- [How API versioning works](https://docs.stripe.com/api-versions)

- [Version Skew Policy](https://kubernetes.io/releases/version-skew-policy/)

- [Maintaining a DB instance - Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.Maintenance.html)
