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 生成的代码有质量检查标准吗?评论区聊聊。

觉得有用请点赞收藏。

相关推荐
AI算力1 小时前
让安全驾驶有“AI”相伴|腾视科技DMS视频监控一体机,守护每一次出行
人工智能·科技·ai·车载终端·ai算力·车载智能终端·车载dvr
泯泷2 小时前
超越基准:Claude Opus 4.5 的 4 个惊人洞察
人工智能
果果软件2 小时前
2026 后台管理系统选型:若依、JeecgBoot、芋道、NocoBase 和 GewuMind Boot 怎么选?
java·人工智能·后端·ai·开源
Csvn2 小时前
刚开始用 WorkBuddy,第一步该做什么?
人工智能
一水鉴天2 小时前
同一与唯一:AppBus 外壳与 DevOps 内核 之1 20261121(元宝)
人工智能·机器学习
Wellijohn3 小时前
一个 Android 老兵的十年开源路:从 167 star 的滑动控件,到本地优先的 AI Agent
android·人工智能·开源
ZONGYUAN-ROOT3 小时前
【API配额】API 配额监控告警不生效?用 Python 监控读数变化量,抓住静态阈值漏掉的「假重置」
人工智能
Wellijohn3 小时前
我把公司内部的 12 个 CRUD 接口交给了 AI Agent,然后省出了两周
人工智能·python·mcp
伞伞悦读5 小时前
【第92期】逻辑回归的分数概率与阈值的实验与排查
人工智能·python·深度学习·机器学习