第五章：验收体系——质量门禁设计
2026.07.26代码能跑通，不代表它是安全的。能正常工作，不代表它没有埋下隐患。
你的项目上线运行了三个月，一切正常。
直到有一天，一个用户发现了一个"小问题"：他在搜索框输入了一个特殊字符，页面崩溃了。你查了日志，发现是 AI 在生成代码时，没有对用户输入做转义处理。
你开始担心：这会不会只是一个孤立的疏忽？你检查了更多代码。结果让你后背发凉——AI 写的 API 没有做请求频率限制、数据库查询没有用参数化处理、用户上传的文件类型没有校验、错误信息直接暴露了数据库连接字符串。
这些代码全都"能跑通"。它们工作正常——直到某个边界条件触发了隐藏的漏洞。
你不是不小心。你是没有建立验收体系。
5.1 为什么需要独立的验收
在传统的 AI 编码实践中，"验收"往往只是开发者看一眼代码，觉得"差不多"就通过了。
但问题在于：AI 生成的代码从语法上看几乎总是正确的，真正的问题藏在逻辑和架构层面。 一眼看不出来，跑一下也可能正常——直到某个边界条件触发 bug。
这就是为什么需要一套独立的、结构化的验收体系。
5.2 三条防线的设计逻辑
验收体系的核心是"三条防线"的设计。为什么是三条？因为 AI 编码的错误有三个层次，你需要三个层次的检测方法。
第一层：功能防线——检测"代码是否跑通了"
这是最直观的检查。代码能不能跑通？功能对不对？你写测试用例，跑测试，看结果。如果你让 AI 实现"用户注册"，它写了代码，你跑测试——注册成功，密码存入了数据库，登录成功。功能防线通过。
但功能防线有一个盲区：它只检查"代码是否按预期运行"，不检查"代码是否按正确的方式运行"。你的注册功能跑通了，但密码是明文存储的——功能测试发现不了这个问题。因为功能测试的输入是"用户名+密码"，输出是"注册成功"，测试用例不会去检查数据库里存的是什么。
第二层：架构防线——检测"代码是否遵守了蓝图"
这是 AI 编码中特有的防线。AI 很容易在实现功能时"顺手"改了不该改的东西——比如为了修复一个 Bug，它直接修改了数据库表结构。功能测试看不出来，因为功能还是对的，但架构已经偏移了。
架构防线的检查方法很简单：对比蓝图文件（CONTEXT.md）和实际代码。蓝图规定"密码必须用 bcrypt 加密"，架构防线就检查实际代码中是否调用了 bcrypt。蓝图规定"错误必须抛统一 AppException"，架构防线就检查实际代码中是否用了 AppException。
第三层：安全防线——检测"代码有没有引入安全隐患"
这是最容易被忽视的防线。AI 生成的代码往往"功能正确但安全脆弱"。原因很直接：AI 的训练数据中包含了大量"能用但不安全"的代码。它学会了"写功能"，但没学会"写安全的代码"。
来看一个三层防线如何协作的例子。假设同一个 Bug——登录接口在密码错误时返回 500 错误：
- 功能防线看到的是：返回状态码错误，需要修
- 架构防线看到的是：错误处理逻辑不在统一的异常处理层，需要重构
- 安全防线看到的是：错误信息直接暴露了数据库连接信息，需要修复
同一个 Bug，三层防线看到的是三个不同层面的问题。只修了第一层，第二层和第三层的问题依然存在。这就是为什么需要三层防线——每一层覆盖上一层覆盖不到的盲区。
新手验收通常只关注第一层。有经验的开发者三层都检查。
5.3 如何设计验收标准
验收标准不是测试用例。测试用例验证"代码是否按预期运行"，验收标准验证"代码是否按约束完成"。两者有本质区别。
一个设计良好的验收标准应该包含三类检查：
第一类：功能检查——核心流程是否跑通？边界条件是否处理？错误路径是否覆盖？这些是测试用例可以覆盖的。
第二类：约束检查——是否遵守了技术栈约定？是否遵守了命名规范？是否遵守了架构原则？这些是蓝图中的"硬约束"，AI 容易在不经意间违反。
第三类：质量检查——代码行数是否在合理范围？是否有重复代码？是否有不安全的 API 调用？这些是"软约束"，没有明确的通过/不通过，但需要人工判断。
来看一个"好验收标准"和"差验收标准"的对比：
差的验收标准（太模糊，无法判断是否完成）：
"登录功能完成。"
好的验收标准（精确，可量化，可验证）：
"登录功能完成，验收标准：
- 密码用 bcrypt 比对
- JWT 包含 user_id，有效期 2 小时
- 错误返回统一格式的 401 AppError
- 连续 5 次失败锁定账号 30 分钟"
差的验收标准说了等于没说。好的验收标准让 AI 和开发者都能精确判断"是否完成"。
5.4 验收清单
以下是一份完整的验收清单，你可以根据项目实际情况调整：
功能验收
- 所有需求点都已实现
- 主流程能正常运行
- 边界情况有处理（空数据、异常值、极限情况）
- UI 交互符合预期（加载状态、错误提示、空状态）
代码验收
- 代码风格与项目一致（缩进、命名、注释）
- 没有明显的代码质量问题（重复代码、过长函数、不合理命名）
- 没有死代码（未被调用的函数、未使用的变量）
- 错误处理合理（不吞异常、不暴露敏感信息）
架构验收
- 没有修改不应修改的核心代码
- 没有引入不必要的依赖或抽象
- 单个文件没有过度膨胀（建议上限 300 行）
- 新增代码与项目的目录结构一致
- API 设计遵循项目的约定
安全验收
- 用户输入经过验证或转义
- 敏感接口有权限控制
- 没有硬编码的密钥或凭证
- 数据库查询使用参数化查询或 ORM
- 不返回不应暴露的数据字段
5.5 验收报告
验收完成后，应该输出结构化的验收报告。以下是报告模板：
## 验收报告：里程碑 X
### 结论：PASS / NEEDS_FIX / REBUILD
### 功能验收
- [x] 需求全部实现
- [x] 主流程正常
- [ ] 边界情况：未处理搜索关键词为空的情况
### 代码验收
- [x] 代码风格一致
- [x] 无重复代码
- [x] 错误处理合理
### 架构验收
- [x] 未篡改核心代码
- [x] 未引入不必要的依赖
- [x] 目录结构合规
### 安全验收
- [x] 输入验证完整
- [x] 权限控制到位
- [x] 无硬编码凭证
### 修复建议（仅 NEEDS_FIX 时）
1. 在搜索函数中添加空字符串判断
2. 当搜索关键词为空时，返回完整列表
5.6 验收中的架构偏移检测
架构偏移是 AI 编码中最隐蔽也最具破坏性的问题。AI 在实现一个功能时，可能会"顺手"修改了不该改的地方。
三大信号详解
信号一：篡改地基
AI 修改了以下类型的代码，应该立即 REBUILD：
- 数据库连接配置
- 认证和授权逻辑
- 全局中间件
- 核心工具函数
- 共享的数据模型定义
为什么会发生： AI 发现当前功能的实现"需要"修改地基代码。但通常这不是真的需要，而是 AI 走了捷径。
信号二：过度设计
AI 引入了以下不必要的复杂性：
- 为简单场景添加了抽象层（接口、工厂、策略模式）
- 引入了项目不需要的第三方库
- 添加了当前功能不需要的配置选项
为什么会发生： AI 倾向于"以防万一"的设计，而不是"刚刚好"的设计。
信号三：体积失控
AI 在单个文件中堆积了过多代码：
- 一个组件文件超过 300 行
- 一个工具函数文件包含多个不相关的功能
- 一个 API 路由处理了多个不相关的请求
为什么会发生： AI 在"追加代码"时不会主动重构。它会直接在现有文件上添加新功能，导致文件膨胀。
检测方法
如何检测架构偏移？
1. 用 git diff 查看变更文件列表
意外出现的文件修改 → 可能是篡改地基
2. 检查新增文件的长度
新文件超过 300 行 → 可能是体积失控
3. 检查新增的依赖
package.json 中出现了未预期的依赖 → 可能是过度设计
4. 对比蓝图的目录结构
代码放在了蓝图未约定的位置 → 可能是架构偏移
5.7 验收中的安全审查
安全审查不是可选项。AI 生成的代码存在一些常见的"安全盲区"。
常见安全问题
信息泄露：API 返回了数据库中的敏感字段（密码哈希、内部 ID）
// ❌ 不安全：返回了整个 user 对象 return Response.json(user) // ✅ 安全：只返回需要的字段 return Response.json({ id: user.id, name: user.name })权限缺失：敏感接口没有权限检查
// ❌ 不安全：任何人都能删除用户 DELETE /api/users/:id // ✅ 安全：只有管理员能删除用户 DELETE /api/users/:id // 需要 admin 角色输入验证不足：用户输入直接用于数据库查询或页面渲染
// ❌ 不安全：直接拼接用户输入 db.query(`SELECT * FROM users WHERE name = '${input}'`) // ✅ 安全：使用参数化查询 db.query('SELECT * FROM users WHERE name = ?', [input])
安全验收方法
一个有效的做法是让 AI 做安全自检：
请对以下代码进行安全审查，检查：
1. 是否存在 SQL 注入风险
2. 是否存在 XSS 风险
3. 权限检查是否完整
4. 是否暴露了不应暴露的数据
5. 是否有硬编码的密钥或凭证
5.8 验收的自动化
对于成熟的项目，验收可以部分自动化：
- 单元测试：自动运行，确保核心逻辑正确
- Lint 检查：自动检查代码风格和常见问题
- 类型检查：TypeScript 项目自动检查类型
- 安全扫描：自动扫描已知的安全漏洞
但自动化不能替代人工验收。自动化检查只能发现"代码层面的问题"，无法发现"设计层面的问题"——后者需要人基于蓝图的判断。
本章小结
验收体系是 AI 编码中不可省略的环节。三条防线——功能、架构、安全——覆盖了 AI 编码的三个错误层次，每层覆盖上一层覆盖不到的盲区。验收标准的核心是"可验证"：精确到让 AI 和开发者都能判断"是否完成"。架构偏移的三大信号（篡改地基、过度设计、体积失控）是验收中最需要警惕的问题。记住：代码能跑通不等于它是对的，能正常工作不等于它没有隐患。下一章，我们将学习项目编排——当项目有多个功能时，如何管理它们的开发顺序和质量门禁。