接手一个已经运行多年的项目,和从零开始写代码是完全不同的体验。OTTO 项目在我手里走过了五个年头,从最初接手时的手忙脚乱,到后来逐渐摸出一些门道,中间踩过的坑、交过的学费,值得整理成一份可复用的经验清单。这篇文章不谈抽象的方法论,只讲那些在实际维护中真正起作用的做法和判断。
先理解“为什么”,再动“怎么做”
长期维护的项目最危险的动作,是维护者在不理解历史决策的情况下贸然重构。OTTO 项目里有一段看起来非常别扭的配置加载逻辑,我最初花了三天想把它改简洁,结果上线后才发现那段“冗余”代码处理的是某个早期客户遗留的兼容格式。类似的教训让我形成了一个习惯:任何看起来不合理的代码,先假设它有理由,再去验证这个理由是否还成立。
具体做法上,我建立了一个“决策日志”文件,记录每次重大变更的背景、备选方案和被否决的原因。这份日志不追求文采,只求后来者(包括半年后的自己)能快速还原当时的约束条件。维护三年以上的项目,代码本身会说话,但说不了“为什么没选另一条路”,而这恰恰是最容易重复踩坑的地方。
把依赖管理当作一等公民

Otto 项目早期最大的隐性成本来自依赖失控。第三方库版本分散、间接依赖冲突、某个底层包停止维护,这些问题往往在紧急发版时集中爆发。后来我们做了三件事,效果显著:
- 锁定文件必须入库,且定期主动升级。不是等到安全告警才动,而是每季度安排一次小范围升级,把风险摊薄到日常。
- 为核心依赖设置“退出预案”。对每一个深度耦合的外部库,评估替换成本,并记录在案。真正需要换的时候,不至于从零调研。
- 区分“直接依赖”和“传递依赖”的维护责任。传递依赖出问题时,优先在直接依赖层解决,避免打补丁式地层层覆盖。
依赖管理的本质不是追求最新,而是保持可控。一个版本落后但稳定的依赖,远好过一个版本新潮却随时可能断裂的依赖。
测试是维护者的安全带
长期项目最怕的不是 bug,而是“改一处、崩三处”的连锁反应。Otto 项目的测试策略经历过一次明显转向:从追求覆盖率数字,转向保护关键路径。我们的做法是,把测试分为三层——核心业务逻辑的单元测试必须覆盖边界条件;跨模块交互用集成测试兜住;至于那些频繁变动、生命周期短的展示层代码,不强行写测试,而是靠快速回滚机制兜底。
另外一点很重要:测试代码也要当产品代码维护。过时的测试比没有测试更糟糕,因为它会给出虚假的安全感。我们规定,任何一次功能变更如果导致测试失效,必须同步更新测试,不允许“先跳过、以后补”。
文档要写给“未来的陌生人”

长期维护项目中,文档的最大读者不是当前团队,而是半年后接手的人。Otto 项目的文档体系做了减法:删除大量过时的设计文档,只保留三类——环境搭建与本地运行指南、架构总览与关键取舍说明、常见故障排查手册。每类文档都指定了负责人,并在每次相关变更时同步更新,更新动作纳入代码评审清单。
一个实用技巧是,把文档中的示例命令做成可直接复制运行的片段,并定期在干净环境中验证。文档里跑不通的命令,比没有文档更消耗信任。
建立节奏,而不是依赖英雄
长期维护最隐蔽的风险,是项目逐渐依赖某一个人的记忆和判断。Otto 项目曾经有段时间,只有一位同事清楚部署流程的全部细节,他休假时整个团队都紧张。后来我们把关键操作全部脚本化,并实行轮值制度,让至少两个人熟悉每条关键路径。维护工作靠的是稳定的节奏和可交接的流程,而不是某个人的超常发挥。
回过头看,长期维护的核心并不复杂:尊重历史、控制依赖、守住测试、写好文档、分散风险。这些做法单看都不新鲜,难的是在日复一日的迭代中坚持执行。Otto 项目还会继续走下去,这份经验清单也会继续增补,但上面这几条,大概会一直适用。















暂无评论内容