Apache DolphinScheduler 参数优先级详解：五大参数来源的冲突裁决规则与实战验证

• 任务调度
• 大数据
• 后端
• 前端

DolphinScheduler 工作流中的参数值可能来自项目级、工作流级、任务节点级、上游传递等多个来源，当参数名重复时系统如何裁决取值，直接影响任务执行结果。本文以官方文档「参数优先级」为骨架，系统讲解五大参数来源的作用域、启动参数 > 本地参数 > 上游任务传递的参数 > 全局参数 > 项目级别参数的完整优先级链、上游多任务同名参数的取值规则，并结合 Shell / SQL 任务实例与源码实现，帮助你准确预测每一个参数在运行时的最终取值。

一、参数的五大来源：先分清"参数从哪来"

在讨论优先级之前，先明确 DolphinScheduler 中参数的五个定义位置。文档 参数优先级 将其归纳为五类，每一类都有独立的作用域与定义入口：

几个容易混淆的要点：

• 项目级别参数作用于"整个项目"，即该项目下所有工作流、所有节点都能引用，是范围最大的参数；
• 全局参数在"工作流定义"页面配置，只对当前工作流生效，配置方式为在工作流定义页面点击"设置全局"右侧加号，填写变量名、值并选择类型（参考 全局参数）；
• 启动参数在"工作流启动"页面配置，DolphinScheduler 会将其合并进全局参数中参与执行，二者作用域相同、面向整个工作流（参考 启动参数）；
• 本地参数默认仅节点内可见，只有方向为OUT时才允许被下游任务引用，这与 本地参数 中IN / OUT的语义一致；
• 上游传递的参数是单向的，仅能由上游传给有依赖关系的下游，若节点之间没有依赖关系，则局部参数无法通过上游传递（参考 参数的引用）。

二、核心规则：参数优先级从高到低

因为参数存在多个来源，当参数名相同时，取值就会产生冲突。DolphinScheduler 的裁决规则（从高到低）为：

启动参数 > 本地参数 > 上游任务传递的参数 > 全局参数 > 项目级别参数

理解这条链的关键在于：

1. 启动参数优先级最高：由于启动参数在每次运行时动态注入，它天然覆盖工作流定义期设置的同名全局参数，适合"每次运行临时改变参数值"的场景（例如 启动参数 中的例子，修改dt参数后再执行可输出不同日期）；
2. 本地参数高于全局参数与项目参数：节点自定义参数可以"屏蔽"掉更大作用域的同名参数，实现节点级个性化取值；
3. 上游传递的参数高于全局参数、低于本地参数：任务链传递的中间结果可以覆盖全局配置，但无法覆盖下游节点自己显式定义的同名本地参数；
4. 全局参数高于项目级别参数：工作流级别的配置优先于项目级别的公共配置。

关联佐证：在 参数的引用 的完整示例中，Node_A 脚本中为output赋值为 1，但日志显示值为 100（来自全局参数），而在 Node_B 中按优先级规则输出为 1，证明"上游传递的参数 > 全局参数"在实际运行中生效。

三、上游多个任务传递同名参数时的取值规则

除了跨作用域的优先级，还存在同层级的冲突：当上游存在多个任务向下游传递参数，且传递的参数名相同时，下游节点按以下规则取值：

• 优先使用值为非空的参数：空值参数被自动过滤；
• 多个非空参数并存时，按上游任务的完成时间排序，选择完成时间最早的上游任务对应的参数。

也就是说，在多上游场景下"先完成者胜出"。这与任务实例的执行完成时间（endTime）强相关，后完成的上游节点即使同名参数值更新，也不会覆盖先完成者，除非先完成者的值为空。

四、实战示例一：Shell 节点中本地参数如何压制上游参数

下面通过文档给出的 Shell 节点示例，直观理解"本地参数 > 上游任务传递的参数"这条规则。

4.1 无依赖关系时，上游参数不可见

工作流中包含三个节点：createParam（产生参数的源头）、useParam（使用参数的下游）、noUseParam（无依赖的旁路节点）：

节点useParam可以使用节点createParam中设置的变量；而useParam与noUseParam之间没有依赖关系，所以并不会获取到noUseParam的变量。上图中只是以 Shell 节点作为例子，其他类型节点具有相同的使用规则——这正是 参数的引用 中强调的"若节点之间没有依赖关系，则局部参数无法通过上游传递"。

4.2 同名参数：本地参数值覆盖上游传递值

createParam节点在使用变量时直接使用即可。该节点设置了key和key1两个变量，同时用户在useParam节点中定义了一个与上游传递的变量名相同的变量key1，并赋值为"12"：

按照优先级规则，由于本地参数key1的优先级高于上游任务传递的参数，这里的值"12"会被最终使用，而上游节点设置的变量值会被抛弃。

五、实战示例二：SQL 节点中本地参数与全局参数、多上游参数的裁决

再用 SQL 节点解释另外两种冲突场景：本地参数 vs 全局参数、多上游同名参数 vs 完成时间。

节点use_create与上游节点createParam1、createParam2的依赖关系如下：

use_create节点的定义如下：

5.1status：本地参数覆盖全局参数

status是当前节点设置的节点的自有变量（本地参数）。但用户在保存工作流时同样设置了status变量（全局参数），并赋值为 -1。那么在该 SQL 执行时，status的值取优先级更高的本地参数值2，全局变量中的值 -1 被抛弃。这印证了规则本地参数 > 全局参数。

5.2id：多上游同名参数取最早完成者

id是上游节点设置的变量，用户在节点createParam1、节点createParam2中设置了相同参数名id的参数。而节点use_create中使用了最先结束的createParam1的值——即按照"上游任务完成时间排序，选择完成时间最早的上游任务对应的参数"这一规则执行。

六、源码视角：优先级规则在代码中如何落地

参数优先级的实现贯穿任务参数装配的全过程，可以在 AbstractParameters.java 中看到关键支撑：

• 本地参数与 varPool 分离管理：localParams保存节点自定义参数，getLocalParametersMap()将其组织为Map<prop, Property>；varPool保存节点运行后输出的参数池，getVarPoolMap()同样按 prop 建立索引。二者通过LinkedHashMap保持定义顺序；
• IN/OUT 方向决定参数能否外传：getInputLocalParametersMap()只收集方向为 IN（或未设置方向、默认按 IN 处理）的参数用于节点内计算；getOutProperty()只过滤出方向为 OUT 的参数，并由dealOutParam()在任务输出参数taskOutputParams非空时把实际值注入 OUT 参数，最终通过VarPoolUtils.mergeVarPool(...)合并进 varPool，供下游任务读取——这正是"上游任务传递的参数"在运行时产生并流向下游的实现路径；
• 同名参数的覆盖语义由合并顺序决定：从varPool中按 prop 取出同名参数时，后 merge 的本地参数（OUT 结果）会覆盖先进入的作用域参数，与文档所述"本地参数 > 上游参数"的优先级方向一致；
• 任务输出参数来源：上游 Shell / SQL 等任务在执行日志中输出${setValue(key=value)}（或#{(key=value)}）格式内容，DolphinScheduler 捕捉该输出后写入taskOutputParams，再经由上述dealOutParam流程落地（参考 参数的引用 中对 Shell、Python、Kubernetes 等任务类型参数捕捉格式的说明）。

从源码结构可以推断，最终下发给任务节点的TaskExecutionContext中通过varPool字段（见 TaskExecutionContext.java）承载"上游传递的参数 + 节点 OUT 参数"的合并结果，任务运行时再叠加全局参数、启动参数与本地参数完成最终取值，从而在参数名冲突时体现出文档所述的整体优先级。

七、工程实践建议

结合上述规则与示例，在实际编排工作流时可遵循以下要点：

1. 参数命名做好规划：避免不同作用域使用同名参数，从源头减少冲突；确需同名覆盖时，明确利用优先级规则（如用启动参数覆盖全局参数以实现"运行期改参"）；
2. 依赖关系决定参数可见性：只有存在依赖关系的上下游之间才能传递参数，设计 DAG 时需保证传递路径上的节点连线正确；
3. 多上游同名参数以"先完成者"为准：若业务要求"以最后一个完成的上游为准"，应改用不同参数名或在下游通过自定义逻辑二次选择，不能依赖默认规则；
4. OUT 参数必须显式声明：上游节点需要在"自定义参数"中定义方向为 OUT 的变量（Shell 用echo '${setValue(key=value)}'，SQL 用查询结果列名对齐参数名，Python 用print('${setValue(key=%s)}' % value)），否则即使脚本输出了setValue内容也无法传递到下游（参考 参数的引用）；
5. 空值与完成时间是最后的裁决依据：上游同名参数全部为空时，下游取空值；存在多个非空值时，比较各上游任务实例的完成时间取最早者，排查取值异常时可结合"工作流实例→任务实例"页面核对各上游节点的完成时间与输出值。

• 任务调度
• 大数据
• 后端
• 前端