接手遗留系统生存指南：7 天摸清陌生代码库

接手一个陌生的遗留系统，是每位工程师都绕不开的关卡。没有文档、没有原作者、代码里还堆着说不清的遗留系统技术债——本文用一套 7 天上手清单，帮你从一头雾水到能独立改 bug、排故障。更重要的是，要在”读懂它”和”别被它拖垮”之间找平衡：目标是七天后的你能独立交付改动，而不是把每一行都背下来。

一、为什么接手遗留系统这么难

新项目可以从零设计，遗留系统却要你同时扮演”考古学家”和”急诊医生”：业务规则散落在十几年前的注释里，唯二懂代码的人已经离职，而线上还在持续吐故障。最忌讳的两种心态，一是”这代码太烂了我重写一遍”，二是”闷头从头读到尾”。前者会引爆兼容性地雷，后者三个月也读不完。正确做法是带着问题读、按天推进、边读边写文档。

二、第 1–2 天：先画一张”系统地图”

别急着读代码。先搞清楚它部署在哪、依赖谁、流量从哪进。翻 CI 配置、docker-compose、Nginx 反向代理，把”用户请求 → 网关 → 服务 → 数据库”的链路画成一张图。顺手用 git 历史看清仓库的活跃度与核心贡献者，定位”谁最懂这块”可能已经指向了离职同事的提交：

# 看清核心贡献者与仓库活跃度
git shortlog -sne --all | head -20
git log --since="1 year ago" --pretty=format:'%ad %an' --date=short \
  | sort | uniq -c | sort -rn | head -20

这两行能立刻告诉你：哪些是高频改动文件（大概率最易出 bug），哪些模块已经常年无人碰（可能是稳定区，也可能是雷区）。关于如何高效读源码的方法论，可以参考《高效阅读源码：工程师突破瓶颈的实战方法》。

三、第 3–4 天：把它跑起来，顺着请求读代码

读代码的最高效率方式不是”通读”，而是顺着一条真实请求走到黑。先在本地把服务起起来，在入口处打一条带 traceId 的日志，然后造一个最小请求，跟着日志把完整调用链读完：

// 在控制器入口打一条带 traceId 的日志，顺着它读完整调用链
log.info("[traceId={}] enter {} args={}", traceId, method, args);
// 再到下游 service / dao 各补同样一行，串联起一次请求的完整路径

读完一条主链路，你对系统的理解会从”一堆文件”变成”一条有头有尾的流程”。遇到看不懂的分支，先记下来、别卡住，等整体骨架清晰了再回头啃细节。一个小技巧：顺手在笔记里给每个关键函数贴一句话标签，七天后回看时你会感谢现在肯花这三十秒的自己。

四、第 5 天：读懂数据模型与技术债

代码之上，数据才是系统的真相。找出最大、最常被改动的表，它们通常承载着核心业务。以 PostgreSQL 为例：

-- 找出行数最多、最"重"的表，优先理解它们的字段含义
SELECT relname, n_live_tup
FROM pg_stat_user_tables
ORDER BY n_live_tup DESC
LIMIT 10;

同时翻一遍数据库的迁移脚本（Flyway / Liquibase / 自建 SQL），你能看出哪些字段是”临时加的”、哪些索引是事故后补的——这些就是《技术债不是原罪：在速度与质量间做工程决策》里说的、真实发生的取舍痕迹。

五、第 6 天：找历史的”伤疤”

遗留系统的坑，八成已经在过去踩过。去翻 issue、线上事故群、以及团队的《技术复盘实战：用 Postmortem 把故障变成团队资产》记录。哪里出过 P0、哪次发布回滚了、哪个接口被限流过——这些”伤疤”就是你的避雷清单，比任何文档都值钱。

六、第 7 天：产出你的上手文档

第七天别再”只读”，要把前面六天的心得落成一份文档：架构图、关键表说明、常见故障与解法、本地起环境步骤。写文档的过程本身就是二次确认。可参照《技术文档写作实战：把复杂方案写人人能懂的文档》的结构来组织。这份文档未来会救下接手你的下一个人。

七、7 天上手清单

八、新手最容易踩的 3 个坑

坑一：一上来就重写。你还没读懂旧系统”为什么这样写”，重写必然丢掉隐藏的业务约束。
坑二：闷头通读。没有目标的阅读会在第 3 天就耗尽耐心，永远读不完。
坑三：忽略测试。遗留系统的测试往往是唯一可信的”行为说明书”，跑一遍测试比读十遍注释更管用。改完代码记得走一遍《代码评审文化：高效 CR 落地实战指南》里的自查清单再提交。

十、让阅读事半功倍的 4 件武器

读代码不是只靠眼睛。善用工具能把一周的活压缩到三天，尤其面对动辄几十万行的老代码库：

# 用 ripgrep 按业务关键词反查调用点，比翻目录快得多
rg -n "createOrder" --glob '!*.test.ts' src/
rg -n "ORDER_PAID" migrations/

• 全局搜索大法：用 rg / ag 而不是肉眼翻目录，按方法名、报错文案、表名字反向定位调用点。
• 调用层级图：IDE 的 “Find Usages / Call Hierarchy” 一键展开谁调了谁，比读 import 快十倍。
• 本地测试当探针：在怀疑的分支打断言、跑单测，让测试失败来告诉你真实的执行路径。
• 数据库客户端直连：直接 SELECT 几条真实数据，字段含义比注释诚实得多。

把这几件武器和前面的 7 天节奏结合，你会发现自己不是在”啃”系统，而是在”解”系统——每一次搜索命中、每一条调用链打通，都是把陌生变成熟悉的进度条。

九、小结

接手遗留系统不可怕，可怕的是没有节奏地硬啃。用”先地图、再主链路、后数据、查伤疤、落文档”的 7 天节奏推进，你会从恐惧变成掌控。记住：你不是来崇拜旧代码的，你是来让它继续健康跑下去的。