
> AI 编程工程化实践系列 · 卷四 · 实战 | 第 7 篇 / 共 8 篇
>
> 这个系列只讲一件事：怎么用工程化的方法，把 AI 编程从"碰运气"变成"可预期"。

![image.png](https://developer.qcloudimg.com/http-save/yehe-12408676/3c00fd88162361457ff72fd159ef6a7d.png)

---

## 一、为什么是这两个场景

六步工作流在简单场景下不难理解：加个接口，拆需求、扫代码、出方案、写代码、跑验证、归档，两小时走完。

真正的考验在两个地方：**改动面特别广**，或者**改动跨越服务边界**。这两种场景下，凭感觉写一定翻车，而六步工作流的价值也正是从这里开始显现。

下面两个场景，一个广度大、一个跨度大。前面五篇讲的所有原则，会在里面一一出场。

## 二、场景一：批量修改，核心挑战是"改不全"

**需求**：所有 Controller 方法统一加权限校验注解。

改动深度很浅，就是加一行注解。广度很大：几十个文件、横跨多个模块。

**这类需求的核心挑战不是改不对，是改不全。**

AI 改对了 90% 的文件，漏了 10%。代码编译得过，测试跑得过，你根本不知道漏了哪几个。等上线后某个接口被越权调用，你才倒查回来，而那时候你连"还有多少个漏网的"都说不清。

### ① 拆需求：简单的需求也要追问

"所有 Controller 加权限注解"这句话，看着没什么可拆的。但 decompose-prd 会把它拆出四个必须回答的问题：

1. **哪些 Controller 要加？** 所有模块，还是排除某些（比如内部回调接口、健康检查端点）？
2. **注解的 value 值怎么确定？** 手动映射，还是按路径自动推断？
3. **已有的注解要不要动？** 有些方法可能已经加了别的权限注解。
4. **加错了能不能快速回滚？** 这决定了后面要不要分批提交。

四个问题不回答，AI 就会自己定：全部加上、按路径猜、覆盖已有注解、一次改完。四个默认选择，每一个都可能不是你要的。

### ② 探代码：两条命令锁定影响面

批量修改里，这一步的价值最高。**不写代码，先算清楚要改多少个地方。**

```bash
# 统计受影响的方法总数
grep -r "@GetMapping\|@PostMapping\|@PutMapping\|@DeleteMapping" \
  --include="*.java" src/main/java/ | wc -l

# 列出所有需要改动的文件路径
grep -rl "@GetMapping\|@PostMapping\|@PutMapping\|@DeleteMapping" \
  --include="*.java" src/main/java/
```

第一条给你一个总数，第二条给你一份清单。这两个数字后面要反复用到：改之前的总数、改之后的数量、改完的批次数，三者必须对齐。

> **原则**：30 个以上的批量改动，必须分批。算不出精确数量，就没法定分批策略。

### ③ 出方案：修改模板 + 不可触碰区域

批量修改的方案很薄，但有两样东西必须有。

**一是修改模板**，精确到代码级别：

```
修改前：
  @GetMapping("/items/{id}")
  public ApiResponse<ItemDTO> getItem(@PathVariable Long id) { ... }

修改后：
  @RequirePermission(value = PermissionEnum.ITEM_VIEW)
  @GetMapping("/items/{id}")
  public ApiResponse<ItemDTO> getItem(@PathVariable Long id) { ... }
```

有模板，AI 每批的改法是一致的。没模板，它会自己发挥，第一批加在注解上方，第二批加在方法里，第三批顺手改了缩进。

**二是不可触碰区域**，明确写出来：

- 不改动已有注解（`@RequestMapping`、`@Valid` 保持原样）
- 不改动方法签名和参数列表
- 不修改 utils/ 和测试代码

这一条在批量修改里尤其要紧。AI 的想象力比你丰富，你不说不许碰什么，它可能顺手帮你把隔壁模块"优化"了。第 4 篇讲过：不许碰什么，比要做什么更管用。

### ④ 写代码：每批 5 个文件

**每批 5 个文件，改完一批验证一批，通过后再改下一批。**

```
第 0 步（在任何修改之前）：mvn test → 记录基线
第一批（5 个文件）：修改 → mvn compile → mvn test → 对比基线 → git commit
第二批（5 个文件）：修改 → mvn compile → mvn test → 对比基线 → git commit
...
最后一批完成：全量回归 → mvn test → 对比基线 → 合并
```

**为什么不一次改完再跑测试？**

一次改 30 个文件，CI 挂了，你不知道是第几个文件的第几行改坏的。你只能逐个文件排查，或者整体回滚。而整体回滚意味着前面 29 个文件的正确改动也一并丢掉。

分批之后，任何一批出问题都能立刻定位到具体文件，回滚成本是 5 个文件，不是 30 个。

批量大小取 5 是个经验值：太少则批次过多、每批都要跑一遍全量测试，开销大；太多则定位成本上升。文件之间耦合度高的项目可以降到 3。

### ⑤ 验证：基线 + 覆盖度检查

除了常规的编译、测试、规范检查，批量修改要多做一步：**覆盖度核对**。

用探代码阶段同样的 grep，再跑一次，对比改动前后的数量：

```bash
# 改完之后再数一遍：有多少个方法已经带上了权限注解
grep -r "@RequirePermission" --include="*.java" src/main/java/ | wc -l
```

这个数字应该等于探代码阶段统计的总数。对不上，就说明有漏的，用 grep 反查哪些文件还没有：

```bash
# 列出有 Mapping 注解但没有权限注解的文件
for f in $(grep -rl "@GetMapping\|@PostMapping" --include="*.java" src/main/java/); do
  grep -q "@RequirePermission" "$f" || echo "未覆盖: $f"
done
```

这一步就是"改不全"这个核心挑战的直接解法。**AI 说改完了，你不信，用命令数一遍。** 数字对不上，剩下的就是漏网的。

### 数出来对不上，怎么办

覆盖度核对最常见的意外是：AI 说改完了，你数出来少几个。按三种情况处理：

1. **先核 grep 口径**。统计命令可能把不该改的也算进去了，比如测试代码里的 Mock 接口、抽象父类里的抽象方法。口径不对就改命令，别急着让 AI 补。
2. **真的漏了**。把漏掉的文件列出来，单独作为一批让 AI 补上，补完再数一遍。
3. **同一类文件反复漏**。如果漏的都属于某一类，比如都用了 `@RequestMapping` 而不是 `@GetMapping`，说明统计口径或规则里没有覆盖这一类。把它补进 rules/，下次同类任务自动覆盖。

第三种最值得留意。AI 反复漏同一类文件，多数时候不是它笨，是你的规范里压根没提过这类文件存在。补一条规则的收益，比补十个文件的收益大。

### ⑥ 归档

把这次发现的规则缺口写进 rules/。典型的一条：某些内部回调接口不该加权限注解。写进 `domain-spec.md`，下次同类任务 AI 自动跳过它们。

### 场景一的三条经验

1. **分批是必须的，不是可选的**。一次改完 30 个，CI 挂了等于没挂，你不知道错在哪。
2. **基线快照在批量修改里是生命线**。没有它，你分不清测试失败是历史债还是这次改出来的。
3. **"不可触碰区域"比"怎么改"更重要**。AI 不碰你不让碰的，比它改对你要它改的，更需要你先说清楚。

## 三、场景二：跨服务改动，核心挑战是"全局冲突"

**需求**：一次改动横跨三个服务。A 服务（数据层）新增一个批量更新接口，B 服务（编排层）调用它，C 服务（入口层）调用 B。

**核心挑战：AI 一次只能看到一个服务的代码，容易局部最优、全局冲突。**

典型翻车方式：A 服务的接口签名改了，B 服务还按旧签名调用。两个服务单独看都对，放一起就挂。而这种问题只有在联调时才暴露，排查成本极高。

![image.png](https://developer.qcloudimg.com/http-save/yehe-12408676/80e07135c2c567f3614ebf3ef3d3aa47.png)

### ① 拆需求：锁定调用链

跨服务改动在拆需求阶段就要把调用链和接口协议定下来：

- A 服务：新增 `POST /api/items/batch-update`，入参 `List<ItemUpdateDTO>`，出参 `BatchResult`
- B 服务：调用 A 的接口，需要超时重试加降级
- C 服务：调用 B 的接口，需要处理降级结果

**这三条写下来，就是后面所有工作的依据。** 没写清楚就开工，"我以为改完 A 就行了"这类误会必然发生。

### ② 探代码：画一张跨服务调用链图

三张俯视图覆盖了单个项目的结构，跨服务场景还差一张图：**跨服务调用链图**。它本质是架构图的局部放大，只画跟本次改动相关的那几个服务和调用方向。

画图花十分钟。它的作用是让所有人（包括 AI）在同一个上下文里：C 调 B，B 调 A，改动从 A 开始往上传。

**原则：动任何一行代码之前，先让这张图存在。**

### ③ 出方案：锁死契约，然后自底向上

这是跨服务改动最关键的一步。propose 阶段必须锁死 A 服务的接口签名，包括入参、出参、错误码、超时时间。一旦锁定，它就是 B 和 C 的"法律文书"。

执行顺序必须自底向上：

```
第一步：改 A 服务（底层）→ 锁死接口签名 → A 独立测试通过
第二步：改 B 服务（中间层）→ 基于 A 已锁定的签名写 FeignClient → B Mock A 测试通过
第三步：改 C 服务（入口层）→ 基于 B 已锁定的签名写调用 → C Mock B 测试通过
```

**为什么必须这个顺序？**

反过来想就清楚了：如果先改 B，你根本不知道 A 的接口最终长什么样，只能猜。等 A 实际写出来的接口跟你猜的不一样，B 的代码要重写。自底向上，每一层都基于已经确定的东西往上搭，不猜。

### ④ 写代码：一次只给一个服务的 prompt

**每次只给 AI 一个服务的上下文。**

三个服务的代码一起给，AI 会混淆：把 A 的 DTO 引用到 B 里，把 B 的错误码写到 C 的分支里。这种错误编译期未必能发现，因为类型可能对得上，只是语义错了。

正确做法是串行三次：

```
第一次：只给 A 的 prompt → 生成 → 验证 A → 通过
第二次：只给 B 的 prompt（附上 A 已锁定的接口签名）→ 生成 → 验证 B → 通过
第三次：只给 C 的 prompt（附上 B 已锁定的接口签名）→ 生成 → 验证 C → 通过
```

每次只带一个服务的代码，加上下游已锁定的契约文本。上下文干净，出错率降一个量级。

### ⑤ 验证：分层验证，最后全链路

```
第一层：A 服务单元测试（独立验证，不依赖 B 和 C）
第二层：B 服务集成测试（Mock A 的接口，只测 B 自己的逻辑）
第三层：C 服务集成测试（Mock B 的接口，只测 C 自己的逻辑）
第四层：全链路集成测试（三个服务真实调用 + 数据一致性校验）
```

**先保证每个服务独立正确，再做全链路验证。**

全链路挂了的时候，如果你已经确认过 A、B、C 各自独立正确，问题就只可能出在调用约定上：超时时间、序列化格式、错误码映射。排查范围从"三个服务所有代码"缩小到"三个接缝"。这个差别是几小时和十分钟的差别。

### ⑥ 归档

跨服务改动沉淀的规则往往最有价值：

- 超时时间必须 C > B > A（下游超时不能短于上游，否则上游还在等，下游已经放弃了）
- 降级结果必须标注"可能不一致"
- 跨服务调用的错误码要统一映射，不能直接透传下游错误码

这些规则写进 rules/，下次跨服务改动自动生效。

### 场景二的三条经验

1. **先锁契约，再动手写**。契约没锁死之前，不要动下游任何一行代码。
2. **自底向上，每层独立验证**。三个服务的 prompt 不要一起给 AI，上下文混淆会让它把不同服务的类引用搞混。
3. **跨服务调用链图是理解层的核心产出**。画图十分钟，省掉的排查时间可能是几小时。

## 四、两个场景的共同点

两个场景看起来差别很大，一个是几十个文件加一行注解，一个是三个服务改一条链路。但底层是同一套原则：

| 原则 | 批量修改里的体现 | 跨服务改动里的体现 |
|------|----------------|------------------|
| **先算影响面，再动手** | 两条 grep 算出精确数量 | 画调用链图锁定服务边界 |
| **分批，每批独立验证** | 每批 5 个文件，改完提交 | 每个服务一层，验证通过再上一层 |
| **明确不可触碰区域** | 不改动方法签名、不动测试代码 | 契约锁定后不许改签名 |
| **用命令核对，不信 AI 的自述** | 覆盖度 grep 反查漏网文件 | 分层测试逐层排除 |

四条里最后一条最容易被忽略。AI 说"改完了"，你信不信？在这两个场景里都不能信，得用命令数一遍、用测试跑一遍。这不是不信任 AI，是改动面大到人脑核对不过来的时候，只能让机器给答案。

## 五、可带走的三件事

1. **批量修改的敌人是"漏"**：两条 grep 算出总数，每批 5 个文件改完就提交，全部改完再用同样的 grep 数一遍，数字对不上就是漏了。
2. **跨服务的敌人是"猜"**：先锁死底层服务的接口签名，再自底向上逐层实现。契约没定就动下游，等于让 AI 猜，猜错了整层重写。
3. **两个场景都要"不可触碰区域"**：批量修改里是不许动方法签名和已有注解，跨服务里是契约锁定后不许改签名。先划红线，再让它动手。

## 下一篇预告

**第 8 篇：《从一个人到全团队：推广路径 + 9 个排查项》**

到这里，整套方法论讲完了：理解层、约束层、验证层、六步工作流、两个复杂场景。

最后一篇回到人的问题：团队里只有你一个人用，怎么办？同事不感兴趣怎么推？AI 不遵守规范、代码看着对却跑不通、维护成本太高，这三类高频问题怎么排查？以及一个判断标准：你该用哪些指标衡量这套东西到底有没有用。


这个系列只讲一件事：怎么用工程化的方法，把 AI 编程从"碰运气"变成"可预期"。

批量修改与跨服务改动：两个真实场景走一遍

六步工作流真正见真章的是两类改动：几十个文件一起改，跨三个服务改一条链。批量修改怕漏，先算总数、改完再数一遍；跨服务改动怕猜，锁死契约再自底向上。共同点一句话：AI 说改完了不算，得用命令数一遍。

编程语言

后端

开发工具

批量修改场景用两条grep命令算出精确影响面，每批5个文件改完即验证，最后用相同命令反查漏网文件；跨服务改动先锁死底层接口签名，再自底向上逐层实现，每层独立测试。两种场景都需明确"不可触碰区域"，用命令核对替代信任AI自述，确保改动完整性和契约稳定性。

数据一致性

单元测试

集成测试

代码解释

AI编程

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

批量修改与跨服务改动：两个真实场景走一遍-腾讯云开发者社区-腾讯云

批量修改与跨服务改动：两个真实场景走一遍

批量修改与跨服务改动：两个真实场景走一遍

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐