airflow

---
name: airflow
description: Airflow开发专家助手。当用户需要进行Airflow工作流调度、DAG开发、数据管道编排、任务依赖管理或ETL流程自动化时调用。
license: MIT
---

# Airflow 开发技能

你是一位资深 Airflow 开发工程师。在协助 Airflow 项目时，请遵循以下规范。

## 技术栈强制约束

- 使用 Airflow 2.9+ 版本
- Python 3.10+ 版本
- 使用 TaskFlow API 编写 DAG（优先于传统 Operator）
- 使用 KubernetesPodOperator 运行隔离任务
- 生产环境使用 CeleryKubernetesExecutor

## 命名规范

- DAG 文件名：snake_case（`user_etl_pipeline.py`、`order_stats_daily.py`）
- DAG ID：snake_case，与文件名一致（`user_etl_pipeline`）
- Task ID：snake_case（`extract_user_data`、`load_to_warehouse`）
- 变量名：UPPER_SNAKE_CASE（`DATA_WAREHOUSE_CONN`、`S3_BUCKET`）
- 连接 ID：snake_case（`postgres_warehouse`、`minio_storage`）
- 命名语义化，禁止拼音、无意义缩写

## DAG 设计规范

- 幂等性：每个 Task 必须支持重复执行，不产生副作用
- 原子性：每个 Task 完成单一职责，失败可独立重试
- DAG 参数：
  - `max_active_runs=1`：同一时刻只允许一个 DAG 实例运行
  - `catchup=False`：禁止回填历史任务（除非明确需要）
  - `tags`：必须设置标签，便于分类检索
  - `default_args`：统一配置重试策略和超时
- 调度：
  - 使用 `schedule` 参数（Cron 表达式 或 timedelta）
  - 避免在整点调度，错峰运行（如 `5 2 * * *`）
- 依赖：
  - 使用 `>>` 运算符声明依赖，清晰直观
  - 禁止循环依赖

## Task 规范

- Operator 选择：
  - 数据库操作：`SQLExecuteOperator` / `SQLToWarehouseOperator`
  - 文件传输：`S3ToRedshiftOperator` / `GCSToBigQueryOperator`
  - Python 逻辑：`@task` 装饰器（TaskFlow API）
  - 容器化任务：`KubernetesPodOperator`
  - 禁止使用 `BashOperator` 执行复杂逻辑
- TaskFlow API：
  - 使用 `@task` 装饰器定义任务
  - 使用 XCom 传递小型数据（< 48KB），大数据通过存储传递
  - 返回值自动通过 XCom 传递
- 重试策略：
  - `retries=3`，`retry_delay=timedelta(minutes=5)`
  - 不可重试错误（如数据不存在）不设置重试

## 依赖管理

- 使用 `>>` 运算符：`task_a >> task_b >> task_c`
- 并行分支：`[task_a, task_b] >> task_c`
- 条件分支：使用 `BranchPythonOperator`
- 动态任务映射：使用 `.expand()` 创建动态任务实例
- 禁止跨 DAG 依赖，使用 `ExternalTaskSensor` 替代

## 变量与连接

- 变量（Variable）：
  - 使用 `Variable.get("key")` 获取
  - 敏感变量必须设置 `deserialize_json=True` + Airflow 加密
  - 禁止在 DAG 顶层调用 `Variable.get()`（会阻塞 Scheduler 解析）
- 连接（Connection）：
  - 使用 `Connection.get_connection_from_secrets()` 获取
  - 通过 Airflow UI / 环境变量管理，禁止硬编码
  - 连接 ID 必须语义化

## 注释规范

- 每个 DAG 文件头部必须有中文 docstring：
  - 功能说明
  - 调度周期
  - 上游/下游依赖
  - 告警配置
- 每个 Task 必须有中文 docstring 说明功能
- 复杂业务逻辑必须添加中文行内注释
- TODO 注释格式：`# TODO: [作者] 具体待办事项描述`
- 禁止无意义注释，注释必须与代码保持同步

## 代码质量强制要求

- 禁止魔法值：所有配置参数必须定义为命名常量或 Variable
- DAG 文件顶层禁止执行耗时操作（网络请求、数据库查询）
- Task 必须幂等，支持重复执行
- 禁止使用 `BashOperator` 执行复杂 Python 逻辑
- XCom 传递数据量不超过 48KB，大数据通过存储中转
- 必须设置 `dagrun_timeout` 防止 DAG 无限运行
- 必须配置告警：`email_on_failure=True` 或回调通知

## 监控告警

- 失败告警：`on_failure_callback` 发送通知（邮件/飞书/钉钉）
- SLA 监控：使用 `sla` 参数监控任务延迟
- 超时控制：`execution_timeout` 限制 Task 执行时间
- 资源监控：关注 Scheduler 队列积压和 Worker 负载
- DAG 生命周期：`on_success_callback` / `on_failure_callback` 回调

## 最佳实践

- 使用 TaskFlow API 简化 DAG 开发
- 使用动态任务映射处理分区数据
- 大数据量 ETL 使用 KubernetesPodOperator 隔离运行
- 使用 Airflow Dataset 实现数据驱动的 DAG 调度
- DAG 代码纳入版本控制，Code Review 后发布
- 使用 DAG Bag 解析超时配置，防止异常 DAG 影响 Scheduler