接手“无文档、无交接”的老系统：一段抢救记录

技术笔记 · good fun 谷放

企业里有一种活儿很少被写：不是从零开发，也不是常规迭代，而是接手一套没人交底的老系统——上一任开发者退场、文档为零、而它还在线上跑着。

在协助维护老系统时，我们曾接手过类似的项目（细节已泛化处理）：一个培训类小程序上的集成半成品，要求是“先让它稳下来，再继续往下做”。这篇笔记记录这次抢救里最有复用价值的部分：方法、踩过的两个坑、一份可以带走的清单。

01先立规矩：生产环境从“只读”起步

接老系统的第一大忌，是上来就改。我们给自己立的规矩是三句话：

• 所有诊断改动只加日志，不改业务逻辑；
• 进生产前先想好怎么回滚；
• 先读代码、先看日志，把“系统本来的样子”摸清楚，再动手。

老系统的每一次改动，都可能踩中你不会知道的依赖。摸清现状的成本，永远低于误伤之后的修复成本。

02案例一：藏在“眼皮底下”的 UI 事故

现象：用户点击一个按钮，弹层死活不出现；日志、接口、数据全都正常。

根因：一个全局公共弹层在历次改版里层级被叠到了很高（近千），而业务弹层只有几十——内容一直都在，只是被“盖住了”。

三条教训：

• 复杂系统里，“看不见”的问题不一定是功能坏了，可能是被别的图层盖住；
• 排查顺序可以从最笨的地方开始：先查“谁盖住了谁”，再往业务逻辑里找；
• 公共组件的一次“顺手升级”，半年后可能以完全无关的 bug 形式冒出来——公共层的每次变更都值得留痕。

03案例二：“修好了”却没有留在代码里

现象：一个早已判定修复的问题，过一阵又冒了出来。

追查：翻代码历史后发现——当初“修好了”的结论没错，但那次的修复从来没有被写成代码；顺带还认出几段“在跑、但结果没人用”的死代码。

两条教训：

• “告知过的修复”不等于“代码里的修复”。接手老系统时，把它当成一次对账：把“应该已经修了”的项逐条拿到代码里核对；
• 如果交付只停在“我改了什么”的口头交代，下一个接手的人还会再踩一遍。改动、结论、验证方式，都落进版本记录。

04一份可以带走的清单

接手“无文档、无交接”的系统时，我们会按这份清单过一遍：

1. 生产只读起步：先日志后改动，改动必带回滚；
2. 现状盘点：关键路径（登录 / 支付 / 核心业务）逐条走通；
3. “声称已修”的项：逐条到代码里核对；
4. 层级 / 公共组件类问题：先查“谁盖住谁”，再查业务逻辑；
5. 每次改动：最小面、可回滚、留痕迹（改了什么 + 为什么 + 怎么验证）；
6. 交出去时：写清现状与坑，让下一位接手的人不用从零考古。

结语

这类项目的价值不在“会写代码”，而在能在不确定的环境里把问题一条条钉死、把系统安全地扶起来。如果你手上也有这样一套“没人交接、还得继续用”的系统，欢迎聊聊。