主题
十二、质量与验证
本章速览:读完后你会知道 —— ① 测试与闸门各防什么(927 条用例 / 24 条架构规则 / 文档与配置检查器);② 为什么规模数字必须进闸;③ 发布前必须跑哪 6 步。
这个项目的质量策略是"把纪律变成闸门":能机械检查的绝不靠自觉, 检查不过就不许发布。数字、清单、契约、行为都有对应的闸。
12.1 测试与检查体系
| 层 | 工具/位置 | 规模 | 命令 |
|---|---|---|---|
| 后端单测/集成 | JUnit 5 + Mockito + 真实 HTTP(部分) | 927 条用例 / 216 个测试类 | mvn -B -o clean test(必须 clean) |
| 架构规则 | ArchitectureGuardTest | 24 条架构规则 | 包含在 test 中 |
| 模块边界 | ModuleBoundaryTest | 业务模块互不实现依赖 | 同上 |
| 文档覆盖 | docs/tools/check-doc-coverage.mjs | 10 类覆盖 + 4 项结构 + 4 项附录准确性 | node docs/tools/check-doc-coverage.mjs |
| 文档数字 | ArchitectureGuardTest 规则 17 | 规模数字/迁移号/表数/@Mapper/页面数 | 在 test 中 |
| API 接线 | docs/tools/check-api-wiring.mjs | 前端 332 路径 ↔ 后端端点 | node …(含未接 UI 清单) |
| 配置台账 | vite-cosmos-web/scripts/check-config-registry.mjs | 176 键 ↔ 面板 ↔ 读点 | 在 web verify 中 |
| MCP 契约 | docs/tools/check-mcp-tools.mjs | 70 工具 ↔ 真机 tools/list | 需两个令牌,手动/巡检 |
| 部署守卫 | deploy/scripts/check-deploy-guards.sh | 闸 A–F(挂载/健康/回滚/密钥/迁移期望键) | bash … |
| 宿主体检 | deploy/scripts/doctor.sh | 25 项(端口/挂载/令牌/备份/迁移/环回) | bash deploy/scripts/doctor.sh |
| 管理端 e2e | Playwright | 53 passed / 1 skipped(生产只读) | npm run test:e2e |
| 管理端单测 | Vitest | 请求层/工具/组件 | npm test |
| 前端构建 | vue-tsc -b + vite build | 双前端 | npm run build |
| 文档站构建 | VitePress(源文件仍是本文) | 30 页(首页 + 15 章 + 14 附录) | npm --prefix docs-site run build |
| 灾难恢复 | restore-drill.sh / 官方 mysql-restore.sh | 恢复演练(101 表 / ~42s) | 手动,每季度/大改后 |
12.2 为什么"数字进闸"
文档里的规模数字是读者判断完整度的依据,却最容易漂:历史上 Java 文件 820→793、 @TableName 97→93、测试 826→836、后台页面 92→91、Flyway 149→163 都漂过。 架构规则 17 与文档检查器把"可机械计数"的项固化:改代码不同步文档 = 测试红。
同理,端点/表/配置键/错误码/脚本/路由/定时任务都有"源码 ↔ 文档"双向核对, 新增而不登记会直接失败 —— 这是"文档是可执行事实"的落地方式。
12.3 审查记录与修复文化
docs/全项目审查记录.md 记录每一轮全链路审查的「症状 → 根因 → 修法 → 验证」。 比较典型的几类(都沉淀成了测试或闸):
- 假成功/谎报:更新 0 行仍报成功、存上了却说没存上、跳过没有理由;
- 静默失效:配置写脏值被静默回退、出网档位错字变成放行、润色缓存永远返回模板;
- 边界泄漏:附件 mime 注入面、孤儿清理引用面漏项、导出包把笔记变文章;
- 时间炸弹:固定日期测试在 30 天后永久变红(本轮已修)。
纪律:修一次,补一类测试;修复必须给真机证据(生产库行、日志、请求响应), 不允许"看代码觉得好了"。
12.4 发布前清单
mvn -B -o clean test(必须 clean);npm run build(后台 + 门户);后台npm run test:e2e;node docs/tools/check-doc-coverage.mjs、check-api-wiring.mjs;- web 侧
npm run verify(样式 token / i18n / 配置台账 / build); bash deploy/scripts/check-deploy-guards.sh;bash deploy/scripts/doctor.sh;- 部署后:
curl -sk https://127.0.0.1/api/health -H 'Host: vite66.cn'、健康检查通过、 启动日志 ERROR=0、能力健康看板无异常跳过。