如何用Architecture Tests守护模块边界:DownKyi测试体系与ratchet机制揭秘

原创2026-11-13 20:09:291,919 阅读

如何用Architecture Tests守护模块边界:DownKyi测试体系与ratchet机制揭秘

哔哩下载姬(DownKyi)是一款跨平台哔哩哔哩视频下载工具,支持批量下载、8K 与杜比视界,并内置音视频提取、去水印等工具箱。当代码库增长到几十个模块时,架构如何避免悄悄腐化?本文带你走进 DownKyi 的测试体系,揭秘 Architecture Tests 与 ratchet(棘轮)机制如何自动守护模块边界。

一、为什么大项目需要"架构守卫"?🛡️

很多项目的架构规范只写在文档里,靠口头约定维持。时间久了,总会出现这样的"小事故":

  • 核心协议层偷偷引了 UI 框架,导致核心库无法在其他平台复用;
  • 两个模块互相引用,形成循环依赖,一拆就崩;
  • 到处出现同名的 Subtitle 类型,编译能过,排查起来却是一团乱麻。

DownKyi 的解法很直接:把架构规矩写成可自动执行的测试。规则不再依赖人的自觉,每次提交都会由 CI 统一验收。

哔哩下载姬 DownKyi 登录界面示意图:哔哩哔哩扫码登录与视频下载

二、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 中把规则写得很明确:

  1. 把已确认的既有违规设置为最大集合,即 ratchet 基线;
  2. 删掉一条违规 → 测试通过(债务减少);
  3. 新增任何一条违规 → 测试失败(债务禁止增长);
  4. 修复债务后,同步删掉已失效的基线条目。

为什么不用"现状先红"(把必然失败的测试直接合入)?因为 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。架构测试与审计脚本互为镜像:测试守护运行时,脚本提供人类可读的审计证据。

七、给新手的三点启示 📌

  1. 把规矩写成可执行的测试——文档会被遗忘,CI 门禁不会;
  2. ratchet 是存量债务的最优解——不要求一步清零,但绝不允许倒退,主线永远是绿的;
  3. 测试即文档——Architecture.Tests 里每一条断言,都是架构决策的"活注释",比任何 README 都更贴近现实。

延伸阅读:docs/maintenance.md(领域路由与维护)、docs/testing/README.md(测试分层与正式入口)、ARCHITECTURE.md(当前 owner 与依赖方向)。

登录后查看全文
downkyicore