张彦峰ZYF头像
写完了不等于能合并:用AI完成一个Java功能的全过程封面图

写完了不等于能合并:用AI完成一个Java功能的全过程

目录

一、一句话需求为什么换不来一次合并

(一)能编译、能演示、能合并是三件事

(二)失控的四种典型现场

(三)五段闭环:把生成关进流程里

二、开工之前:给AI一个有边界的工作台

(一)示例功能与验收标准

(二)隔离的工作区:分支与工作树

(三)写进仓库的规则:记忆文件与命令清单

三、第一段:分析代码——只读优先

(一)分析提示词:明确要什么、禁止什么

(二)四样交付物:清单、链路、复用点、疑问

(三)怎么判断AI真的读懂了

(四)分析报告也要落盘

四、第二段:制定计划——把方案钉进文件

(一)计划模式的机制价值

(二)一份可执行计划长什么样

(三)人工审计计划的三个焦点

1、隐藏范围

2、测试设计是否证明行为

3、业务规则谁来定

(四)计划落盘:从聊天记录到需求文件

五、第三段:实现功能——在边界内执行

(一)实现提示词的硬约束

(二)核心代码:状态机、幂等、金额与并发

1、幂等入口:请求号先行

2、金额账本:BigDecimal与超额校验

3、并发防线:条件更新

4、审计闭环:谁在什么时候退了多少

(三)实现期的纠偏:小步反馈而不是推倒重来

六、第四段:运行测试——让证据代替感觉

(一)两层运行:先定向、后全量

(二)AI补测试的清单

(三)修复回路与叫停条件

七、第五段:审查差异——最后一道人工闸门

(一)先看改了什么,再看改得对不对

(二)第二视角:让另一个会话做只读复核

(三)提交、PR与可追溯性

八、从一次跑通到长期可用

(一)验证成本决定委托边界

(二)风险分级:不是所有环节都值得自动化

(三)常见失败模式与对策

(四)给团队的落地清单

九、结语

参考资料


干货分享,感谢您的阅读!

把一句话需求丢给编码智能体,几分钟后拿回一屏幕新代码——这件事在今天已经不稀奇。

稀奇的是:这些代码里,有多少能在当天通过评审、合并进主干、并且三个月后没有人骂它。很多工程师的体感是割裂的:AI生成代码的速度是自己手写的十倍,但从"生成完毕"到"可以合并"之间的距离,有时反而比自己从头写还要长。差距不在模型能力,而在过程控制——生成是一瞬间的事,合并是一个流程的事。

这回我们用一个完整的Java功能作为贯穿案例,把"用AI做完一个功能"拆成五个可验证的阶段:分析代码、制定计划、实现功能、运行测试、审查差异。每个阶段都回答三个问题:这一步让AI做什么、禁止它做什么、人在哪个位置做什么判断。

思考后,结合自己以往的工作经历,这次案例选择的是订单系统里一个足够真实的需求——管理员对已支付订单发起部分退款。它牵扯状态机、金额精度、幂等、并发和审计日志,小到一个人一天能做完,又复杂到足以暴露"直接让AI生成"会踩的所有坑。

一、一句话需求为什么换不来一次合并

(一)能编译、能演示、能合并是三件事

评价一段AI生成的代码,存在三个从低到高的门槛。第一个门槛是能编译:类型对得上、依赖找得到、构建不报错。当前主流编码智能体跨过这个门槛的成功率已经相当高,因为编译器是最便宜也最严格的验证器,模型可以拿着报错信息自己迭代。第二个门槛是能演示:正常路径跑得通,接口调用返回预期结果。这一层多数时候也能达到,因为正常路径恰恰是需求描述里写得最清楚的部分。

真正的分水岭是第三个门槛:能合并。能合并意味着代码尊重项目既有的架构分层、复用了已经存在的基础设施、没有绕过团队的业务约束、覆盖了异常与并发路径的测试、并且差异范围干净到评审者愿意为它签字。这三个门槛考察的是完全不同的东西——前两个考察模型的生成能力,第三个考察的是整个开发过程有没有被组织好。一句话需求之所以换不来一次合并,是因为它只为第一、二个门槛提供了信息,第三个门槛需要的信息全部缺席。

(二)失控的四种典型现场

把"给订单系统加一个部分退款功能"直接丢给编码智能体,常见的失控现场有四种,每一种都对应一类缺失的过程控制。

第一种是平行发明。项目里已经有统一的异常体系、审计日志组件和支付渠道客户端,AI没有找到它们,于是自己发明了一套:新的异常基类、手写的日志表插入、重新封装的HTTP调用。代码本身没有错,但它是一座孤岛,评审者要么全部推翻,要么接受项目里从此有两套做法。这对应的缺失是分析阶段——没有人要求AI先读懂项目再动手。

第二种是边界扩张。任务是加退款,diff里却出现了对既有支付方法的"顺手重构"、对公共DTO的字段调整、以及一批与需求无关的格式化改动。每一处单看都说得过去,合在一起让评审无从下手。这对应的缺失是计划阶段——没有一份事先圈定"允许修改哪些文件"的清单。

第三种是快乐路径工程。生成的代码在演示时完美工作,但没有回答这些问题:同一笔退款请求重放两次会不会退两次钱?两个管理员同时操作同一订单会发生什么?退款金额恰好等于剩余可退金额时状态该落在哪里?金额用了double会不会在第七位小数上亏一分钱?这对应的缺失是测试阶段——没有人把异常与并发场景变成必须通过的用例。

第四种是无人审计的合并。测试全绿之后直接提交,三周后才发现AI在实现里悄悄放宽了一个状态校验,或者把带着敏感信息的入参原样打进了日志。这对应的缺失是差异审查阶段——绿色的测试只能证明"测过的行为是对的",不能证明"没测过的改动是无害的"。

(三)五段闭环:把生成关进流程里

四种失控现场对应的解法,合起来就是本文的主线:把一个功能的交付拆成五段,每段有明确的输入、输出和验收标准,段与段之间设置人工确认点。

第一段是分析代码:AI只读不写,交付物是文件清单、调用链、可复用组件和待确认的业务问题。第二段是制定计划:AI基于分析产出一份文件级的实施方案,人来审计范围、依赖和测试设计,确认后落盘为需求文件。第三段是实现功能:AI在计划圈定的边界内修改代码,硬约束写在提示词里。第四段是运行测试:先跑定向用例快速反馈,再跑全量构建防回归,失败进入有限次数的修复回路。第五段是审查差异:人(以及一个只读的第二视角)逐行看diff,确认改动与计划一致后才允许提交。

这个结构不是为了仪式感。它的每一段都在回答同一个工程问题:这一步的产出,用什么办法验证?分析的产出用人的项目知识验证,计划的产出用业务规则验证,实现的产出用编译器和测试验证,最终的差异用人的评审验证。验证手段齐备的环节可以放心交给AI迭代,验证手段缺失的环节必须由人把守——这一条原则会贯穿全文,并在第八章展开成一个可操作的判断框架。

二、开工之前:给AI一个有边界的工作台

(一)示例功能与验收标准

先把贯穿全文的需求钉死。业务方的原始诉求是一句话:"客服处理售后时,管理员要能给已支付的订单退一部分钱。"在进入任何工具之前,第一件事是人来把这句话翻译成可验证的验收标准:

  • 仅PAID(已支付)与PARTIALLY_REFUNDED(已部分退款)状态的订单允许发起退款;
  • 单笔退款金额必须大于零,且累计退款总额不得超过订单实付金额;
  • 退款后若累计退款等于实付金额,订单状态迁移为REFUNDED(已全额退款),否则迁移为PARTIALLY_REFUNDED;
  • 调用方必须携带全局唯一的请求号requestId,同一请求号重复提交按幂等处理,返回首次受理结果,不重复打款;
  • 两个并发请求操作同一订单时,最多只有一个成功,另一个必须得到明确的冲突错误而不是静默覆盖;
  • 每次退款记录操作人、退款原因、金额与时间,写入既有审计日志体系;
  • 金额一律使用BigDecimal,保留两位小数;
  • 不修改既有表结构,退款流水使用项目中已存在的refund_record表(该表对request_id建有唯一索引)。

这份清单是整个流程的锚点。后面每一段的提示词都会引用它,最后的差异审查也拿它当对照表。值得强调的是,这一步没有任何AI参与——哪些状态可退、超额怎么处理、幂等语义是什么,这些是业务决策,AI最多能帮你发现"这里有一个没定义的边界",不能替你定义它。

(二)隔离的工作区:分支与工作树

AI修改代码之前,先给它一个可以整体丢弃的空间。最低要求是一个独立分支:

git checkout -b feature/order-partial-refund

分支是安全边界。它保证无论这次实验产出什么,都可以用一次git branch -D干净地回退,主干不会沾染任何未经验证的改动。如果你需要在同一台机器上并行处理多个任务——比如一边让AI做退款功能,一边自己修一个线上问题——git的工作树机制可以为每个任务提供物理隔离的目录:

git worktree add ../order-refund-wt feature/order-partial-refund

两个检出各自独立,文件互不干扰,从根上消除了"两个会话改了同一个文件"的冲突。主流编码智能体已经把这一步产品化,例如Claude Code的--worktree参数会自动创建并管理工作树,多智能体框架则默认为每个任务分配隔离工作区。手段可以不同,原则只有一条:AI的每一次实验都应该发生在可以整体作废的空间里。

(三)写进仓库的规则:记忆文件与命令清单

复杂项目里有大量"每次都要交代"的背景:构建命令、架构分层、编码红线、禁止触碰的区域。与其每个会话重新解释,不如写成一份仓库内的记忆文件(按工具约定命名为CLAUDE.md、AGENTS.md或规则文件),让智能体每次启动自动加载:

# 项目速览
Spring Boot 3 订单服务,Java 21,MyBatis + MySQL,JUnit 5 + Mockito。

## 构建与测试
- 定向测试:mvn -Dtest=OrderRefundServiceTest test
- 全量校验:mvn clean verify

## 架构边界
- Controller 只做参数校验与编排,业务规则在 service 层
- 订单状态变更必须走条件更新(校验旧状态)
- 金额一律 BigDecimal,禁止 float/double
- 审计日志统一走 OrderAuditLogRepository,禁止自建日志表

## 修改纪律
- 未经确认不改表结构、不加第三方依赖、不动公共异常格式
- 不自动执行 git commit / push
- 不做与任务无关的格式化与"顺手重构"

这份文件的写法有讲究:放进去的应该是长期稳定的规则与命令,而不是某一个需求的临时说明——临时性的内容属于第四章要讲的需求文件,两者混在一起会让规则文件迅速膨胀失效。一个有效的检验标准是:文件里的每一条,是否在任何任务中都成立?成立的留下,不成立的挪走。

三、第一段:分析代码——只读优先

(一)分析提示词:明确要什么、禁止什么

工作台就绪后,第一条指令不是"实现退款",而是"读懂项目"。给分析阶段的提示词要同时做到两点:列出必须回答的问题,明确禁止修改任何文件。

请分析当前订单服务项目,本阶段禁止修改任何文件。

需要确认:
1. 订单状态枚举的定义位置与现有状态迁移规则;
2. 支付成功后的实付金额存储在哪个字段,精度如何处理;
3. refund_record 表对应的实体、Mapper 与现有读写位置;
4. 支付渠道退款接口的客户端封装及其幂等语义;
5. 审计日志的统一写入方式与既有事件类型;
6. 管理端接口的权限校验是如何组织的;
7. 项目中是否已存在部分退款、取消或逆向流程的类似实现;
8. 与订单状态和退款相关的现有测试及其运行方式。

输出:相关文件清单(含路径)、主要调用链、可直接复用的组件、
需要人工决策的业务问题。暂时不要给出任何代码修改建议。

"禁止修改"不只是嘴上说说。多数编码工具提供了机制级的只读保障:Claude Code的计划模式(plan mode)下模型可以读文件、搜代码,但任何写操作都会被拦截,直到人批准方案;其他工具也有类似的只读会话或权限模式。用机制保证只读,比在提示词里恳求"请不要改代码"可靠得多——这也是一个通用原则:能用权限约束的事情,不要依赖模型的自觉。

另一个实用技巧是委托检索。分析大项目会产生海量的文件读取,这些内容会挤占主会话的上下文窗口。支持子智能体(subagent)的工具可以把"翻文件"外包出去:子智能体在自己的上下文里读几十个文件,只把结论带回主会话。主会话保持干净,后续计划与实现阶段的质量都会受益。

(二)四样交付物:清单、链路、复用点、疑问

分析阶段合格的产出是四样东西,缺一样都不该进入下一段。

第一样是文件清单:与本次需求相关的实体、服务、Mapper、配置和测试的具体路径。它是后面圈定修改边界的原材料。第二样是调用链:从管理端接口到订单落库、从支付回调到状态迁移的完整路径,让人能判断新功能应该挂接在哪一层。第三样是可复用组件:这个项目里已经有的东西——统一异常体系、条件更新的Mapper方法、审计日志仓储、支付渠道客户端。这份清单直接决定AI会不会平行发明。第四样是待确认问题,这往往是最有价值的部分。一次合格的分析应该能提出这样的问题:"refund_record表有status字段,取值PENDING/SUCCEEDED/FAILED,退款是同步成功还是要等渠道回调?累计已退金额应该统计SUCCEEDED还是包含PENDING?"——这个问题直接影响超额校验的口径,答案只能由人给出。

(三)怎么判断AI真的读懂了

分析报告本身也需要验证,验证者是人的项目知识。有效的办法是抽查你已经知道答案的问题:项目里明明有一个定时任务在扫描超时订单,报告有没有提到它?支付客户端的重试逻辑写在拦截器里,报告有没有定位到?如果AI遗漏了你知道的关键事实,说明它对项目的理解存在盲区,此时进入实现阶段的风险极高——它大概率会在盲区里平行发明。正确的动作是补充提示("请再看一下scheduler包下的超时处理"),让它修正报告,直到分析质量过关。这一段多花十分钟,后面能省一小时。

(四)分析报告也要落盘

和后面的计划一样,确认过的分析报告值得保存为仓库内的文件,例如docs/analysis/order-refund-context.md。它有两个后续用途:一是实现阶段开新会话时,把它和需求文件一起作为起点,新会话不必重新读一遍项目;二是三个月后另一个人(或另一个智能体)接手逆向流程相关的需求时,这份"退款上下文地图"可以直接复用。分析是全流程里最贵的智力投入之一,让它以文件形式沉淀下来,而不是随会话结束蒸发,是这套流程从"一次跑通"走向"长期可用"的关键一环。

四、第二段:制定计划——把方案钉进文件

(一)计划模式的机制价值

分析确认后,让AI输出实施计划,此时依然不允许它改代码。很多工具把这一步做成了显式的工作模式:模型给出完整方案,人批准后才解锁写权限。这个"批准闸门"的价值在于它把决策时刻前置了——在计划阶段否决一个方案的成本是几句话,在实现之后否决它的成本是几百行diff和已经花掉的时间。经济学上这叫把昂贵的分歧放到便宜的时刻去解决。

(二)一份可执行计划长什么样

给计划阶段的提示词要把验收标准完整带上,并规定输出结构:

基于前面的分析,为"管理员部分退款"生成实施计划,暂不修改代码。
业务约束:(此处粘贴第二章的八条验收标准)

输出格式:
- 需求理解(用你的话复述,暴露理解偏差)
- 拟修改/新增的文件清单,每个文件的具体改动内容
- 事务边界与失败回滚策略
- 并发与幂等的处理方案
- 计划新增的测试用例列表(含异常与并发场景)
- 明确不做的事情(Out of Scope)
- 仍不确定、需要人拍板的问题

一份合格的计划应该具体到文件级,看起来像这样:

1. OrderRefundController.java(新增)
   - POST /admin/orders/{id}/refunds,接收金额、原因、requestId
   - 复用 AdminAuthInterceptor 既有权限校验
2. OrderRefundService.java(新增)
   - 幂等检查 → 状态校验 → 超额校验 → 落流水 → 条件更新状态
     → 调渠道退款 → 写审计日志,整体一个事务
3. OrderMapper.java(修改)
   - 增加 updateStatusIfMatch(orderId, fromStatus, toStatus)
4. RefundRecordMapper.java(修改)
   - 增加 findByRequestId 与 sumSucceededAmount
5. OrderRefundServiceTest.java(新增)
   - 正常部分退款 / 恰好退完转 REFUNDED / 超额拒绝 /
     幂等重放 / 非法状态拒绝 / 并发条件更新失败 / 金额精度
不做:退款审批流、批量退款、渠道回调对账(另立需求)
待定:渠道退款失败时,流水表状态标 FAILED 后是否自动重试?

计划的七个要素里最容易被忽略的是"明确不做的事情"。范围蔓延多数不是从大改动开始的,而是从"顺手把审批流也加了"开始的。把Out of Scope写进计划,等于给了后续差异审查一把量尺。

(三)人工审计计划的三个焦点

计划到手,人的审计聚焦三件事。

1、隐藏范围

逐条检查文件清单:有没有计划之外的公共API改动?有没有新增第三方依赖?有没有触碰表结构?特别警惕"为了实现A顺便调整了B"式的措辞——那通常是范围扩张的起点。本例中,如果计划提出"给Order实体加一个refundedAmount冗余字段以免每次求和",就触碰了"不改表结构"的红线,必须打回:累计金额从refund_record表实时求和,性能问题留给未来有数据支撑时再议。

2、测试设计是否证明行为

看计划里的测试列表是不是在证明验收标准,而不是在"锻炼刚写的函数"。一个危险信号是测试用例与实现结构一一对应(每个私有方法一个测试),却没有覆盖"同一请求号重放不重复打款"这种行为级承诺。测试应该锚定在需求上,实现怎么重构都不该动摇它们。

3、业务规则谁来定

计划里的"待定问题"必须逐条给出人的答案,不能让AI用默认值蒙混过去。本例拍板:渠道退款同步返回受理结果,受理即标SUCCEEDED(简化模型,回调对账另立需求);累计已退金额只统计SUCCEEDED。这些决定连同计划一起落盘。

(四)计划落盘:从聊天记录到需求文件

确认后的计划不能只活在聊天窗口里——换一个会话、换一个工具、换一个人,上下文就丢了。把它保存为仓库内的需求文件:

docs/requirements/order-partial-refund.md

这份文件从此成为唯一事实源:实现阶段的提示词引用它,测试用例对照它,差异审查拿它当验收依据。它和第二章的规则文件分工明确——规则文件管"这个项目永远如此",需求文件管"这个任务具体如此"。

五、第三段:实现功能——在边界内执行

(一)实现提示词的硬约束

现在才轮到写代码。给实现阶段的指令不是重复业务需求,而是指向需求文件并附上硬约束:

请根据 docs/requirements/order-partial-refund.md 实现部分退款功能。
只允许修改计划中列出的五个文件。

约束:
1. 保持既有架构分层与异常响应格式;
2. 金额一律 BigDecimal,scale=2,舍入 RoundingMode.HALF_UP;
3. 状态更新必须使用条件更新,禁止 read-modify-write 直接 save;
4. 幂等依赖 request_id 唯一索引,捕获重复键冲突按幂等成功处理;
5. 每完成一个文件运行 mvn -Dtest=OrderRefundServiceTest test;
6. 不自动提交 git;
7. 发现计划与现有代码冲突时,停下来说明,不要自行变通。

第七条值得单独说明。实现过程中AI一定会遇到计划没有预料的情况——某个方法签名和分析时不一致、某个组件其实不支持预想的用法。糟糕的智能体行为是"自行变通":悄悄绕开障碍,把变通埋进diff里。好的行为是抛出异常给人:停下、说明冲突、等待决策。这条约束就是在明确要求后者。

(二)核心代码:状态机、幂等、金额与并发

以下是本例核心服务的实现(完整可编译代码见交付包source/demo-code目录),四个设计点逐一说明。

@Service
@RequiredArgsConstructor
public class OrderRefundService {

    private static final int AMOUNT_SCALE = 2;

    private final OrderRepository orderRepository;
    private final RefundRecordRepository refundRecordRepository;
    private final PaymentGatewayClient paymentGatewayClient;
    private final OrderAuditLogRepository auditLogRepository;

    @Transactional
    public RefundResult applyRefund(RefundCommand command) {
        Optional<RefundRecord> existing =
                refundRecordRepository.findByRequestId(command.getRequestId());
        if (existing.isPresent()) {
            return RefundResult.replayed(existing.get());
        }

        Order order = orderRepository.findById(command.getOrderId())
                .orElseThrow(() -> new OrderNotFoundException(command.getOrderId()));
        if (!order.getStatus().refundable()) {
            throw new OrderStatusNotAllowedException(order.getId(), order.getStatus());
        }

        BigDecimal amount = command.getAmount()
                .setScale(AMOUNT_SCALE, RoundingMode.HALF_UP);
        if (amount.compareTo(BigDecimal.ZERO) <= 0) {
            throw new InvalidRefundAmountException(order.getId(), amount);
        }
        BigDecimal refunded = refundRecordRepository.sumSucceededAmount(order.getId());
        BigDecimal remaining = order.getPaidAmount().subtract(refunded);
        if (amount.compareTo(remaining) > 0) {
            throw new RefundAmountExceededException(order.getId(), amount, remaining);
        }

        RefundRecord record = RefundRecord.accepted(order.getId(),
                command.getRequestId(), amount, command.getOperatorId());
        try {
            refundRecordRepository.insert(record);
        } catch (DuplicateKeyException e) {
            RefundRecord winner = refundRecordRepository
                    .findByRequestId(command.getRequestId())
                    .orElseThrow(() -> new RefundStateInconsistentException(
                            command.getRequestId(), e));
            return RefundResult.replayed(winner);
        }

        OrderStatus target = amount.compareTo(remaining) == 0
                ? OrderStatus.REFUNDED : OrderStatus.PARTIALLY_REFUNDED;
        int updatedRows = orderRepository.updateStatusIfMatch(
                order.getId(), order.getStatus(), target);
        if (updatedRows != 1) {
            throw new ConcurrentOrderUpdateException(order.getId());
        }

        paymentGatewayClient.refund(
                order.getPayTradeNo(), command.getRequestId(), amount);
        auditLogRepository.save(OrderAuditLog.refund(order.getId(),
                command.getOperatorId(), command.getReason(),
                amount, LocalDateTime.now()));
        return RefundResult.accepted(record, target);
    }
}

1、幂等入口:请求号先行

方法第一步不是查订单,而是查请求号。重放的请求在这里直接返回首次结果,根本不进入业务逻辑。但仅有前置检查不够——两个携带相同requestId的请求可能同时通过检查,所以真正的防线是request_id上的唯一索引:后到者在insert时收到DuplicateKeyException,代码显式捕获它、回查首次记录、按幂等成功返回。注意这个catch块做了实事而不是吞掉异常,且回查失败时抛出携带原始异常的明确错误——静默的空catch在这里等于埋雷。

2、金额账本:BigDecimal与超额校验

金额进门先统一精度(setScale(2, HALF_UP)),再做两道校验:必须为正、不得超过剩余可退额度。剩余额度来自实付金额减去已成功退款的实时求和,而不是任何冗余字段——这正是计划审计时拍板的口径。所有比较使用compareTo而非equals,因为BigDecimal的equals会把1.0和1.00判为不等,这是AI生成金额代码时的高频陷阱,值得写进规则文件。

3、并发防线:条件更新

状态迁移使用条件更新而不是读改写:

UPDATE orders SET status = #{toStatus}, updated_at = CURRENT_TIMESTAMP
WHERE id = #{orderId} AND status = #{fromStatus};

受影响行数为1说明本请求赢得了状态迁移;为0说明订单状态在读取之后已被并发请求改变,此时抛出冲突异常,整个事务回滚,流水记录一并作废。两个并发退款最多一个成功,另一个得到明确的冲突响应——这正是验收标准要求的语义。

4、审计闭环:谁在什么时候退了多少

审计日志复用既有仓储,与主事务一起提交,记录操作人、原因、金额与时间。注意日志内容不包含用户手机号等敏感信息——差异审查阶段会专门检查这一条。

(三)实现期的纠偏:小步反馈而不是推倒重来

实现阶段人不需要盯着每一行生成,但需要在AI每完成一个文件、跑完一轮定向测试的节点上快速扫一眼。发现方向偏了,纠偏的方式是增量反馈("条件更新的fromStatus应该用读取时的状态,不是写死PAID"),而不是清空重来。上下文里已经积累的项目理解是有价值的资产,推倒重来等于把分析阶段的投入清零。只有当会话明显陷入自我缠绕——反复在两个错误方案之间横跳——才值得开新会话,并把需求文件作为新会话的起点。这也再次说明了把计划落盘的意义:会话可以作废,文件不会。

六、第四段:运行测试——让证据代替感觉

(一)两层运行:先定向、后全量

测试运行分两层,节奏完全不同。第一层是定向测试,只跑本需求的用例,秒级反馈,实现过程中高频执行:

mvn -Dtest=OrderRefundServiceTest test

第二层是全量校验,跑完整个模块的测试与构建,分钟级,在实现收尾时执行:

mvn clean verify

两层缺一不可。只跑定向测试,无法发现"退款改动弄坏了取消订单的旧用例"这类回归;只跑全量,反馈周期太长,AI的修复迭代效率会掉一个数量级。让智能体在迭代中用第一层、在宣布完成前必须通过第二层,是成本与置信度的最优组合。

还有一个容易被忽略的细节:要求AI在报告测试结果时给出原始证据,而不是一句"测试已通过"。具体来说,指令里写明"报告你执行的完整命令与输出摘要,包括用例总数、通过数、失败数与耗时"。这条要求防的是两类问题:一类是智能体根本没有运行测试却声称通过(在长会话末尾并不罕见);另一类是它运行了错误范围——比如只跑了一个用例却报告"全部通过"。原始输出里的用例计数是最难伪造的证据,Tests run: 8, Failures: 0和一句空泛的"测试通过",置信度完全不同。

(二)AI补测试的清单

让AI补测试时,指令同样锚定验收标准而不是实现结构。本例的用例清单:

  • 正常部分退款:状态迁移为PARTIALLY_REFUNDED,渠道被调用,审计日志落库;
  • 恰好退完:累计等于实付时状态迁移为REFUNDED;
  • 超额拒绝:申请金额大于剩余额度时抛出明确异常,渠道不被调用;
  • 幂等重放:相同requestId第二次提交返回首次结果,渠道只被调用一次;
  • 并发插入冲突:insert抛出重复键异常时回查并按幂等返回;
  • 非法状态:PENDING_PAYMENT、CLOSED状态的订单直接拒绝;
  • 并发状态变更:条件更新返回0行时抛出冲突异常且事务回滚;
  • 金额精度:传入10.005按HALF_UP落为10.01,0.00被拒绝。

其中幂等重放用例的结构值得展示,它验证的是行为承诺而非方法调用:

@Test
@DisplayName("申请退款-相同请求号重复提交-应返回首次结果且不重复调用渠道")
void applyRefund_whenRequestIdReplayed_shouldReturnFirstResultWithoutSecondGatewayCall() {
    // Arrange
    RefundCommand command = refundCommand("REQ-001", new BigDecimal("30.00"));
    given(refundRecordRepository.findByRequestId("REQ-001"))
            .willReturn(Optional.of(succeededRecord("REQ-001")));

    // Act
    RefundResult result = orderRefundService.applyRefund(command);

    // Assert
    assertThat(result.replayed()).isTrue();
    then(paymentGatewayClient).shouldHaveNoInteractions();
    then(orderRepository).shouldHaveNoMoreInteractions();
}

Mock的纪律要在指令里说清楚:仓储、渠道客户端、时间获取必须Mock(外部依赖),被测服务本身、RefundCommand这类纯数据对象、BigDecimal运算禁止Mock。AI在无约束时倾向于过度Mock,产出"验证了每个Mock被调用、却什么行为都没证明"的测试,这类测试全绿也毫无置信度。

(三)修复回路与叫停条件

测试失败后进入修复回路:AI读失败输出、定位原因、修改、重跑。这个回路必须限次。经验上限是同一个失败修三次:三次之内AI通常能收敛;超过三次还在失败,几乎总是意味着更深的问题——计划遗漏了某个前提,或者测试本身写错了预期。此时正确动作不是让AI继续磨,而是人介入判断:是回到计划阶段补充设计,还是修正测试的断言。

还有一条红线要在指令里写死:修复的对象是代码,不是测试。AI在压力下存在"把断言改宽让测试变绿"的倾向——比如把assertThat(updatedRows).isEqualTo(1)改成isGreaterThanOrEqualTo(0)。任何对测试文件的修改都必须在差异审查中单独过目,凡是放宽断言、删除用例、给测试加忽略注解的改动,一律视为高风险信号。

七、第五段:审查差异——最后一道人工闸门

(一)先看改了什么,再看改得对不对

测试全绿不是终点。提交之前,人要完整地看一遍差异——不是看最终文件的样子,而是看这次到底改了什么:

git diff --stat
git diff

先看--stat的文件清单:有没有计划之外的文件出现在列表里?改动行数与预期是否匹配(计划里说"新增两个方法",diff却有四百行,一定有问题)?再逐文件细读,对照一份固定的清单:

  • 是否修改了计划清单之外的文件;
  • 是否改变了公共方法签名或接口契约;
  • 是否删除或放宽了既有校验逻辑;
  • 事务注解与边界是否与计划一致,有没有把长耗时的渠道调用不当地圈进事务;
  • 是否引入了未经批准的依赖或配置变更;
  • 日志里是否出现手机号、卡号等敏感字段的明文;
  • 测试文件的改动是否只有新增,既有断言有没有被动过;
  • 是否混入与需求无关的格式化、重命名与"顺手重构"。

这份清单看起来朴素,但它拦下的问题类型恰恰是测试拦不住的:测试证明"写了的行为是对的",差异审查负责"没写测试的改动是无害的"。两者是互补关系,不可互相替代。

(二)第二视角:让另一个会话做只读复核

人工审查之外,可以再加一道机器复核——但必须换一个干净的会话,并且明确它的角色是只读审查者:

请审查当前分支相对 main 的 git diff,禁止修改任何文件。
对照 docs/requirements/order-partial-refund.md 检查:
1. 实现是否完整覆盖验收标准,有无遗漏的边界;
2. 幂等与并发防线是否存在绕过路径;
3. 事务边界是否合理,渠道调用失败时数据是否一致;
4. 是否存在需求范围之外的改动;
5. 测试是否真实证明了行为,有无放宽断言的痕迹。
输出:高风险问题 / 中风险问题 / 低风险建议 / 需人工确认的事项。

换会话不是形式主义。让实现者审查自己的产出,它会带着实现时的全部假设去看代码,盲区与实现时完全重合;一个没有历史包袱的新会话(更好的是另一个模型)会用新鲜的眼光重读需求与diff,这在多智能体工程里对应"创作者与审查者分离"的制衡模式。审查产出的高风险问题回到实现阶段修复,修复后重新过测试与diff——闭环在这里真正闭合。

(三)提交、PR与可追溯性

三道检查(测试、人工diff、机器复核)全部通过后才轮到提交。提交信息交给AI起草没有问题,但要求它如实概括改动并引用需求文件路径。推送后创建PR,描述里带上验收标准清单与测试证据(用例列表、运行结果),让评审者不必重新考古。

提交的粒度也值得设计。如果功能是分几个阶段实现的(先Mapper、再Service、再测试),按阶段分别提交比一个大提交更友好:每个提交都是一个可回退的检查点,评审可以按提交逐段看,出问题时git revert的爆炸半径也小。有的团队更进一步,要求AI在每个计划步骤完成并通过测试后就地提交,提交信息里标注对应的计划步骤编号——这样PR的提交历史本身就是计划执行的轨迹,审查者对照需求文件即可逐步核销。

到这里,一个功能才算真正走完"能合并"的全程——从一句话需求出发,中间经过八个有产出物的节点:验收标准、分析报告、实施计划、需求文件、实现diff、测试证据、审查报告、PR。每个节点都可追溯,这正是这套流程和"一把梭生成"的本质区别。

八、从一次跑通到长期可用

(一)验证成本决定委托边界

走完一遍全流程,可以回头提炼那条贯穿始终的原则了:一个环节能不能放心交给AI,取决于这个环节的产出有没有便宜、可靠的验证器。

编译是最便宜的验证器,所以类型层面的修改可以完全放手;单元测试是便宜且可靠的验证器,所以有测试覆盖的实现与重构可以大胆委托,让AI对着测试自己迭代;构建与静态检查同理。反过来,接口契约的合理性、安全边界的完备性、业务规则的正确性——这些没有廉价验证器,验证它们的唯一手段是人的判断,所以计划审计与差异审查必须由人把守。Java生态在这个框架下有天然优势:强类型、成熟的测试设施、严格的构建工具,让"可委托区"比动态语言生态大得多。这也解释了为什么同样的智能体,在有测试传统的Java项目里表现明显好于没有测试的遗留系统——差别不在模型,在验证器的密度。

(二)风险分级:不是所有环节都值得自动化

流程跑熟后,自然会想把它自动化——用钩子在提交前自动跑测试,用CI在PR上自动触发机器复核,用定时任务让AI巡检失败的构建。自动化的尺度可以用风险分级来标定:只读分析类操作(读代码、生成报告、审查diff)风险最低,可以完全自动;文档、测试补充类修改风险较低,合并前人工确认即可;涉及接口、权限、数据结构的修改,修改前与合并前都要人工确认;部署生产、删除数据、变更密钥这类不可逆操作,永远不该让AI自动执行。分级的意义在于让自动化有边界地扩张:每当你想再自动化一步,先问这一步失控的最坏后果是什么、能不能整体回退。

自动化的另一个方向是把五段闭环里的机器角色专门化。实践中已经成型的模式是:分析与审查用只读会话(甚至不同的模型),实现用主力编码智能体,测试运行交给不需要智能的脚本或轻量模型——用小模型跑测试、解析输出、回传"用例到通过与否"的映射表,成本只有主力模型的零头。角色专门化还有一个副产品:各角色的提示词可以沉淀为团队共享的模板(分析模板、计划模板、实现约束模板、复核模板),新成员照模板即可跑通流程,而不必先成为提示词专家。工程能力从个人经验变成团队资产,这正是流程化区别于技巧化的地方。

(三)常见失败模式与对策

最后把实践中高频出现的失败模式收拢成一张对照表,供流程落地时自查。

  • 跳过分析直接实现——AI平行发明既有组件;对策:只读分析先行,四样交付物齐了才放行。
  • 计划只活在聊天里——换会话即失忆;对策:确认后的计划落盘为需求文件,进版本控制。
  • 两个工具同时改代码——同一方法两套实现;对策:同一阶段只有一个修改者,其余角色只读。
  • 只跑新增测试——旧功能被静默弄坏;对策:宣布完成前必须通过全量构建。
  • AI改测试让它变绿——置信度归零;对策:测试文件的diff单独审,放宽断言一票否决。
  • 修复回路无限转——时间黑洞;对策:同一失败限修三次,超限人工介入。
  • 测试绿了直接提交——未测行为的改动无人审计;对策:人工diff清单加只读机器复核。
  • 规则每次重新交代——质量随会话波动;对策:稳定规则进记忆文件,随仓库演进。

(四)给团队的落地清单

把这套流程引入团队,不需要一步到位。可操作的起步路径是:第一周,为仓库补一份记忆文件(构建命令、架构边界、修改纪律三节即可),并规定所有AI任务必须在独立分支进行;第二周,在中等规模的需求上强制"分析—计划—确认"三步,体会计划审计拦下问题的时刻;第三周,把差异审查清单贴进PR模板,把"测试证据"设为PR必填项;一个月后,再考虑用钩子和CI固化两层测试与机器复核。选练手需求时避开支付、权限等核心链路,从文件范围清晰、已有测试基础的模块开始——这套流程的价值要在第一次"计划审计发现了隐藏范围"或"diff审查抓到了放宽的校验"时才会被真正相信。

九、结语

回到标题:写完了不等于能合并。AI把"写完"的成本压到了历史最低,于是工程的重心整体后移——移向写之前的分析与计划,移向写之后的测试与审查。本文用一个部分退款功能走完的五段闭环,本质上是把资深工程师面对陌生需求时的隐性素养显式化了:先读懂再动手,先设计再编码,先证明再相信,先审计再合并。这些素养过去靠年头养成,现在靠流程保障——因为执行环节交给了一个速度极快、但对项目没有记忆、对后果不负责任的合作者。

流程不是对AI的不信任,而是对验证的信任。当每一段都有明确的产出物和验证手段时,你会发现自己敢把越来越大的任务交出去——不是因为模型变得更可靠了,而是因为你的流程让不可靠变得可发现、可回退、可负担。这才是"用AI完成一个功能"的完整含义:完成的不只是功能,还有一条下次可以更快走一遍的路。

参考资料

转载自 CSDN-专业IT技术社区

原文链接:https://blog.csdn.net/xiaofeng10330111/article/details/166735604

文章来源转载

评论

评论列表

微信小程序
QQ小程序

关于作者

点赞数:0
关注数:0
粉丝:0
文章:0
关注标签:0
加入于:--