質量與上線

约 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