旧项目改造如何形成可追踪闭环

接手一个老项目，最让人心里发毛的往往不是代码写得有多乱，而是你根本不知道改完这一处，哪个角落会突然崩掉。登录挂了、支付回调失灵、导出报表变成乱码，这些事儿在旧系统里太常见了。问题不在于代码旧，而在于改动没有边界——修了一个 Bug，却捅出三个新坑，而且根本说不清楚到底是哪一步改坏的。

想把旧项目改造做成可追踪的闭环，核心思路其实像记账：每笔改动都得能查到来龙去脉，出了问题能快速定位是谁、在什么时候、因为什么原因改的。

第一步不是急着改代码，而是先把“家底”摸清楚。项目能在目标 PHP 版本上跑起来吗？依赖包有没有长期不更新、甚至已经停止维护的？很多人一上来就盯着业务逻辑看，结果改了半天才发现，底层某个废弃函数早就在新版 PHP 里报错了，或者 Composer 锁定的那个老旧依赖包带着已知安全漏洞。先把运行环境和依赖边界搞清楚，后续每一步才有底气。

有了这个基础，下一步是用工具建立质量基线。PHPStan 这类静态分析工具，不是让你一次性把所有报告都修完——老旧项目跑一遍高严格等级，报告能刷出几千条，团队根本消化不了。更务实的做法是从低等级开始，只盯那些会影响稳定性的问题：控制器里的空值没处理、支付回调的参数类型对不上、数据库查询封装里藏着拼接 SQL 的隐患。关键是要让检查结果可比较——这次提交新增了哪些错误，是不是碰了认证、上传、回调这些高风险目录。这样出问题的时候，能马上判断是业务改动导致的，还是依赖升级带来的连锁反应。

安全加固也要有优先级。旧项目的安全漏洞不会均匀分布，它们扎堆出现在可被外部触发的入口：用户输入、文件上传、登录认证、第三方回调。这些地方一旦被绕过，影响面远大于后台某个管理页面的代码质量问题。优先堵这些缺口，比漫无目的地扫全站高效得多。

修 Bug 的时候，最忌讳一把梭重写。很多看着混乱的代码，其实承载着真实的业务规则——特殊折扣逻辑、历史订单状态、老客户端的兼容返回格式。直接推翻重来，很容易把这些隐性规则一起丢掉。更好的方式是模块化替换：先用 Git 建独立分支，每个修复只动一个明确的边界，改完只验证跟这个模块相关的行为。如果一个旧函数被后台列表、前台页面、导出 CSV 三处同时调用，别直接改函数内部逻辑，而是加一层适配，让旧调用方保持不变，新调用方走安全实现，再逐步迁移。

这套流程走下来，真正有价值的不是某一个技巧，而是形成了一套可重复的工程习惯：环境评估、依赖审计、静态分析建立基线、安全入口加固、模块化小步替换。每一步都有记录，每次改动都能回滚、能归因。旧项目不怕代码老，就怕改了说不清。只要闭环形成了，二次开发就不再是凭运气干活，而是有章可循的稳定操作。