AI 交付前的质量门禁：复杂度、分层、安全配置、测试，一个都不能少

AI 生成的代码"能跑"不等于"能上线"。

在 SDD-Agent 中，代码交付前必须通过一组质量门禁检查：方法复杂度、DDD 分层、实体字段注释、安全配置文件、测试覆盖。这篇文章讲清楚这些门禁怎么设计。

一、为什么 AI 生成的代码需要质量门禁

AI 生成的代码通常有以下几个隐患：

隐患	具体表现
方法太长太复杂	一个方法里塞了校验、查询、映射、持久化、通知，圈复杂度超过 30
分层混乱	Controller 直接调 Mapper，Service 里定义了内部 DTO 类
实体字段无注释	新增字段没有 Swagger 注解或 Javadoc，后续维护者不知道用途
AI 工具配置文件入库	.claude/、.codex/、.mcp.json 被提交到 Git，泄露秘钥
测试缺失	只测了 happy path，没测边界和并发

二、质量门禁清单

基础约束（所有变更必须通过）

☐ Service 层不定义内部结构类（Entity/DTO/VO/Request/Response）

☐ Entity 每个持久化字段有注释（Swagger/Javadoc/ORM 注解）

☐ 新增/修改方法有清晰描述（public API、复杂逻辑必须有）

☐ 方法圈复杂度 < 16

☐ AI 工具配置文件（.claude/ .codex/ .cursor/ .mcp.json）已在 .gitignore 中

架构约束（涉及 Service/Controller/DB/Redis 变更时必须通过）

☐ Controller 禁止直接引用 DTO/Param/VO（应通过领域模型交互）

☐ Service 禁止直接操作 SQL/QueryWrapper（下沉到 Repository）

☐ Repository 禁止包含业务逻辑

☐ 多业务交叉写操作加 Redis 分布式锁

事务仅包裹 DB 操作，不含 Feign/Redis

☐ 前置校验在事务外

☐ 降级必须非中断性（默认值 + 通知）

☐ XXL-Job 和 Kafka 消费必须 try 全局异常并通知

三、圈复杂度检查示例

💡 为什么要控制复杂度？

AI 倾向于把所有逻辑写在一个方法里。这导致代码难以理解、难以测试、难以维护。圈复杂度 < 16 强制 Agent 把长方法拆成职责单一的小方法。

复制代码

// ❌ AI 常见输出：一个方法干所有事（圈复杂度 = 25）
public void processOrder(OrderRequest req) {
    if (req == null) throw new IllegalArgumentException(...);
    if (req.getItems() == null || req.getItems().isEmpty()) ...
    if (!checkStock(req.getItems())) ...
    if (req.getCouponId() != null) { ... }
    // ... 还有 20 个 if/else
}

// ✅ 正确拆法（每个方法圈复杂度 < 10）
public void processOrder(OrderRequest req) {
    validateOrder(req);
    List<OrderItem> items = checkAndLockStock(req.getItems());
    CouponResult coupon = applyCouponIfPresent(req.getCouponId());
    Order order = buildOrder(req, items, coupon);
    saveOrder(order);
    notifyDownstream(order);
}

四、AI 工具配置文件安全检查

SDD-Agent 在目标仓库开始设计/开发前，强制检查以下文件是否已加入 .gitignore：

文件	风险
`.claude/`	包含 Claude 工具的本地会话和配置
`.claude.json`	包含 API Key 等敏感信息
`.codex/`	包含 Codex 工具的本地配置
`.cursor/`	包含 Cursor 编辑器的 AI 配置
`.cursorignore`	包含 Cursor 忽略规则
`.mcp.json`	包含 MCP 服务器配置和秘钥

如果发现缺失，Agent 会先补充 .gitignore 条目再继续改动：

复制代码

# AI model tool local configs (do not commit)
.claude/
.claude.json
.codex/
.cursor/
.cursorignore
.mcp.json

五、测试规则

测试类型	要求
Happy Path	正常流程必须通过
边界条件	时间边界、数量边界、空值
回归测试	修改不影响已有功能
失败/超时/幂等	异常场景验证
并发测试	分布式锁和幂等验证
覆盖率	整体 ≥ 50%，核心 Service ≥ 75%

**⚠️ 硬规则：**如果测试失败，Agent 不允许将任务标记为完成。必须修复编译或运行时错误后重新测试。

六、门禁流程图

复制代码

AI 生成代码
  ↓
基础约束检查
  ├── Service 内部结构类？ → ❌ 不通过
  ├── Entity 缺注释？      → ❌ 不通过
  ├── 圈复杂度 ≥ 16？      → ❌ 不通过
  └── AI 配置文件入库？    → ❌ 不通过
  ↓ 全部通过
架构约束检查（如适用）
  ├── 分层违规？           → ❌ 不通过
  ├── 事务包含 Feign？     → ❌ 不通过
  └── 降级有通知？         → 必须有
  ↓ 全部通过
运行测试
  ├── 编译失败？           → ❌ 修复后重跑
  ├── 测试失败？           → ❌ 修复后重跑
  └── 全部通过？
  ↓
✅ 交付

七、总结

质量门禁的价值不在于"增加流程"，而在于用机器可检查的规则替代人工审查的疏漏。AI 可以写得很快，但门禁确保它写得不烂。

📌 下一篇预告： 用 Agent 排查线上问题------SLS 日志 + DB/Redis 数据验证

你的团队对 AI 生成的代码有质量检查标准吗？评论区聊聊。

觉得有用请点赞收藏。