dbt 项目提交前检查

要解决的问题

dbt 项目的模型规模膨胀后，命名不规范、引用缺失、依赖顺序错误、元数据缺失等问题会逐步积累。这些问题往往在 merge request 评审阶段才被发现，返工成本高；更糟的是，某些模型校验缺失会直接流入生产环境，影响下游数据消费。

技能如何工作

该技能把 dbt-checkpoint 挂载到本地的 pre-commit 钩子上，在 git commit 触发时自动执行一系列检查：

• 语法检查：调用 dbt parse 校验项目 DAG 是否能正常编译
• SQL 格式化：确保模型 SQL 风格统一，避免格式化噪音混入提交
• 代码质量检查：校验模型命名规范、缺失的 description、存在未解析引用的模型等问题
• 模型卫生验证：检查文档完整性、标签配置、owner 元数据等

核心步骤是把对应钩子写入 .pre-commit-config.yaml，之后每次提交都会自动触发。检查结果不通过时，提交会被拦截，问题在本地修复即可。

适用边界与注意点

• 该技能依赖本地已安装 Python、pre-commit、dbt-checkpoint 以及可正常解析的 dbt 项目
• 钩子只在本地提交时生效，无法覆盖团队成员漏跑 pre-commit 的情况，因此 CI 侧仍需独立配置校验
• 检查项以静态规则为主，无法替代 dbt test 的数据质量校验
• 项目结构特殊的团队可能需要调整钩子参数或跳过部分检查