我接手过一个统计报表服务核心类ReportService有 1800 多行generateReport()一个方法里塞了数据查询、月份计算、HTML 拼接还有十二个if (type 1) ... else if (type 2)分支。没人敢动它因为上一个改过它的人已经离职而线上每个月都靠它出报表。这种代码在 Java 老项目里太常见了——不是不能编译而是改了之后不知道会发生什么。后来我尝试用 AI 辅助重构这类遗留代码目标是“安全迭代”一次只改一小步、每步都有验证、随时可以回退。这篇文章把整个过程拆开讲从风险盘点、影响面分析到提示词设计、diff 红线审查再到灰度放量每一环都按安全迭代的节奏来。如果你手头也有一个 Java 老系统团队每天喊着要重构又没人敢动手这篇文章应该能给你一套可以直接照做的思路。1. 老项目为什么总是“不敢动”遗留 Java 系统的真实风险图谱1.1 你面对的可能不只是烂代码先描述一下我见过的典型遗留 Java 项目一个类两千行不罕见一个方法几百行的到处都是方法名和业务完全没有对应关系StringUtil、BusinessManager这种类名从 2008 年用到现在没人说得清它被多少地方引用项目里 Java 6 和 Java 8 的语法混着写构建脚本还停留在 Ant 或者 Maven 2几个全局静态类被十几个模块共享ThreadLocal里藏着当前用户信息稍不注意就在异步线程里丢上下文。这些不是代码风格问题是实打实的风险单元。我把它们分成三张清单来管理清单关注点作用技术栈清单JDK 版本、Spring/Servlet 版本、ORM 框架、构建方式决定 AI 生成代码时要声明什么约束高风险文件清单超大方法、全局静态状态、频繁变更文件决定护栏先装在哪里无人维护区域清单已离职同事写的、几乎没人懂的逻辑决定哪些代码绝对不碰第一次和 AI 协作重构前至少要把这三张清单拉出来。否则 AI 可能会用 JDK 17 的语法去改一段还在 JDK 6 上运行的代码或者在某个没人懂的类里自作聪明“优化”掉一段关键逻辑。1.2 业务耦合最危险的地方从来不在语法层遗留代码最危险的往往不是“呃这段代码居然这么丑”而是“这段代码为什么要这么写”。业务知识没有写进文档全部藏在if、switch、魔法数字和奇怪的字符串拼接里。举个例子。报表模块里有这么一段if (type 3) { dateStr df.format(date); } else if (type 4) { dateStr df2.format(date); }单看代码这就是两个分支格式不同而已。但实际业务是type3 表示月报格式必须是yyyy-MM-ddtype4 表示年报格式是yyyy。下游有个 Excel 导入脚本硬编码按yyyy解析。如果 AI 觉得df2命名不规范把两个SimpleDateFormat合并成同一个线上报表就会出问题。这类业务知识AI 看不到文档里也没有只有线上运行结果说了算。所以我总结了一句自己的原则在遗留系统里每一处看起来很蠢的代码背后都可能是一次线上事故的修复记录。你看不懂它为什么要这么写只能先尊重它。1.3 没有测试、没有文档、没有“敢拍板的人”老项目不敢动很多时候不是技术问题是团队心理。大家默认“能跑就别动”重构任务在 backlog 里躺了三年都没人领。这种情况太正常了没有测试意味着行为基线为零没有文档意味着唯一权威是线上结果没有能拍板的人意味着重构决策会无限延期。安全迭代的第一步不是引入 AI而是承认这种不确定性。AI 不会降低重构的风险但它能把“一次大爆炸”拆成“很多次小爆炸”配合必要的护栏就能把每次爆炸的杀伤范围控制住。这就是后面几章要做的事。注意我在这里说的“安全迭代”不是“把代码改得更优雅”而是“在改进过程中不把业务弄坏”。重构不是修 bug行为不一致就是失败。2. 动手之前先给重构装上“护栏”影响面分析、可观测性与回滚预案2.1 影响面分析先回答“谁调了它”和“它调了谁”在给 AI 丢任何代码之前先做一轮影响面分析。核心问题就两个谁调用了这段代码这段代码调用了什么我在实际项目里一般这么查# 1. 静态搜索找出所有引用 ReportService 的地方 grep -rn ReportService --include*.java src/ | grep -v target/ # 2. 搜索 SQL 中涉及的表名找出哪些代码也碰了这些表 grep -rn monthly_report --include*.java src/ # 3. 如果项目里有调用链追踪或 APM导出该方法的调用量、耗时、错误率静态搜索能回答“编译期谁引用了它”但“运行时谁真正调用了它”要靠日志和监控。这一步决定重构的优先级如果一个方法今天压根没人调用那重构它可以排在后面如果它每天被调用几万次那任何行为变化都会被无限放大必须先上护栏再动手。2.2 可观测性给重构前后建立行为基线没有基线的重构等于闭眼换零件。你在动代码之前得先回答一个问题这段代码现在每天执行多少次成功多少失败多少耗时多少入口参数长什么样出口结果有没有异常我改造遗留项目时会在关键路径上加三类观测点入口日志请求ID、参数摘要、耗时、结果状态码出口日志对数据库或外部接口的调用结果指标调用量、异常率、耗时分位数P95、P99如果项目里暂时没有 APM用日志框架配合 MDC 也能实现轻量级的全链路标识。关键是这些观测点要在重构之前就上线并且观察一个完整的业务周期。日报至少要观察一整天月报至少观察一整月。否则你只知道重构前后“今天没坏”不知道“月底会不会坏”。2.3 回滚预案安全迭代的底线工程很多团队把回滚预案当成“出事了再说”这是大忌。安全迭代里回滚必须作为发布设计的一部分在写代码之前就想好。我习惯设计三层回滚代码回滚git revert 或者重新部署上一个版本数据回滚如果动了表结构或数据要提前准备向下的迁移脚本业务回滚用特征开关把流量切回老实现特征开关是遗留系统重构里的关键工具。核心思路是新老实现并存通过配置动态路由。举个例子public class ReportRouter { private final ReportService oldReportService; private final ReportService newReportService; private boolean useNewService; public ReportResult generate(ReportRequest request) { if (useNewService) { return newReportService.generate(request); } return oldReportService.generate(request); } }这个开关必须在发布前就埋在代码里而不是出事后才加。开关状态可以通过配置中心、数据库配置表或者本地 properties 控制要点是切换动作要快、要可预期。带着开关的代码本身就是一种安全感。3. AI 在遗留项目里真正适合干的活三个低风险高收益切入点3.1 接口与实体映射让 AI 当“翻译官”遗留 Java 项目里最消耗人力、又最容易出错的任务就是 PO、DO、VO、DTO 之间的互相转换。一个订单对象从数据库到接口返回中间能转三四层。这类代码逻辑简单、字段多、写起来极其枯燥但模式非常固定AI 生成效率很高而且出错后通过编译和测试很容易发现。我的操作方式是把源类、目标类、当前已有的映射样例一起丢给 AI让它按既有风格补齐而不是让它自由发挥。提示词大致长这样这是旧系统里的 OrderVO 和新系统里的 OrderDTO。 下面是一段已确认的映射对照表请按这个风格生成转换方法。 注意源字段缺失时不要悄悄补 null请生成 TODO 注释标出来。AI 生成完初稿后我再逐个字段扫一遍。大多数情况下能省掉 80% 的敲键盘时间剩下 20% 的注意力放在命名不统一、类型不匹配、以及老代码独有的特殊映射逻辑上。这类工作是 AI 在遗留系统里最稳的切入点。3.2 重复样板代码低风险、高收益的批量清理遗留系统里到处都是重复的 try-catch 包业务异常、手写日志、空指针判断、重复的构造器。这类代码用 AI 批量生成初稿收益不只是省时间更重要的是让真实差异暴露出来。为什么这么说因为看起来“重复”的代码实际上往往有细微差别A 处记录日志B 处把异常吞掉了C 处会重试三次。如果全靠人工一行行找很容易忽略AI 生成一个“标准化版本”后我拿着它与老代码逐段 diff那些差异反而一目了然。整个过程就像给代码“照X光”重复是骨架差异才是病灶。所以我对样板代码清理的建议是AI 起草人工核对差异确认没有语义变化后再替换。不要一键全局替换。3.3 测试代码补全把当前行为固化下来这应该是 AI 在遗留 Java 项目里最值得投入的方向。老项目没有测试重构就没法证明“行为没变”。AI 可以用来生成行为特征测试目的不是验证代码“应该怎样”而是把“当前表现”固化下来。比如一个老方法对 null 入参返回 null哪怕这个行为在业务上不合理重构前它也是“当前事实”。测试先固化它重构后测试通过就说明行为没变Test void nullInputShouldReturnNullAsLegacyBehavior() { assertNull(legacyService.convert(null)); }这个思路很关键重构的时候先不管“这段代码是不是写错了”先把行为钉死。重构完成后再讨论要不要修正行为那是另一个任务不能混在一起。否则 AI 一边重构一边修 bug出问题根本定位不了。3.4 这三类重构现阶段别交给 AIAI 不是所有重构都能干特别是涉及运行时上下文、跨调用边界的改动我建议先别交给 AI重构类型为什么危险如果必须做怎么办并发与锁锁顺序、线程安全、内存可见性取决于运行时上下文请资深同事人工审查AI 只做代码阅读辅助事务与补偿跨库、消息、失败回滚边界都在方法外先画时序图再小步改每步跑完整链路测试序列化与协议兼容缓存里可能还躺着旧对象老客户端未必兼容保留旧反序列化逻辑用兼容层适配日期/时区/精度时区、闰秒、舍入逻辑最容易表面等价实际差异生成行为测试覆盖不同时区用例再交由人工确认原因很简单这些领域的判断依赖你无法全部写进提示词的全局知识。AI 只看得见你贴给它的那一段代码而并发、事务这类问题恰恰潜伏在代码片段之外。4. 实战复盘一次报表模块的 AI 辅助重构全流程4.1 背景一个没人敢碰的报表模块前面提到的ReportService.generateReport()就是我第一次认真尝试 AI 辅助重构的对象。它有多离谱呢一个方法 800 多行职责至少有三层——直接查数据库拿原始数据、用一堆if分支处理 12 种报表类型、最后拼出一段 HTML 表格。没有单元测试没有设计文档唯一“测试”是财务每月初手动核数。团队不敢动它的原因很真实上次改这模块的人已经离职type 5为什么单独走一套日期逻辑没人说得清。我决定拿它当实验对象但定了一条军规这次只做结构重排任何输出变化都算失败。4.2 第一步先锁定模块边界而不是丢一句“帮我重构”很多 AI 重构翻车都死在第一步的提示词太模糊。你丢一句“帮我把这个类重构一下”AI 就会默认往“让代码更好”的方向走而“更好”和“行为不变”经常冲突。我先把“边界合同”写进提示词这是 Java 遗留系统里的一个报表类目标是安全重构。 你只允许做结构重排不允许改变任何外部可见行为。 必须保持 1. 方法签名和返回类型不变 2. SQL 语句、表名字段名不变 3. 日期格式和输出 HTML 结构不变 4. 异常类型和日志输出顺序不变 5. 允许提取私有方法、消除重复代码、引入参数对象同时做影响面分析grep -rn generateReport找出所有调用方确认这个类只被月度任务触发没有其他入口。边界收缩得越小重构风险就越低。最后我甚至把重构范围限制在一个包内不涉及接口层和数据访问层。4.3 第二步让 AI 先生成行为快照再动代码在让 AI 动代码之前我先让它做一件事“读代码输出行为快照”。包括public 方法清单外部依赖清单静态类、Spring Bean、数据库操作所有 if/switch 分支点所有 catch 块所有配置读取点这一步是认知对齐。AI 如果连这段代码在做什么都说不清楚那它改写出来的东西更不可信。反过来说如果 AI 能把所有分支和行为都列出来团队 review 起来就有了一份明细账后续 diff 也有参照物。生成行为快照后我让团队里最了解业务的人确认了一遍“type5 的逻辑确实不能动”然后才进入下一步。这个流程不能跳。AI 分析得再好也不代表业务知识被真正识别出来了它只会按字面逻辑复述代码。4.4 第三步分段重构每段都过编译和测试800 行的方法是不是应该一次性丢给 AI 重写我试过不行。一旦 diff 超过几百行人工审查就成了走过场出了问题根本定位不到是哪一个改动引入的。所以我把它切成了三段一次只重构一段分段内容验证方式第一段数据获取查询参数组装、SQL 调用编译通过 行为测试通过 手工触发当月报表第二段聚合计算12 个 type 分支、日期处理编译通过 行为测试通过 每个 type 分支跑一遍第三段输出生成HTML 表格拼接编译通过 行为测试通过 和旧输出逐字对比每一段交给 AI 后我要求它只返回这一段的改动改完立刻编译、跑测试、做 review确认没问题再进下一段。我给自己定了一个硬指标每次 git diff 尽量控制在 100 行以内。超过这个数就说明切得还不够细。4.5 第四步diff 审查时我抓到的三个典型问题AI 生成的代码表面看起来漂亮但只要你逐行 review总能找到一些隐蔽的语义漂移。这轮重构里我抓到了三个典型问题每个都值得单独说第一个问题AI 把a b悄悄改成了Objects.equals(a, b)。它可能觉得自己更健壮但旧逻辑里a b会在某个值真的为 null 时走一条完全不同的分支用Objects.equals把两边的 null 都视为相等行为就变了。这属于典型的好心办坏事。第二个问题AI 把字符串拼接改成了StringBuilder顺手丢了空字符串的处理。Java 里str 在str为 null 时会输出字符串null而String.valueOf(str)也是null但如果 AI 写成sb.append(str)再toString()看起来一样实际上某些老逻辑里对 null 有特殊判断一改就崩。这种细节不跑线上数据根本发现不了。第三个问题AI 提取重复代码时把两段几乎一样的日志打印合并了导致日志顺序变化。旧逻辑是先记录“开始计算金额”再记录“开始生成 HTML”合并后顺序反了下游的日志分析脚本就对不上了。日志看起来小事但对运营分析来说是契约。审查完之后我的结论是AI 负责把结构理顺但线的最终效果仍然取决于人工的逐行核对。这个环节省不了。5. 让 AI 只改该改的提示词设计、diff 红线与人工审查清单5.1 提示词里必须写清楚的五件事经过几次实践我总结出一个相对完整的重构提示词模板每次用它都能减少大量返工角色你是 Java 遗留系统重构助手本次目标是安全重构不是性能优化不是修复潜在 bug。 输入以下是要重构的类/方法。 约束 1. 保持方法签名、返回类型、异常类型不变 2. 保持 SQL、表名、字段名不变 3. 保持日期格式、输出格式、日志内容与顺序不变 4. 只允许做结构重排提取方法、提炼参数对象、消除重复代码 5. 对任何“看起来像 bug 但不属于本次任务”的地方保留原样并用 TODO 注释说明 输出格式 1. 重构后的完整代码 2. 一份变更说明列出所有你判断为“行为不变”的理由 3. 如果你认为有任何行为可能变化单独标出等待人工确认 自检生成代码前先列出现有代码中所有“看起来可疑但必须保留”的行为。五个关键点是角色、输入、约束、输出格式、自检。其中自检最重要它逼着 AI 在动手之前先“复述”它对代码的理解等于一道额外的安全闸门。5.2 diff 红线哪些改动一出现就该挡回去我给自己列了一张 diff 红线表凡是出现右侧情况的一律打回重新生成不讨论允许出现必须拦下新增私有方法常量值变化提取局部变量if/switch 条件变化哪怕看起来等价方法内部语句重排SQL、表名、字段名变化把魔法数字提取为常量值不变日期格式字符串变化把重复日志封装为方法顺序不变日志文本、级别、顺序变化精简注释异常类型或抛出位置变化资源获取/释放位置变化序列化逻辑变化方法签名变化为什么“看起来等价”也要拦因为老代码里那些非典型的写法很可能就是针对某个历史线上问题的特殊处理。你能证明它等价才能改你不能证明就保持原样。AI 的可信度来自你给它划的红线而不是它对代码的“理解”。5.3 人工审查清单比代码规范更重要的六条红线AI 生成的 diff 不是最终交付物人工审查才是。我每次 review 时过这六条行为等价性重点看边界输入——null、空集合、超大值、重复值。常规路径没差别不够边界没差别才算数。异常路径catch 了什么、重新抛了什么、有没有悄悄吞掉异常。老代码里的 catch 块可能是故意为之。资源释放数据库连接、文件流、锁是否在异常情况下也能关闭。AI 重构时最容易顺手改动资源生命周期。并发语义有没有改到共享变量、静态状态、线程安全边界。这个 AI 基本感知不到。外部契约接口签名、消息结构、缓存 key、表名、返回 JSON 字段。任何外部同学依赖的东西都不能动。依赖方向重构后模块是否反向依赖了不该依赖的东西。遗留项目里这种问题最隐蔽。我的习惯是并排打开旧版本和新版本用 IDE 的 Diff 工具逐块高亮盯着每一处差异看而不是读 AI 生成的最终代码。因为最终代码太“干净”了很容易让人放松警惕而 diff 上的每一行都是风险点。6. 小步提交、灰度放量与长尾节奏安全迭代的收尾工作6.1 小步提交让每次变更都可解释、可回退重构完成不代表可以一次性提交一个大 commit。我有一次因为图省事把三段重构和一个格式调整打成一个提交后来线上出问题想通过 git bisect 定位是哪一次改动引入的根本没法定位。从那以后我强制自己遵守两条规则一个提交只做一种重构动作提交信息明确标注行为是否变化refactor: extract>