# 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 可以正常执行：

```bash
airflow version
```

### 2. 克隆仓库

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

### 3. 将示例放入 DAG 目录

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

```bash
airflow config get-value core dags_folder
```

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

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

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

### 4. 检查 DAG 是否加载成功

```bash
airflow dags list
```

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

```bash
airflow dags list-import-errors
```

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

### 5. 运行示例

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

```bash
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 环境连接起来。

## 说明

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