4. Databricks Asset Bundles核心机制

Databricks Asset Bundles（简称 DAB）把作业、流水线、模型等 Databricks 资源从“在 UI 里手工点出来”变成“用声明式配置描述出来”。它的核心载体就是项目根目录下的 databricks.yml（也常被称作 bundle 配置文件）。理解这个文件的结构，等于掌握了整个 Bundle 的骨架：哪些字段决定项目身份，哪些字段声明资源，哪些字段负责把同一份资源映射到不同环境。

一个典型的 Bundle 目录通常长这样：根目录放 databricks.yml，资源定义放在 resources/ 下，源码放在 src/ 下。配置文件本身由若干顶层块组成，最关键的几块是：bundle（项目名）、include（引入其它配置文件）、workspace（工作区主机与认证）、variables（变量声明）、targets（目标环境）以及 resources（资源声明）。其中 resources 和 targets 是日常改动最频繁的两块。

先看 resources。它下面按资源类型分组，常见的有 jobs、pipelines、models、experiments。每个资源有一个逻辑键（如 etl_daily_job），这个键是 Bundle 内部引用资源的名字，部署时 Databricks 会据此生成或更新真实资源。以作业为例，一个最小声明包含 name、tasks，任务里再指定 notebook_path 或 python_wheel_task、集群配置等。流水线则用 catalog、target、libraries 描述。模型资源通常配合 MLflow 实验路径与 serving 端点声明。

resources:
  jobs:
    etl_daily_job:
      name: "etl_daily_${var.env}"
      schedule:
        quartz_cron_expression: "0 0 2 * * ?"
        timezone_id: "Asia/Shanghai"
      tasks:
        - task_key: bronze_to_silver
          notebook_task:
            notebook_path: ../src/etl/bronze_to_silver.py
          new_cluster:
            spark_version: "15.4.x-scala2.12"
            node_type_id: "i3.xlarge"
            num_workers: 2
  pipelines:
    silver_pipeline:
      name: "silver_pipeline_${var.env}"
      catalog: ${var.catalog}
      target: ${var.schema}
      libraries:
        - notebook:
            path: ../src/pipeline/silver.py

注意上面出现的 ${var.env}、${var.catalog}，这就是参数化的入口。变量在顶层 variables 中声明，可以给默认值，也可以不给。声明之后，在 resources 里用 ${var.xxx} 引用，在 targets 里为每个环境覆盖具体取值。这样同一份资源定义就能在 dev、staging、prod 之间复用，而差异只集中在 target 块里。

targets 是环境差异的集中地。每个 target 可以覆盖变量、指定不同的 workspace host、设置 mode（development 或 production）、配置 presets（如名称前缀、是否暂停调度）、以及 run_as 身份。development 模式下，Databricks 会自动给资源名加前缀、把调度暂停，避免开发环境误触发生产任务；production 模式则保持资源名与调度原样。这种“同一份声明、多环境投影”的机制，正是 DataOps 持续交付的基础。

变量覆盖的优先级需要记清楚：命令行 --var 最高，其次是 target 中的 variables，最后是顶层 variables 的默认值。理解这个顺序，才能在排查“为什么部署到 prod 却用了 dev 的 catalog”这类问题时快速定位。

写完配置后，不要急着部署。DAB 提供了一组本地验证命令，可以在不触碰远端工作区的情况下先做静态检查。databricks bundle validate 会解析 YAML、检查字段合法性、校验变量引用与资源引用是否完整，并输出解析后的最终配置。加上 -t prod 可以验证指定 target 的展开结果，确认参数覆盖是否符合预期。databricks bundle schema 可以输出当前 CLI 版本支持的完整配置 schema，用于对照字段名。databricks bundle summary 则展示 Bundle 的概览信息，包括资源数量与目标环境。

# 验证默认 target
databricks bundle validate

# 验证 prod 目标，查看变量展开结果
databricks bundle validate -t prod

# 查看解析后的完整配置（含变量替换）
databricks bundle validate -t prod --output json

# 查看 Bundle 概览
databricks bundle summary -t prod

验证通过后，常用命令是 databricks bundle deploy -t dev 部署到开发环境，databricks bundle run etl_daily_job -t dev 触发运行，databricks bundle destroy -t dev 清理资源。部署时 Bundle 会计算期望状态与当前状态的差异，只做必要的创建或更新，这也是它比手工操作更适合持续交付的原因。

把这几块串起来看：resources 回答“要创建什么”，variables 回答“哪些值需要可变”，targets 回答“每个环境取什么值”，validate 回答“这份配置是否自洽”。四者配合，才构成一个可重复、可审查、可回滚的 Bundle 交付单元。