审查 AI 代码变更,也要检查依赖边界
文章指出,AI 生成的补丁即使通过测试,也可能引入跨层依赖或隐藏网络调用。建议比较基线与补丁的模块关系,列出新增依赖、越界情况及其理由,作为代码审查依据。
AI 深度解读
AI 编程代理给结账流程加了个功能,测试全绿,但它顺手让 apps/web 直接引用了数据库适配器。功能能上线,原先约定好的依赖方向却变了。等到要换存储实现,团队才发现 Web 层也得跟着改。
作者建议在 PR 里加一份架构差异报告(architecture diff),从代码里算出这次补丁新增或移除了哪些模块依赖,以及哪些变化越过了团队约定的边界。对经常审 AI 生成代码的前端和全栈开发者,这个办法能把藏在大段改动里的依赖变化,变成几条可以逐个核对的记录。
测试全绿,为什么还要看依赖方向
行为测试擅长回答「结账后有没有发出邮件」。只要测试覆盖的行为一致,无论邮件是在 HTTP 请求里直接发送,还是交给后台 worker 处理,两套实现都有可能通过。可对代码库来说,这两条路径的影响不同。前者把外部服务调用带进了请求路径,后者引入了异步处理,需要验证重试时会不会重复发送。
架构差异关注的是这次 PR 改了哪些依赖关系。在作者的 Web 应用示例里,web -> application -> domain 表示 Web 层通过应用层使用领域逻辑。-X-> 则表示禁止依赖,例如 web -X-> adapters/database。一旦报告指出某个控制器绕过应用层直连数据库,审查者就有了明确的入口,可以判断这条边是否必要,或者把操作移回应用层。
这类报告最适合跨包引用、新增队列或定时任务、增加 API 端点或 webhook、开辟数据库访问路径,以及调整职责或修改调用方很多的共享包。新增会随应用一起发布的运行时依赖,也值得看一眼。改个错别字或调整独立组件时,报告为空就够了。
规则由团队维护,变更从代码里算
架构图谱可以先从仓库里的一份小配置做起。作者用 apps/web/**、packages/application/** 等路径模式划分模块,再声明允许和禁止的依赖方向,并给 adapters 和 domain 分别标上 platform-team、core-team。小团队可以先保住两三个改起来最贵的边界,比如 UI 到数据层、领域层到基础设施层。历史违规单独登记,先拦新增,再逐步缩减存量。
CI 分别从目标分支的基准提交(base commit)和 PR 的最新提交(head commit)提取依赖图,把文件归入模块,再比较新增和移除的边。JavaScript 和 TypeScript 要解析 import,用正则扫文本容易把注释、字符串和真实依赖混在一起。Python 可以结合导入语句和包元数据。服务仓库如果依赖生成的客户端、主题订阅或路由注册,也可以把这些关系纳入检查。
下面这段 TypeScript 演示了 CI 如何用禁止规则检查上游已经提取并比对过的依赖边。
type Edge = { from: string; to: string; file: string };
const forbidden = new Set(["web->adapters", "domain->web"]);
for (const edge of changedEdges as Edge[]) {
const key = `${edge.from}->${edge.to}`;
if (forbidden.has(key)) {
console.error(`Forbidden architecture edge: ${key} (${edge.file})`);
process.exitCode = 1;
}
}
留心 console.error 这一行,它带上了 edge.file,审查者可以直接定位引入依赖的文件。实际接入时,上游还要先归一化路径别名。如果规则只管运行时依赖,就要排除没有运行时影响的类型导入。把提取逻辑和规则判断分开,以后补充框架分析能力时,PR 报告仍然可以沿用同一种格式。
哪些变化值得让 CI 拦下来
作者建议根据依赖的目标和方向定风险。新增一条绕过身份校验、支付或受保护存储的路径,只要规则能准确识别,就可以阻断合并。允许的依赖变化也可能值得审查。比如作者的示例中,CheckoutController.ts 和 sendReceipt.ts 都走应用层,依赖方向合规,但新增了异步副作用,所以报告把它标为中风险,并列出幂等测试、队列重试测试和 platform-team 的审批作为依据。人工提交也适用同一套规则。
这套流程可以提前用在给代理派活的时候。以结账后发回执为例,任务里可以写清楚 Web 和 worker 都能调用 packages/application,apps/web 不能导入 adapters/database,邮件要避开 HTTP 请求路径,公开支付契约保持原样。交付时带上应用命令的单元测试、验证重试安全性的 worker 测试,以及依赖变更报告。代理仍然可以决定模块内部怎么写。
报告有变化时,审查者要核对四件事:新增依赖是否为需求所必需,方向是否符合约定,新边界有没有行为测试,高风险变更是否经过目标模块负责人审查。确实需要例外时,把目标、负责人、原因和到期时间写清楚。涉及放宽规则的 PR,也应给规则本身安排独立的审查。
我的判断
作者把架构检查拆成了两个问题。架构测试检查仓库当前是否满足规则,架构差异帮审查者定位这次 PR 改了什么。对于历史包袱重的仓库,先报告增量,能让团队在清理旧问题的同时守住新增边界。如果仓库已经有成熟的依赖规则,直接把检查结果里的新增违规和对应文件显示在 PR 里,就能实现其中最有用的一部分。
原文给的是配置和流程示例,没有提供团队实测、对照数据或误报率。「先跑一两周再收紧」是上线经验,实际要看这段时间里跑过多少种 PR、规则是否已经稳定。想用它降低审查成本,前提是团队对受保护的边界有共识,模块也有人负责。否则报告每天都能产出,例外该不该批还是没人能定。
静态图的覆盖范围同样决定了报告能回答什么。反射、依赖注入、动态导入、生成代码、配置驱动的路由和远程调用,都可能漏掉。测试夹具或类型导入也可能误报。对于靠框架注册的入口,路由清单、集成测试和运行时追踪能补上部分证据。行为、安全、迁移和部署依然要用各自的检查来判断。
能拿来做什么
- 如果前端和 Node 服务共用一个仓库,先挑一条已经有共识的边界,例如禁止
apps/web直接引用数据库适配器。让 CI 从 base 和 head 生成依赖差异,先以 PR 检查摘要展示新增边和来源文件。 - 给代理派发涉及队列或外部调用的任务时,把允许经过的模块、必须避开的调用路径和验收测试一起写进去。例如让结账回执走应用层和 worker,再用测试覆盖幂等和重试。
- 先跑一到两周,检查误报并调整路径匹配规则,再让高置信度的关键违规阻断 CI。已有违规保留在基线里,确需放行的新例外记录具体目标和到期时间,每月复核。