dbt模型血缘与测试覆盖率检查器

解决什么问题

dbt 项目的模型数量一旦涨到几十上百，几个典型的工程问题就会集中爆发：

• 测试覆盖靠记忆。某个模型加了新字段、改了 join 逻辑，到底有没有对应的 schema tests 或 data tests，往往只有写它的人知道。人一走，断档就来了。
• 血缘关系说不清。想回答“这张表下游还有谁”“我改了这个模型会影响哪些报表”，通常只能对着 run_results.json 或手动在 dbt Cloud UI 里点来点去。
• 文档与断言滞后。模型的 description 停留在半年前的状态，unique、not_null 这类基础断言缺失或已经失效，质量门槛形同虚设。
• 测试结果与代码脱节。CI 里跑的测试通过与否，和仓库里模型的定义之间缺少一个可直接查询的关联。

这个技能就是针对上述场景，把 dbt 项目的静态工件和运行时结果放在同一张视图里检查。

它是如何工作的

核心思路很直接：以 dbt 编译产物为输入，而不是去解析模型的 SQL 源码。

1. 读取工件。解析项目里的 manifest.json 和 catalog.json。前者包含模型的依赖关系、配置和测试定义，后者包含列级别的统计信息与描述。
2. 构建血缘图。根据 manifest 中节点的 depends_on 信息重建模型上下游关系，输出可读的层级或图结构，而不是隐式的 JSON 嵌套。
3. 扫描覆盖率缺口。逐模型检查是否存在测试、description 是否为空或明显过时、是否配置了 unique / not_null 等唯一性断言，把缺项汇总成清单。
4. 关联 dbt Cloud 运行结果。通过 dbt Cloud API 拉取最近一次（或指定）run 的测试执行状态，为每个模型标注 passed 或 failed，让静态定义和真实执行结果对齐。

适用边界与注意点

• 依赖工件完整性。manifest.json 和 catalog.json 需要由 dbt compile / dbt docs generate 产出。如果项目还没跑过编译，或使用的是旧版 dbt，字段结构可能不一致，检查结果会有偏差。
• 覆盖的是 dbt 原生测试。它统计的是 dbt 层面的通用测试与断言，不会自动识别你在单元测试框架里手写的 SQL 校验逻辑。
• Cloud API 访问权限。拉取运行结果需要有效的 dbt Cloud API 凭证，且账号对目标项目有读取权限。本地纯离线场景只能得到静态检查部分。
• 描述“过时”的判定是启发式的。它只能提示可能过期的文档，无法判断业务语义是否真的失效，最终仍需人工确认。
• 结果用于排查，不替代 CI 门禁。它适合在 review、审计或接手项目时快速摸底，真正拦截回归还是要靠流水线里的实际测试执行。