如何用Architecture Tests守护模块边界:DownKyi测试体系与ratchet机制揭秘
如何用Architecture Tests守护模块边界:DownKyi测试体系与ratchet机制揭秘
哔哩下载姬(DownKyi)是一款跨平台哔哩哔哩视频下载工具,支持批量下载、8K 与杜比视界,并内置音视频提取、去水印等工具箱。当代码库增长到几十个模块时,架构如何避免悄悄腐化?本文带你走进 DownKyi 的测试体系,揭秘 Architecture Tests 与 ratchet(棘轮)机制如何自动守护模块边界。
一、为什么大项目需要"架构守卫"?🛡️
很多项目的架构规范只写在文档里,靠口头约定维持。时间久了,总会出现这样的"小事故":
- 核心协议层偷偷引了 UI 框架,导致核心库无法在其他平台复用;
- 两个模块互相引用,形成循环依赖,一拆就崩;
- 到处出现同名的
Subtitle类型,编译能过,排查起来却是一团乱麻。
DownKyi 的解法很直接:把架构规矩写成可自动执行的测试。规则不再依赖人的自觉,每次提交都会由 CI 统一验收。
二、DownKyi 分层架构:依赖方向一览表
在谈测试之前,先看懂它要守护的对象。DownKyi 按经典分层组织,依赖方向自上而下单向流动:
| 项目 | 职责 | 可以依赖 |
|---|---|---|
DownKyi |
可执行入口,只有一个 Program.cs |
Desktop |
DownKyi.Desktop |
Avalonia 界面、Views/ViewModels、导航与对话框 | Application / Domain / Infrastructure / Core |
DownKyi.Application |
用例(use cases)与各端口契约 | Domain |
DownKyi.Domain |
下载任务状态机,持久化状态的权威 | 无(保持纯净) |
DownKyi.Infrastructure |
FFmpeg 运行时、SQLite 存储、持久化适配器 | Application / Domain |
DownKyi.Core |
哔哩哔哩协议解析、弹幕转换(保持 headless) | Application |
这套结构完整记录在 ARCHITECTURE.md 中。而"谁可以依赖谁"这条规则,由 ProjectDependencyTests.cs 逐项目比对 .csproj 引用强制执行;同时用深度优先遍历检测整个依赖图是否存在环(循环依赖检测)。
三、测试体系全景:10 个测试项目各守一摊
DownKyi 的测试按职责分层,各层互不越位(详见 docs/testing/README.md):
| 测试项目 | 守护重点 |
|---|---|
DownKyi.Domain.Tests |
状态机转换与值对象 |
DownKyi.Application.Tests |
命令、查询与端口契约 |
DownKyi.Infrastructure.Tests |
SQLite 迁移、写回、FFmpeg 适配器 |
DownKyi.Core.Tests |
哔哩哔哩 API 契约、弹幕转换 |
DownKyi.Desktop.Tests |
真实 Host 下的 UI 冒烟测试 |
DownKyi.Tests |
端到端服务与可执行兼容性 |
DownKyi.Architecture.Tests |
依赖方向、模块边界、仓库结构 |
DownKyi.Windows/Linux/MacOS.Tests |
各平台进程与打包行为 |
所有测试都通过统一入口 tools/DownKyi.CentralTestRunner 执行:它自动发现 tests/ 下所有测试项目、按平台选择用例集、逐项目校验 TRX 报告非空,测试失败时还会保存进程快照证据(Flight Recorder)。
四、ratchet(棘轮)机制:债务只减不增 ⚙️
这是全文最值得借鉴的设计。棘轮就像自行车的飞轮:只能往前转,不能倒转。
传统做法是给架构违规加"豁免基线",久而久之基线变成免责金牌。DownKyi 在 docs/testing/module-boundary-ratchets.md 中把规则写得很明确:
- 把已确认的既有违规设置为最大集合,即 ratchet 基线;
- 删掉一条违规 → 测试通过(债务减少);
- 新增任何一条违规 → 测试失败(债务禁止增长);
- 修复债务后,同步删掉已失效的基线条目。
为什么不用"现状先红"(把必然失败的测试直接合入)?因为 CI 一旦永久红灯,后续真正的回归信号就会被淹没——主线必须保持绿色,只允许债务下降。
更严格的是,部分边界已"收 tight 到零":不再保留基线,任何命中直接失败。例如 Core 中的 Avalonia 引用、生产代码中的 ImmutableObservableCollection<T>、Core 不得包含 UI 或二维码渲染依赖 等(规则清单见 module-boundary-ratchets.md)。
五、实战:架构测试具体在守护什么?
命名与文件组织债务
全仓库同名的"简单类型名"(如 Subtitle、VideoPage)会被扫描分组,只有已登记的基线 被允许存在,新增重名立即失败;"文件名必须匹配主类型"的既有例外同样按 ratchet 管理,不允许继续扩散。
行为契约防回退
架构测试不只查引用,还查行为:
- 下载清单必须只暴露
ReadOnlyObservableCollection<T>,可变集合私有持有(契约测试); - 下载运行时不得轮询 UI 集合"偷活干",防止后台逻辑与界面状态纠缠;
- 哔哩哔哩 HTTP 客户端禁止恢复静态字段或同步调用,保证异步传输架构不可逆转。
Bilibili 接口清单审计
audit-bilibili-api.ps1 会从源码生成全部硬编码 API 端点清单,再由 BilibiliApiInventoryArchitectureTests.cs 比对:新增一个哔哩哔哩接口必须让"代码中的事实"与"生成的清单"完全一致,接口数量从此有了可审计的账本。
六、一键运行:如何触发全部门禁?
本机与 CI 走同一条路径,没有平行的 dotnet test 后门:
# 完整解决方案测试(经由 CentralTestRunner 统一调度)
pwsh ./script/test-solution.ps1
# 模块边界审计,输出结构化 JSON 报告
pwsh ./script/audit-module-boundaries.ps1 -OutputPath artifacts/architecture/module-boundary-audit.json
严格验证的完整命令序列(含 Release 构建、格式校验、密钥扫描等)见 docs/operations/verification-and-rollback.md。架构测试与审计脚本互为镜像:测试守护运行时,脚本提供人类可读的审计证据。
七、给新手的三点启示 📌
- 把规矩写成可执行的测试——文档会被遗忘,CI 门禁不会;
- ratchet 是存量债务的最优解——不要求一步清零,但绝不允许倒退,主线永远是绿的;
- 测试即文档——
Architecture.Tests里每一条断言,都是架构决策的"活注释",比任何 README 都更贴近现实。
延伸阅读:docs/maintenance.md(领域路由与维护)、docs/testing/README.md(测试分层与正式入口)、ARCHITECTURE.md(当前 owner 与依赖方向)。
