Skip to content

AI 编程助手:补全、重构与评审 ​

本篇要点:你能判断哪些编码任务放手交给助手、哪些必须自己盯着,并且有一套验收动作能把它的错误挡住。 前置文章:《提示词基本功:普通人也能稳定复现》讲了指令四要素,这一章把它搬进编辑器,换成代码这种"能跑就是对的"的场景。

一、为什么需要它 ​

先看一条日志。2026 年 7 月,一个后台项目上线当天出的故障:

text
java.lang.NullPointerException: Cannot invoke "Coupon.getAmount()"
  because the return value of "CouponService.getByOrder(Order)" is null
	at com.shop.order.OrderCalc.calc(OrderCalc.java:47)

出事的这一行是助手补的。补全的时候,上下文里有 couponService.getByOrder(order) 的调用,助手顺着写出了 order.getCoupon().getAmount(),看起来天衣无缝。

问题在三天前的另一处改动:优惠券服务在某次重构后可以返回 null 了。助手不知道这件事,因为它只看到了当前文件的几十行。

这不是助手的错。它看到了你给它的那一小块,就只对那一小块负责。你的仓库里有 4 万行代码、一次没写进文档的约定变更、三个只在周五晚上触发的边界条件,这些都不在它的视野里。

这一章的目标不是让你少用编程助手,是让你明白它到底"看见"了什么,然后在它看不见的地方补位。

二、核心概念 ​

2.1 三种交互形态,视野各不相同 ​

形态它看到什么适合什么不适合什么
行内补全当前文件上下文、光标前后若干行重复样板、顺着上文就能推出的下一步涉及跨文件的逻辑、需要改接口的活
对话式改码你选中的代码块 + 你贴的内容局部重构、解释这段为什么慢需要全仓库搜索才能判断的改动
仓库级助手索引过的整个仓库找调用点、跨文件改名、读懂陌生项目索引过期时的判断、依赖私有环境的配置

表 3-1 三种交互形态的视野边界

这张表解释了一个常见困惑:为什么同一个模型,聊天里答得很好,编辑器的补全却给你一个不存在的 API。

因为补全的视野窄。它没读过你项目里那个 OrderMapper,只能按命名习惯猜一个最像的方法名。命名越规范的项目,这种猜测越容易蒙对;越不规范,越容易编。

2.2 接受率不是质量指标 ​

很多 IDE 会显示"你本周接受了 62% 的建议"。这个数字不该拿来当成绩。

接受率高的两种可能:一是补全确实好用,二是你按 Tab 按得太快。后者更常见,尤其是在写样板代码时,人处于低警觉状态。

一个可用的替代指标是被接受后的回滚率:接受了的建议里,有多少在十分钟内被你改掉或者删掉。这个数字超过三成,说明你接受得太随意。

2.3 测试生成:先写测试,再让它改代码 ​

这是编程助手上最稳的一个用法,也是最被浪费的一个。

顺序很关键。正确顺序是:你写出失败的测试(哪怕是助手帮你写),确认它因为正确的原因失败,再让助手改实现直到测试通过。

反过来做——先让它改代码、再让它补测试——它补的测试会照着实现写。实现里有个 off-by-one,测试就会把这个 off-by-one 当成期望值。测试全绿,bug 还在。

类比体检。先定标准再化验,叫体检;先化验再定标准,那叫配合结果。

2.4 仓库级理解:索引是有时效的 ​

仓库级助手靠索引工作。索引通常包含文件路径、函数签名、部分函数体。它有三个已知的盲区:

一是刚改的代码。你今天上午改的接口,索引可能还没更新。 二是生成代码与第三方库源码。node_modules 和构建产物一般不入索引。 三是运行期才成立的事实:配置中心里的开关、数据库里的枚举值、只在某个环境启用的分支。

盲区二和三决定了:凡是涉及"这个值在线上是什么"的判断,助手的答案都不可信。

2.5 评审:把助手当提交者,不当作者 ​

代码评审的价值在于有人真的读过。但如果这个"人"是助手,评审就退化成了格式检查。

可行的做法是把助手放进两个位置:

第一个位置是第一道筛子。让它先扫一遍 diff,专找四类问题:空值与边界、资源未释放、异常被吞、日志里泄露敏感信息。它在这四类上比人稳定。

第二个位置是被审对象。它自己写的代码,必须由人过一遍,重点看"它有没有引入项目里不存在的约定"。

图 3-1 编程助手的正确站位:测试在前,助手在中间,人在最后一道

如图 3-1 所示,助手承担的是"从红到绿"这段最费体力的活,判断仍然在人手上。顺序颠倒过来,测试就失去了裁判资格。

三、动手实践 ​

用一段真实代码复现那个空指针。这段代码是脱敏后的版本,逻辑没改。

3.1 先看助手会写出什么 ​

原始代码是这样的:

java
// CouponService.java(重构后:查不到优惠券时返回 null)
public Coupon getByOrder(Order order) {
    return couponMapper.selectByOrderId(order.getId());   // 可能返回 null
}

把光标放在 order 后面,助手补出的是:

java
BigDecimal amount = order.getCoupon().getAmount();

运行结果(对一笔没有用券的订单跑):

text
java.lang.NullPointerException: Cannot invoke "Coupon.getAmount()"
  because the return value of "CouponService.getByOrder(Order)" is null
	at com.shop.order.OrderCalc.calc(OrderCalc.java:47)

一样的空指针,一样的行号。助手不是不会写空判断,是它不知道这个方法会返回 null——它的视野里,getCoupon() 从来就是有值的。

复现这一步只用了两分钟,但它把"助手会犯错"从一句提醒变成了一个你能亲自跑出来的事实。后面三小节都在处理同一个问题的不同侧面:怎么给它准确的约定(测试)、怎么限定它的改动范围(指令约束)、怎么发现它编造的调用(反向用例)。

3.2 用测试把约定钉住 ​

先写一个必定失败的测试,把"没券"这个场景固化下来。

java
// OrderCalcTest.java
@Test
void 未使用优惠券时_金额等于原价() {
    Order order = new Order("T-1001", new BigDecimal("128.00"));
    when(couponService.getByOrder(order)).thenReturn(null);   // 关键:显式造出 null

    assertEquals(new BigDecimal("128.00"), calc.total(order));
}

运行结果:

text
OrderCalcTest > 未使用优惠券时_金额等于原价 FAILED
    java.lang.NullPointerException at OrderCalc.java:47
1 test completed, 1 failed

失败的原因正确——就是那个空指针,不是断言写错、不是环境问题。这一步不能跳,跳了你后面所有的绿都是假的。

3.3 让它改,但限定改法 ​

给助手的指令里要带约束,否则它会顺手重构三个文件。

markdown
任务:修复 OrderCalc.calc 的空指针,使上面这个测试通过。
约束:
- 只改 OrderCalc.calc 一个方法,不改 CouponService 的返回约定
- 不改任何测试文件
- 不引入新依赖
- 未使用优惠券时,金额等于原价
输出:只给 diff,不要解释。

运行结果(它给的 diff):

diff
--- a/src/main/java/com/shop/order/OrderCalc.java
+++ b/src/main/java/com/shop/order/OrderCalc.java
@@ -44,8 +44,9 @@
     public BigDecimal total(Order order) {
-        BigDecimal amount = order.getCoupon().getAmount();
-        return order.getPrice().subtract(amount);
+        Coupon coupon = couponService.getByOrder(order);
+        if (coupon == null) {
+            return order.getPrice();
+        }
+        return order.getPrice().subtract(coupon.getAmount());
     }

预期输出(应用 diff 后再跑同一条测试):

text
OrderCalcTest > 未使用优惠券时_金额等于原价 PASSED
1 test completed, 1 passed

这次对了。注意它做的第一件事是把 order.getCoupon() 改成 couponService.getByOrder(order)——它从测试的 when(...) 里读到了真实的调用方式。给它测试,等于给它一份准确的接口说明。

3.4 补一个反向用例,防止修反 ​

只测"没券"还不够,还得测"有券",否则把实现改成永远返回原价也能全绿。

python
# gen_cases.py —— 生成边界用例清单,供人挑选用
cases = [
    ("无券",        None,           "128.00", "128.00"),
    ("满100减20",   "20.00",        "128.00", "108.00"),
    ("券额等于原价", "128.00",       "128.00", "0.00"),
    ("券额大于原价", "200.00",       "128.00", "?"),      # 需要问业务:能否为负
]
for name, coupon, price, expect in cases:
    print(f"{name:<10s} 原价 {price:<7s} 期望 {expect}")
print("共", len(cases), "条,其中 1 条期望值未定")

运行结果:

text
无券         原价 128.00  期望 128.00
满100减20    原价 128.00  期望 108.00
券额等于原价     原价 128.00  期望 0.00
券额大于原价     原价 128.00  期望 ?
共 4 条,其中 1 条期望值未定

第四条是助手不会替你问的问题。券额大于原价时金额能不能为负,是业务约定,不是技术问题。这类"未定"必须回去问人,不能让它猜一个然后补上测试。

四、常见误解 ​

很多人以为助手写的代码要先跑通再说。实际上先看 diff 比先跑更快:很多错误(编造的 API、吞掉的异常、写死的时间戳)跑起来不报错,但会在两周后炸。跑通只能证明它没崩,不能证明它对。

很多人以为让它重构能顺便清理技术债。实际上它的重构是"局部最优"的:把当前这个方法改漂亮,不管别处还有七个同样的写法。真要清理,得你自己先搜出全部调用点,再让它按同一套改法批量处理。

很多人以为助手引用的库都是真的。实际上编造 API 是它的高频错误,尤其是版本较新的库和小众库。判断方法很土但有效:让它给出方法所在的类全名和文档链接,你去官方文档搜一遍。搜不到就是编的。

五、小结 ​

《提示词基本功:普通人也能稳定复现》的四要素在这里换了个说法:约束变成「只改这一个方法」,输入变成「这段测试」,格式变成「只给 diff」。工具变了,要求没变。

  • 三种形态的视野不同:补全看当前文件,对话看选中块,仓库级看索引。视野之外的东西它一律靠猜。
  • 接受率不是质量指标,回滚率才是。超过三成,说明按 Tab 太快。
  • 正确顺序是先写失败测试,再让它改实现。反过来,测试会照着 bug 写。
  • 索引有盲区:刚改的代码、第三方库、运行期配置。涉及"线上是什么值"的判断不能问它。
  • 评审时让它当第一道筛子(空值、资源、异常、日志),人当最后一道(有无编造的约定)。

六、相关文章 ​

编辑器里的活有个前提:你得先打开文件、选中代码、一句句描述。有些活根本走不到这一步——改 200 个文件里的配置、给一批数据跑清洗、按规则重命名一批资源。这类活要交给终端里的 Agent,而它拿到的是你机器的写权限,边界问题比编辑器里严重得多。

继续阅读:[《终端与 Agent CLI:把重复劳动交出去》 终端与 Agent CLI:把重复劳动交出去](/guide/ai-tools/ai-agent-cli-workflow.html)