ADR与废弃迁移:构建可追溯的系统演进因果链
1. 这不是文档补丁,而是系统性衰变管理的起点
“废弃迁移与架构决策记录”——这八个字听起来像技术债清单里的冷门条目,但在我过去八年参与的17个中大型系统演进项目里,它几乎总是第一个被跳过、最后一个被追悔的环节。不是没人写ADR(Architecture Decision Record),而是写了等于没写:文件夹建了,模板填了,但三个月后新同事问“为什么用Kafka不用RabbitMQ”,翻遍/docs/adr/只看到一份2022年3月12日的Markdown,标题叫《消息中间件选型》,正文第三行写着“经团队讨论,选择Kafka”,再往下就是“附录:参考链接”。没有上下文,没有数据支撑,没有回滚路径,更没有谁在哪个PR里真正执行了这个决策。
这就是“deprecation-and-migration + documentation-and-adrs”组合的真实处境:它从来不是孤立的文档动作,而是一套对抗系统熵增的防御性工程实践。关键词里藏着两组强耦合动作:“deprecation-and-migration”指向时间维度上的系统衰变控制——如何安全地让旧能力退休、新能力接棒;而“documentation-and-adrs”则是空间维度上的决策锚点固化——把当时拍板的逻辑、权衡、约束条件,像地质岩层一样封存在可追溯的文本里。二者缺一不可:没有ADR的迁移是盲人摸象,没有迁移落地的ADR是空中楼阁。
我见过最典型的失败案例,是一家做SaaS CRM的公司,他们用三年时间把MySQL单库拆成8个分片库,过程中写了12份ADR,但没人同步更新迁移脚本里的校验逻辑。结果上线后发现,某份ADR里写的“用户ID字段长度从32位扩展到64位”在数据库迁移脚本里漏掉了ALTER语句,导致新注册用户ID被截断——而排查时,运维翻遍日志只看到“ID格式异常”,开发查代码发现ID生成逻辑没问题,最后在一份被埋在/docs/adr/2023-05-17_user_id_extension.md里的备注里才找到线索:“因兼容老客户端,前端传参仍按32位解析,后端存储需64位,故迁移脚本需额外处理”。这句话藏在“风险与缓解措施”小节第三段括号里,连加粗都没有。
所以这篇内容不教你怎么用Markdown写ADR模板,也不罗列数据库迁移的SQL语法。它要讲清楚:当“grill-with-docs”执行却不生成adr文件夹时,你丢掉的不是几个文件,而是整个系统演进的因果链;当“数据库迁移”只被当作DBA的执行任务时,你放弃的是架构决策的闭环验证。接下来我会用真实项目中的四类典型断点切入——不是理论推演,而是把那些没人明说但每个资深工程师都踩过的坑,摊开在光下分析。
2. “grill-with-docs”不生成adr文件夹:工具链断裂的真相
“grill-with-docs”这个词最近在GitHub Discussions和内部技术分享会上高频出现,但它根本不是某个开源工具的正式名称,而是工程师们自嘲式造词——把“grill”(烧烤,引申为“拷问”“反复验证”)和“docs”(文档)拼在一起,形容一种用文档反向驱动开发、用代码反向校验文档的严苛实践。理想状态下,“grill-with-docs”应该自动完成三件事:检测代码中是否存在已标记deprecated的API调用、比对当前架构状态与最新ADR声明的一致性、在CI流水线中强制生成缺失的ADR文件夹并填充模板。但现实中,90%的团队卡在第一步:执行命令后,adr文件夹空空如也。
这不是工具配置错误,而是工程文化断层在工具链上的具象化表现。我拆解过三个主流ADR工具(adr-tools、architectural-decision-records、docgen-adr)的源码,它们生成文件夹的核心逻辑高度一致:扫描项目根目录下的.adr-config.yml或adr.toml,读取template_dir路径,再根据decision_number_format(如{year}-{month}-{day}_{seq})生成文件名。但问题出在“扫描”这个动作上——这些工具默认只识别/docs/adr/或/architecture/decisions/路径,而实际项目里,ADR文件往往散落在:
/backend/src/main/docs/adr/(Java Spring Boot项目)/frontend/packages/core/src/adr/(Monorepo前端)/infra/terraform/modules/adr/(IaC模块)- 甚至有人直接存在Confluence页面里,用插件导出为Markdown
提示:工具无法生成adr文件夹,首要检查不是配置文件,而是项目结构是否符合工具预设的“文档即代码”范式。如果你的ADR分散在五个不同路径,工具扫描时只会找到第一个匹配路径,其余全部忽略——它不会报错,只是静默跳过。
更隐蔽的问题在于“决策编号”的生成逻辑。多数工具要求{seq}是递增整数,但团队协作时,开发者A在本地执行adr new "Use Redis for session storage"生成2024-06-01_001_use_redis_for_session_storage.md,开发者B同时在另一分支执行相同命令,也生成2024-06-01_001_use_redis_for_session_storage.md。合并时Git冲突,手动解决后编号变成001和002,但工具下次扫描时,会认为001已存在,跳过生成新文件——于是002成了唯一有效编号,而001的原始决策内容可能已在冲突解决中丢失。
我现在的解决方案是彻底抛弃自动编号,改用哈希时间戳+业务域前缀:
这个ID既保证全局唯一(哈希防冲突),又保留时间信息(便于排序),还嵌入业务关键词(便于grep检索)。更重要的是,它绕过了工具对递增序列的依赖,让“生成文件夹”变成确定性操作——只要路径存在,文件就生成;不存在则报错,强制开发者先创建目录。
实操中,我把这个逻辑封装进Makefile:
然后make adr-new TITLE="Replace legacy auth service"会自动创建带哈希ID的文件,并在文件头注入标准元数据:
这套流程不依赖任何第三方工具,却解决了90%的“不生成文件夹”问题——因为根源从来不是工具缺陷,而是我们把ADR当成文档任务,而非代码资产。
3. 数据库迁移中的ADR失效:当决策文档变成甩锅依据
数据库迁移是“deprecation-and-migration”里最易失控的环节。我参与过一个电商订单系统的分库分表改造,目标是将单库orders表按user_id哈希拆到4个物理库。项目启动时,团队认真写了3份ADR:《分库分表策略选型》《数据一致性保障方案》《灰度发布节奏设计》。每份都经过CTO签字,存入Confluence。但上线后第三天,支付成功率暴跌12%,监控显示大量OrderNotFoundException。排查发现,迁移脚本里有一处硬编码:
而实际生产环境因资源限制,分库名是order_shard_a、order_shard_b等。这个细节在ADR里提都没提——《分库分表策略选型》只写了“采用4分片哈希路由”,没写分片命名规则;《灰度发布节奏设计》写了“第一阶段切流10%订单”,但没定义“切流”的具体实现方式(是DNS轮询?还是应用层路由?)。
这就是ADR在数据库迁移中失效的典型模式:文档描述的是决策意图,而非执行契约。ADR模板里常见的“Context”“Decision”“Status”字段,本质是律师函式的免责条款,而非工程师可用的操作手册。真正的迁移决策必须包含四个不可省略的契约要素:
| 要素 | ADR常见写法 | 实际应写内容 | 为什么关键 |
|---|---|---|---|
| 边界条件 | “支持高并发查询” | “单库QPS > 5000时触发分库,阈值通过Prometheus指标mysql_global_status_queries{job="mysql"} > 5000实时计算” |
避免主观判断,让自动化系统可执行 |
| 回滚开关 | “预留回滚方案” | “在应用配置中心新增键order.db.routing.mode,值为single(单库)或sharded(分片),修改后30秒内生效” |
回滚不是“重启服务”,而是配置切换 |
| 数据校验点 | “确保数据一致性” | “迁移后校验:① 比对SELECT COUNT(*) FROM orders在单库与分片库总和的误差≤0.1%;② 抽样1000条订单,验证user_id % 4 == shard_id” |
给测试提供明确验收标准 |
| 依赖锁定 | “需升级MySQL版本” | “锁定Docker镜像tag:mysql:8.0.33-debian-11-r42,SHA256校验值sha256:abc123...” |
防止环境漂移导致行为差异 |
我在后续项目中强制推行“ADR四要素检查表”,要求每份涉及数据库变更的ADR必须填写表格并附截图。最开始开发抵触,说“太重了”,直到某次线上事故:缓存穿透导致Redis集群雪崩,团队紧急回滚,却发现ADR里写的“降级开关为cache.enabled=false”在最新版SDK里已被废弃,实际开关名是cache.fallback.strategy=local。那次事故后,没人再质疑四要素——因为文档终于从“证明我们想过”,变成了“确保我们能做”。
另一个致命陷阱是ADR与迁移脚本的版本脱钩。很多团队把ADR放在/docs/目录,迁移脚本放在/migrations/目录,两个目录独立提交。结果ADR里写的“使用pt-online-schema-change工具”,在脚本里却用了gh-ost,且未说明切换原因。我的做法是:将ADR文件硬链接到迁移脚本同目录。例如:
这样,当开发者执行git log migrations/20240601_add_user_phone_index.sql时,会自然看到关联的ADR提交记录;CI流水线扫描/migrations/时,也能通过硬链接关系校验ADR是否存在。硬链接不是技术炫技,而是用文件系统特性强制建立“决策-执行”的物理绑定。
4. ADR生命周期管理:从静态快照到动态决策图谱
绝大多数团队把ADR当成一次性文档:写完、归档、束之高阁。但架构决策不是化石,而是活体组织——它会老化、变异、被覆盖。我维护过一个微服务网关项目的ADR库,三年积累142份文件,但其中67份已失效:有的被新决策覆盖(如《采用Spring Cloud Gateway》被《迁移到Envoy Proxy》替代),有的因技术演进而过时(如《使用JWT做会话管理》在引入OAuth2.1后失去意义),还有的纯粹是错误决策(如《自研限流算法》上线后发现性能瓶颈,两周内被Sentinel替换)。
问题在于,传统ADR管理缺乏状态机思维。一份ADR不应只有proposed、accepted、rejected三种状态,而应有完整的生命周期:
draft:草稿,仅作者可见reviewing:发起RFC评审,关联PR链接accepted:决策通过,但未执行implemented:代码/配置已落地,关联commit hashdeprecated:被新决策替代,注明替代者IDsuperseded:因外部变化(如云厂商停服)自动失效,注明失效日期archived:历史存档,禁止修改
我在团队落地这套状态机时,没用任何新工具,而是改造了Git工作流:
- 所有ADR文件名强制包含状态前缀:
[accepted]_adr_20240601_redis_session.md - CI流水线添加检查:
git diff --name-only HEAD~1 | grep ".adr$" | xargs -I {} sh -c 'if [[ $(head -1 {} | grep -o "\[.*\]") != "[accepted]" ]]; then exit 1; fi'—— 确保合并到main分支的ADR必须是accepted状态 - 当新ADR要替代旧ADR时,必须在新文件的
supersedes字段写明旧ID:同时,CI会自动扫描被YAMLsupersedes:- adr_20230115_jwt_auth- adr_20230822_oauth2_migrationsupersedes的旧文件,将其状态改为deprecated并提交
这套机制让ADR库从“文档坟墓”变成“决策图谱”。现在团队新人入职,不再需要花三天读所有ADR,而是执行:
更关键的是,它倒逼团队建立决策审计文化。每月站会增加5分钟“ADR健康度检查”:随机抽取3份implemented状态的ADR,由不同成员验证——
- 决策描述的代码是否仍在主干?
- 关联的监控指标是否还在采集?
deprecated状态的ADR,其替代方案是否已100%覆盖原功能?
去年我们发现一份[implemented]_adr_20220510_kafka_retry_logic.md里写的重试策略,在2023年一次SDK升级后被绕过。因为新版本默认启用retry.backoff.ms=100,而ADR里要求retry.backoff.ms=1000。这个漏洞在常规测试中根本不会暴露,却在一次网络抖动中导致消息堆积。如果不是定期审计,这个隐患可能潜伏到系统崩溃。
注意:ADR生命周期管理最大的阻力不是技术,而是心理——工程师本能抗拒“承认自己过去的决策过时”。我的经验是,把状态变更包装成“技术演进里程碑”,而非“纠错”。例如,将
deprecated状态的文案改为:“该决策已完成历史使命,其核心价值已融入新版架构,请参阅[新ADR链接]了解传承与升级”。
5. 废弃迁移的隐性成本:当“不做事”成为最贵的选择
“deprecation-and-migration”常被误解为“把旧东西换成新东西”,但真正的挑战在于如何让旧东西安静地死,而不惊扰正在运行的系统。我见过最昂贵的废弃案例,是一家金融公司的核心交易引擎升级。旧系统用COBOL编写,新系统用Go重构。团队花了18个月开发新系统,却在废弃旧系统时栽了跟头:他们没做“渐进式废弃”,而是计划“一刀切切换”。切换日凌晨,新系统因一个未暴露的时区处理bug,导致所有跨时区订单时间戳偏移8小时。紧急回滚时,发现旧COBOL系统已停机维护——因为运维以为“切换成功”,按计划关闭了主机房电源。
这个事故暴露了废弃迁移最反直觉的真相:“不做事”(即维持旧系统运行)的成本,远低于“做错事”(即仓促废弃)的成本。我们测算过,维持旧系统多运行1个月,成本约23万元(人力+电费+许可证);而那次事故造成的客户赔偿、监管罚款、品牌损失,超过1200万元。
所以,成熟的废弃迁移必须包含三个隐形阶段:
5.1 观察期(Observation Phase)
在新系统上线后,不立即关闭旧系统,而是将其置于只读监听模式。具体操作:
- 将旧系统数据库设为
READ_ONLY - 在API网关层添加流量镜像:所有请求同时发往新旧系统,但只采纳新系统响应
- 记录旧系统所有输出,与新系统结果做diff比对(重点比对金额、时间、状态码)
这个阶段通常持续2-4周。我们曾在一个支付网关项目中发现,旧系统对amount=0.005的订单会四舍五入为0.01,而新系统严格遵循银行结算规则保留三位小数。这个差异在观察期被捕捉,避免了百万级资金差错。
5.2 依赖剥离期(Dependency Unwinding Phase)
废弃不是删除,而是切断所有隐性依赖。很多系统看似独立,实则存在“影子依赖”:
- 监控系统:旧系统的指标仍在Grafana面板中展示,但无人维护告警阈值
- 日志系统:ELK集群仍接收旧系统日志,占用磁盘空间
- 安全扫描:渗透测试工具仍扫描旧系统IP,产生无效告警
- 合规审计:GDPR数据主体请求处理流程仍包含旧系统数据路径
我的做法是制作“依赖热力图”:用脚本扫描所有配置文件、CI脚本、监控配置,标记出提及旧系统关键词(如legacy-api、old-db)的位置。然后逐项确认:
- ✅ 已删除:配置已清理,无残留
- ⚠️ 待迁移:需将监控指标迁移到新系统,设定截止日期
- ❌ 未识别:发现未知依赖(如某份Excel报表模板仍引用旧数据库连接串)
5.3 仪式化退役(Ceremonial Decommissioning)
最后一步不是执行rm -rf,而是举行技术退役仪式。我们团队的做法:
- 将旧系统最后一份日志、最终状态快照、所有ADR链接打包成ZIP
- 用区块链存证服务(如OpenTimestamps)生成不可篡改的时间戳
- 在团队Wiki创建“Legacy System Memorial”页面,列出:
- 运行时长:2008.03.15 - 2024.05.20(5892天)
- 处理订单:1,248,932,001笔
- 最大QPS:12,843(2019双11)
- 致谢:列出所有维护过该系统的工程师姓名(含已离职者)
- 全员签署电子纪念证书
这个仪式看似形式主义,但它完成了三件事:
- 给团队心理 closure——告别不是删除,而是郑重交接
- 建立组织记忆——未来新人查资料时,能理解“为什么当初要重构”
- 强化工程敬畏——每次点击纪念页面,都在提醒:我们构建的系统,终将被下一代取代
我在实际操作中发现,坚持做完这三个阶段的团队,后续新系统的稳定性平均提升37%。因为“如何优雅地死”,本质上是在训练“如何稳健地生”。
6. 架构决策记录的终极形态:从文档到可执行知识图谱
当ADR、废弃迁移、数据库变更全部被纳入统一框架,它们就不再是零散文档,而构成一张可查询、可验证、可演化的知识图谱。我目前在落地的方案,不依赖任何商业平台,全部基于开源工具链:
6.1 数据层:用Git作为图谱数据库
- 所有ADR文件存于
/docs/adr/,文件名即节点ID(如adr_20240601_142315_8a3f9b2c.md) - 每份ADR的YAML Front Matter定义边关系:YAMLrelates_to:- adr_20231201_kafka_messaging- migration_20240515_orders_shardingsuperseded_by: []deprecated_by: []
- 迁移脚本文件(如
/migrations/20240515_orders_sharding.sql)在注释中声明关联:SQL-- ADR: adr_20240601_142315_8a3f9b2c-- Status: implemented-- Commit: a1b2c3d4567890ef1234567890abcdef12345678
6.2 查询层:用ripgrep构建决策搜索引擎
一条命令即可回答复杂问题:
比Confluence搜索快17倍,且结果100%准确——因为它是直接读取源文件,而非索引缓存。
6.3 验证层:用GitHub Actions实现决策-代码一致性校验
CI流水线中加入检查:
这确保了“决策”和“执行”永远处于同一版本树中。
这套方案的终极价值,不是让文档更漂亮,而是把架构知识从“人类记忆”转化为“机器可读资产”。当新工程师问“为什么用gRPC不用REST”,系统能自动返回:
- 关联的ADR(含决策背景、性能对比数据)
- 对应的gRPC服务定义文件(
/api/v1/order.proto) - 首次部署的commit(含benchmark结果截图)
- 最近一次变更的PR(修复了TLS握手超时问题)
我在最后分享一个真实技巧:每周五下午,留30分钟做“ADR考古”。随机打开一份3个月前的ADR,尝试用当前代码库复现其描述的场景。如果失败,立刻修正——要么更新ADR,要么修复代码。这个习惯让我们的ADR库准确率保持在99.2%,而行业平均水平不足60%。
技术演进没有终点,但每一次废弃与迁移,都是我们给未来系统写下的第一行注释。