airflow_demo/README.md

Airflow Demo

一个用于学习和练习 Apache Airflow 的示例代码仓库。仓库通过多个独立的 DAG 示例，演示任务定义、参数配置、分支选择、任务间通信、传感器以及跨 DAG 依赖等常见用法，并包含 Hive 集成示例。

本仓库以学习示例为主。运行前请检查代码中使用的 Airflow Operator、Connection ID、文件路径和外部服务配置，并根据自己的环境进行调整。

环境参考

当前学习环境可参考以下版本：

• Python 3.6
• Apache Airflow 2.2.5
• Apache Hive 2.3.6（仅运行 Hive 示例时需要）

Airflow 不同版本之间的导入路径、Provider 依赖和部分参数可能存在差异。若使用其他版本，请以当前安装版本的文档和实际报错为准。

示例目录

文件	主要内容
hello_world.py	基础 DAG 与任务定义入门示例
hello_world2.py	另一种基础工作流与任务编排示例
args_example.py	DAG 和任务的参数配置示例
branch_example.py	使用分支任务，根据 Python 函数的返回值选择后续执行路径
xcom_example.py	使用 XCom 在任务之间传递少量数据
xcom_example2.py	XCom 的另一种任务间数据传递场景
file_sensor_example.py	使用 Sensor 等待文件出现或上游任务达到指定状态
dag_dependency1.py	跨 DAG 依赖示例的一部分，建议与 dag_dependency2.py 配合阅读
dag_dependency2.py	跨 DAG 依赖、触发或等待相关示例，具体行为以代码配置为准
hive_provider.py	Hive Operator / Provider 集成示例，需要配置对应的 Hive 连接和服务

如何运行

1. 确认 Airflow 环境

先进入已经安装 Airflow 的 Python 虚拟环境，并确认 Airflow 可以正常执行：

airflow version

2. 克隆仓库

git clone https://gitea.kennethcheng.cc/KennethCheng/airflow_demo.git
cd airflow_demo

3. 将示例放入 DAG 目录

查看当前 Airflow 配置的 DAG 目录：

airflow config get-value core dags_folder

确认目录无误后，将示例 Python 文件复制到该目录。也可以根据自己的部署方式，将仓库目录配置为 Airflow 能够扫描到的 DAG 目录：

DAGS_DIR="$(airflow config get-value core dags_folder)"
cp ./*.py "$DAGS_DIR"/

请确保 Airflow Scheduler 对这些文件有读取权限。若使用容器或多节点部署，还需要保证相关节点能够访问相同的 DAG 文件及所需资源。

4. 检查 DAG 是否加载成功

airflow dags list

如果示例未出现在列表中，检查导入错误：

airflow dags list-import-errors

也可以打开 Airflow Web UI，查看 DAG 列表、任务依赖图、运行日志和任务状态。具体启动 Scheduler、Web Server 的方式取决于现有 Airflow 部署。

5. 运行示例

在 Web UI 中找到对应 DAG 并手动触发，或使用命令行触发：

airflow dags trigger <dag_id>

将 <dag_id> 替换为代码中实际定义的 DAG ID。DAG ID 不一定与 Python 文件名相同；运行前请先查看对应文件中的 dag_id 配置。

运行前需要注意

跨 DAG 依赖

阅读 dag_dependency1.py 和 dag_dependency2.py 时，注意上游和下游 DAG 的 dag_id、调度时间、逻辑日期（Logical Date / Execution Date）以及 Sensor 的等待条件。两个 DAG 的调度方式或逻辑日期不匹配时，下游任务可能一直等待。

文件传感器

运行 file_sensor_example.py 前，请检查代码中配置的目标文件路径。该路径必须对运行 Sensor 任务的 Airflow 执行环境可见；如果文件由其他主机或容器生成，需要确认目录挂载或共享方式正确。

XCom

XCom 适合传递任务间需要的小型元数据或计算结果，不建议用来传输大型 DataFrame、文件内容或大批量业务数据。大型数据通常应存储在文件系统、对象存储或数据库中，再通过 XCom 传递其路径或标识。

Hive 集成

运行 hive_provider.py 前，请确认 HiveServer2 / Metastore 等所需服务已启动且网络可达，并在 Airflow 的 Admin → Connections 中配置连接。Connection ID、连接参数和代码中的配置必须一致；若缺少相应 Provider 包，请安装与当前 Airflow 版本兼容的依赖。

建议学习顺序

1. 从 hello_world.py、hello_world2.py 熟悉 DAG 和 Operator 的基本结构。
2. 阅读 args_example.py，了解 DAG 与任务的参数配置。
3. 学习 xcom_example.py、xcom_example2.py，掌握任务间传递小型数据的方法。
4. 阅读 branch_example.py，理解分支选择与不同任务路径。
5. 练习 file_sensor_example.py 和两份跨 DAG 依赖示例，理解任务等待与工作流协作。
6. 最后阅读 hive_provider.py，尝试将 Airflow 与 Hive 环境连接起来。

说明

本仓库用于个人学习和功能演示。用于生产环境前，请根据实际业务补充依赖管理、连接与敏感信息管理、任务超时、重试策略、告警、日志和数据质量校验等配置。