质量与上线

约 1381 字大约 5 分钟

QUALITY · MAKE “DONE” PROVABLE

在 AI 参与开发之后，质量保证的重点从“检查每一行”转向“设计一个能快速暴露错误的系统”。这一页把 TG-boot 的质量手段分成四层，并给出上线前必须回答的问题。

一、四层质量防线

层级	手段	主要发现什么
编译	Maven compile	类型、依赖、包名错误
单元 / 集成测试	JUnit、模块测试	业务逻辑、边界条件
架构门禁	ArchUnit + POM 规则	越界依赖、契约污染
运行验证	启动 runner、调用接口	装配、配置、真实链路

四层缺一不可。只有单测、没有门禁，边界会慢慢烂掉；只有门禁、没有运行验证，配置问题会在上线时爆发。

二、测试怎么写才有价值

2.1 先测“边界”，再测“路径”

优先级建议：

跨模块契约的输入 / 输出；
状态机的非法迁移；
幂等与重复消费；
权限与数据隔离；
正常路径。

AI 很擅长生成“正常路径”的测试，但真正值钱的是异常路径。

2.2 同步契约的测试

至少覆盖：

本地 Provider 存在时，是否走本地；
无 Provider 时，是否走远程；
业务异常是否转换为稳定错误码；
返回 DTO 是否符合契约；
超时是否符合配置。

2.3 异步事件的测试

至少覆盖：

事务提交后消息发出；
事务回滚时消息不发出；
重复消费结果一致；
消费者过滤条件正确；
消息字段缺失时的降级行为。

三、架构门禁

mvn -pl spring-boot-starter-architecture-tests -am test

门禁至少守住：

*-api 不依赖 *-biz；
一个 *-biz 不依赖另一个域的 *-biz；
*-api 不定义 Spi*；
POM 依赖方向符合模块规则。

为什么把门禁放在 CI

因为人和 AI 都会犯错，而且都会在“这次特殊”时合理化例外。门禁的价值是：

规则不依赖某个人记得；
失败信息直接指向文件与依赖；
AI 可以在失败后自动修正，形成闭环；
代码评审可以把精力放在设计，而不是抓依赖。

四、Actuator 与生产安全

生产环境禁止把 Actuator 暴露到公网

Actuator 会暴露健康、配置、线程、环境等敏感信息。必须限制访问来源，或只开放在内网 / 管理端口。

最低要求：

不把 /actuator/** 直接暴露给公网；
生产环境不要使用 include: '*'；
只开放必要的 health、info、metrics；
对管理端口做网络隔离；
与 Spring Security 的路径匹配策略保持一致；
将健康检查与业务鉴权分离。

TG-boot 使用 Spring Boot 4 / Spring Security 7，Actuator 路径匹配已经切换到 PathPatternRequestMatcher。升级时不要沿用旧的 AntPathRequestMatcher 写法。

五、MQ 运维基线

生产环境配置真实 RabbitMQ，不依赖嵌入式 Broker；
为每个消费者配置重试与死信队列；
监控 DLQ.{destination}.{group}；
消费者必须幂等；
事件发布必须在事务提交后；
大促 / 批量场景要评估队列积压与消费能力。

六、上线前 12 个问题

新增模块是否已加入正确的聚合与 runner？
是否新增了跨域 *-biz 依赖？
实体、表、索引、唯一键是否一致？
状态字段是否遵循 0/1 与 *ProcessCode 约定？
跨模块调用是否只经过契约？
事件是否在事务提交后发布，消费者是否幂等？
新增配置是否有默认值与生产覆盖方案？
Actuator 是否被限制在内网或管理端口？
日志是否包含敏感信息（令牌、手机号、身份证、密钥）？
是否补充了失败态、空态、超时与重试？
数据库变更是否可回滚？
是否有可执行的回滚与降级预案？

七、部署形态

单 runner

适合大多数早期产品：

一个 JAR；
一次部署；
一套日志；
本地事务简单；
故障域集中。

多 runner

当某个域出现以下信号时再拆：

独立扩容需求明显；
故障隔离要求提高；
团队边界已经稳定；
链路监控需要按域观察；
单进程启动 / 发布已成为瓶颈。

拆分时重点检查：

共享 Broker 地址；
队列与消费组；
数据库 / schema 边界；
网关路由；
链路追踪与日志关联；
分布式事务策略。

八、给 AI 的验收提示词

请对本次改动做上线前审查，不要改代码。

逐项回答：
1. 是否新增跨域 *-biz 依赖？
2. 新增的实体 / 表 / 索引是否一致？
3. 跨模块调用是否只使用 *-api？
4. 事件是否 publishAfterCommit，消费者是否幂等？
5. Actuator 是否可能暴露到公网？
6. 日志是否可能泄漏敏感信息？
7. 是否补充了失败态与回滚方案？
8. 哪些结论是你实际验证过的，哪些只是推断？

对每个“不确定”，给出需要执行的验证命令。

质量不是“没有 bug”，而是“错误能被尽早发现，影响能被限制在边界内”。 QUALITY IS A FEEDBACK LOOP