Apache DolphinScheduler 启动参数（Startup Parameter）完全指南：作用域、配置流程与源码原理

Apache DolphinScheduler 启动参数（Startup Parameter）完全指南：作用域、配置流程与源码原理

【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler

启动参数（Startup Parameter）是 Apache DolphinScheduler 中一类作用于整个工作流所有任务节点的运行时参数，它在工作流启动（运行）页面一次性配置，并在该次运行中作为全局参数注入所有任务。本文基于官方文档 startup-parameter.md 展开，结合前端启动弹窗、API 层参数校验与转换等源码实现，完整讲解启动参数的作用域、配置方式、参数类型、运行样例与参数优先级规则，帮助你掌握"同一份工作流定义，不同次运行传不同参数"的标准做法。

一、什么是启动参数：作用域与定位

启动参数是 DolphinScheduler 六类参数体系中的一员。按官方文档 Parameter Priority 的定义，DolphinScheduler 共有以下六种参数类型：

启动参数的核心特征是运行期注入、按次生效：它不写入工作流定义，而是在你点击"运行"并填写参数的那一刻生效，随后被合并进该工作流实例的全局参数中，对整个工作流的所有任务节点都有效。

注意：官方文档明确说明，启动参数与全局参数的区别在于配置入口——全局参数在"工作流定义页面"配置，写入定义；启动参数在"工作流启动页面"配置，仅对本次启动有效。这使同一份工作流定义可以在不同批次运行时传入不同的业务日期、表名、路径等变量，无需修改定义本身。

二、配置方式：启动页面的三步操作

启动参数的配置入口在工作流的启动（运行）弹窗中。操作步骤如下：

1. 进入工作流定义页面，点击目标工作流右侧的"运行"按钮，打开启动配置弹窗；
2. 在弹窗的启动参数（Startup Parameter）区域，点击下方的"+"号新增一行参数；
3. 依次填写参数名称（key）、参数值（value），并选择合适的参数值类型，点击确定保存。

工作流会将这些参数加入全局参数中，随后本次运行的所有任务节点都可以通过${key}的形式引用。

从前端源码看，启动参数的每一行由 4 个字段构成，见 start-modal.tsx：

• prop（参数名称）：即 key，必填，不可为空；
• direct（方向）：IN或OUT，新建行默认IN；
• type（值类型）：下拉选择，新建行默认VARCHAR；
• value（参数值）：该参数在本次运行中的取值。

其中"参数名称非空"与"参数名称不重复"这两条规则，前端在表单校验里已经实现：use-form.ts中的startParamsList校验器会遍历每一行检查prop是否为空、是否存在重复 key，对应源码见 use-form.ts。提交时，启动参数列表会以 JSON 字符串形式序列化后随启动请求一起发送（见 use-modal.ts）。

三、参数值类型详解

配置启动参数时，需要为每个参数选择数据类型。前端下拉框提供 11 种可选类型，见 data_type.ts，与后端枚举一一对应：

后端类型定义见 DataType.java，前端的DATA_TYPES_MAP与后端枚举顺序完全对齐。多数场景（如传日期字符串、路径）直接使用默认的VARCHAR即可。

四、完整实例：用启动参数打印不同日期

以下样例来自官方文档，演示如何通过启动参数让同一个 Shell 任务输出不同天的日期。整个流程共五步，对应五张官方截图：

步骤 1：创建 Shell 任务

新建工作流，添加一个 Shell 任务，在脚本内容中输入：

echo ${dt}

这里dt就是要通过启动参数声明的全局参数，任务脚本以${dt}引用它。

步骤 2：保存工作流，在启动页面设置启动参数

保存并上线工作流后，点击"运行"，在启动页面的"启动参数"区域新增一行：参数名填dt，参数值填某个具体日期（如2022-08-26），类型选VARCHAR，确定后启动。

注：这里定义的dt参数可以被其它任一节点的局部参数引用，也可以被任务脚本直接以${dt}使用。

步骤 3：在任务实例中查看执行结果

进入"任务实例"页面，点击该 Shell 任务实例的"查看日志"，可以看到脚本实际打印出的日期即为启动参数中填写的值，说明参数注入成功。

步骤 4：修改启动参数，再次执行

回到工作流定义页面再次点击"运行"，这次将启动参数dt的值改为另一个日期（如2022-08-27），再次启动。

步骤 5：再次查看执行结果

在新的任务实例日志中，可以看到脚本输出了与第一次运行不同的日期。由此验证：同一份工作流定义、同一个任务，仅通过修改启动参数即可实现不同批次运行输出不同日期——这正是启动参数在"按天/按批次重跑、补数据"等场景中最典型的用法。

五、源码级原理：启动参数如何从界面流到任务执行

启动参数从配置到生效的完整链路，可以从前端到后端逐层追溯：

1. 前端组装请求

在 use-modal.ts 中，handleStartDefinition会把启动参数列表序列化为 JSON 字符串，放入params.startParams，调用startWorkflowInstance发送启动请求；启动请求的 REST 接口由 ExecutorController.java 接收，参数名为startParams。

2. API 层校验

后端通过 StartParamListValidator.java 对启动参数列表做合法性校验：参数 key 不能为空，且不能重复；违反任一规则都会抛出IllegalArgumentException。该校验器被BackfillWorkflowDTOValidator和TriggerWorkflowDTOValidator等校验链复用，覆盖了手动启动与补数（backfill）两类入口。

3. 转换与合并

启动参数在请求转换阶段被解析为Property列表，见 PropertyUtils.java 的startParamsTransformPropertyList方法：它优先按Map<String,String>形式解析，逐项构造Property（方向IN、类型VARCHAR）；解析失败时再尝试按Property列表的 JSON 数组格式解析。转换后的启动参数列表最终进入工作流命令（Command），作为该次运行实例的全局参数，随任务分发到执行端。

4. 任务执行期替换

任务脚本中的${dt}在任务执行时由参数引擎替换为实际值。这一点从参数优先级文档可以得到佐证：当多个来源定义了同名参数时，DolphinScheduler 有明确的取舍规则（见下一节）。

六、优先级规则：同名参数谁说了算

由于全局参数、本地参数、启动参数等可能定义了同名的 key，DolphinScheduler 必须规定优先级。官方文档 Parameter Priority 给出的优先级从高到低为：

Parameter Context（参数上下文） > Startup Parameter（启动参数） > Local Parameter（本地参数） > Global Parameter（全局参数） > Project-level Parameter（项目级参数） > Built-in Parameter（内置参数）

结合本文主题，这意味着：

• 如果工作流定义里已有同名全局参数，而你在启动页面又设置了同名启动参数，本次运行以启动参数为准；
• 如果某个任务节点定义了同名本地参数，启动参数仍然优先于它；
• 只有上游任务通过 OUT 方向传递下来的参数上下文才能覆盖启动参数。

另外，当多个上游任务向下游传递了同名参数时，下游节点会优先采用非空值；若多个非空值并存，则取完成时间最晚的上游任务传出的值。完整的多级示例（createParam/useParam 节点、项目级参数、全局参数、启动参数、参数上下文叠加的场景）见 priority.md，可作为理解同名参数取舍的实战案例。

七、与其他参数类型的协同与常见问题

与本地参数、参数上下文的配合

• 启动参数对整个工作流所有节点有效，任何节点的脚本与本地参数都可以引用它（见官方文档 startup-parameter.md 的说明）；
• 若需要把某个节点计算结果传给下游节点，则应使用 本地参数 的OUT方向 +setValue语法，或直接参考 参数上下文 中的 Shell / SQL / Python / SubWorkflow / Kubernetes / Zeppelin 传递示例；
• 启动参数与内置参数（如${system.biz.date}）可混合使用，内置参数在运行时按调度时间自动求值，详见 内置参数。

常见使用建议

1. 命名唯一：启动参数 key 尽量与工作流定义中的全局参数、节点本地参数保持语义一致但避免冲突，以免触发优先级规则造成"值不符合预期"；
2. 类型匹配：日期类参数建议直接用VARCHAR传yyyy-MM-dd或yyyyMMdd格式字符串，脚本内自由格式化；仅当需要参与数值运算或与数据库字段类型严格对应时才选择INTEGER、DOUBLE、DATE等类型；
3. 补数与重跑：使用"运行"页面的时间范围或补数功能时，启动参数会一并作用于补出的每个工作流实例；重复运行（REPEAT_RUNNING）场景下，首次启动时指定的启动参数同样会被保留使用（见 ExecutorServiceImpl.java 中"get the startParams user specified at the first starting while repeat running is needed"的注释）。

八、小结

启动参数是 DolphinScheduler 在"工作流启动时刻"提供的参数注入能力：它作用于整个工作流的所有任务节点、仅对当次运行生效，配置只需在启动页面完成"加号 + key + value + type"四个动作。结合本文的源码分析可以看到，前端启动弹窗负责参数行管理与基础校验，API 层的 StartParamListValidator 保证 key 非空且唯一，PropertyUtils.startParamsTransformPropertyList 负责转换为统一的Property模型进入命令与全局参数。理解这条链路以及"参数上下文 > 启动参数 > 本地参数 > 全局参数 > 项目级参数 > 内置参数"的优先级，就能在复杂工作流中精准控制每次运行的参数取值。

【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler