Airflow中PythonOperator的op_kwargs与templates_dict使用区别

首先澄清一个常见误区：很多老教程会误导人说只有templates_dict支持Jinja模板渲染，这是Airflow 1.x时代的遗留结论。2.x版本从源码配置template_fields= ['templates_dict', 'op_args', 'op_kwargs']就能看出，这三个参数里的内容都能被Airflow的Jinja引擎正常渲染，二者的核心区别根本不是「能不能渲染模板」，而是传参逻辑和设计定位完全不同。

核心差异 #

• 传参路径和取值方式完全不同
  op_kwargs是直接给绑定的python_callable传关键字参数的通道，传进去的内容会被直接解包，和你平时手动调用Python函数传**kwargs的行为完全一致。写可调用函数的时候，可以直接定义对应形参接收，不需要额外从上下文取。
  templates_dict里的内容不会被解包成函数入参，所有值会在DAG运行时被Jinja引擎渲染完成后，统一注入到任务的上下文context中，必须在函数里通过context['templates_dict'][键名]才能拿到对应的值。
• 设计定位不同
  op_kwargs是普通的业务参数传参入口，设计目标就是替代手动调用函数时传的关键字参数，不管传的是固定常量、Python对象、还是带Jinja语法的模板字符串，本质都是给业务逻辑传参用的。
  templates_dict最早是为了解决Airflow 1.x中op_kwargs不支持模板渲染的问题设计的专属模板承载容器，所有放在这里的值默认就是要走模板渲染逻辑的，定位是集中存放需要渲染的动态内容，不和普通业务参数混放。

代码示例对比 #

op_kwargs 用法 #

from airflow.operators.python import PythonOperator
from datetime import datetime

# 直接定义形参接收op_kwargs传的内容，符合普通Python编码习惯
def sync_user_data(table_name, run_date):
    print(f"正在同步表 {table_name}，数据日期: {run_date}")

sync_task = PythonOperator(
    task_id="sync_user",
    python_callable=sync_user_data,
    # 这里的{{ ds }}会被正常渲染，不需要放到templates_dict
    op_kwargs={
        "table_name": "dim_user",
        "run_date": "{{ ds }}"
    },
    start_date=datetime(2024, 1, 1)
)

templates_dict 用法 #

from airflow.operators.python import PythonOperator
from datetime import datetime

def run_generic_sql(**context):
    # 必须从上下文里取渲染后的模板内容
    tpl_content = context["templates_dict"]
    rendered_sql = tpl_content["query_sql"]
    print(f"执行SQL: {rendered_sql}")

sql_task = PythonOperator(
    task_id="run_order_sql",
    python_callable=run_generic_sql,
    # 模板内容统一放在这里，不会直接传给函数形参
    templates_dict={
        "query_sql": "SELECT * FROM dwd_order WHERE dt = '{{ ds_nodash }}'"
    },
    start_date=datetime(2024, 1, 1)
)

适用场景 #

• 优先选op_kwargs：90%的常规业务场景都用这个，只要业务函数需要明确接收参数，不管参数是不是带模板，都直接放这里，代码可读性高，符合普通Python的编码习惯，没必要特意绕到templates_dict里。
• 选templates_dict的场景：
  • 需要兼容Airflow 1.x版本的老DAG；
  • 有大量集中的模板类内容（比如动态SQL、动态文件路径、批量宏变量引用），想和普通固定业务参数做逻辑隔离，避免op_kwargs里内容太杂；
  • 写通用工具类的callable（比如通用SQL执行、通用文件校验逻辑），不想给函数固定一堆形参，统一从上下文拿渲染后的模板内容，适配不同任务的传参需求。

踩坑提醒：不要为了「能渲染模板」特意把所有带Jinja的参数都塞到templates_dict里，2.x版本完全没这个必要，平白增加代码取值的冗余逻辑。

内容的提问来源于stack exchange，提问作者kkpalczewski