接手三年没人管的项目，先画图再改码

接手一个三年没人维护的项目，第一件事不是读代码，是搞清楚它现在到底还能不能跑起来。我们上周接到一个管理系统，原作者离职两年，文档只有一份半年前的部署手册，里面写的服务器地址已经换了三台。上周做的事可以当个模板记下来。第一步是先把它跑起来，不追求跑对，只追求不报错。找到入口文件、依赖清单、启动命令，三个都对上再说。这一步通常会卡在依赖版本上，锁文件在就按锁文件装，锁文件不在就把版本全部钉死到当时的最新版本，别用 ^ 或 ~ 让它自动升级，否则你会遇到一堆跟你无关的兼容问题。第二步是建立最小可观测性。在启动时打一行日志说明当前加载的配置文件路径和关键参数，在处理请求的入口打一行说明收到了什么、返回了什么。这两行日志能省掉后面一半的排查时间。第三步是画一张调用图。不要读全部代码，只看入口函数往下追三层，标出哪些是外部依赖、哪些是数据库操作、哪些是纯计算。三层之外的东西先当黑盒。第四步是找出所有的定时任务和后台上报。这类东西最容易被忽略，因为它们不在主流程里，但一旦出错就是数据不一致，而且往往几天后才发现。第五步才是读业务逻辑。到这一步你已经有了一张地图，读代码时知道每块属于哪里，不会迷路。整个过程我们用了四天，产出是一份包含启动方式、依赖版本、调用图、定时任务清单的接手文档。后来源码改动只花了一天，但前面四天不算浪费，因为没有那张图，改一行都得全项目搜索。接手老项目最贵的成本不是改代码，是不知道自己改的这行会影响到哪里。文件路径和关键参数，在处理请求的入口打一行说明收到了什么、返回了什么。这两行日志能省掉后面一半的排查时间。第三步是画一张调用图。不要读全部代码，只看入口函数往下追三层，标出哪些是外部依赖、哪些是数据库操作、哪些是纯计算。三层之外的东西先当黑盒。第四步是找出所有的定时任务和后台上报。这类东西最容易被忽略，因为它们不在主流程里，但一旦出错就是数据不一致，而且往往几天后才发现。第五步才是读业务逻辑。到这一步你已经有了一张地图，读代码时知道每块属于哪里，不会迷路。整个过程我们用了四天，产出是一份包含启动方式、依赖版本、调用图、定时任务清单的接手文档。后来源码改动只花了一天，但前面四天不算浪费，因为没有那张图，改一行都得全项目搜索。接手老项目最贵的成本不是改代码，是不知道自己改的这行会影响到哪里。