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 共有以下六种参数类型参数类型定义位置作用域内置参数系统内置系统级项目级参数项目管理页面项目下所有工作流全局参数工作流定义页面整个工作流启动参数工作流启动运行页面整个工作流仅当次运行参数上下文上游任务节点传递下游任务本地参数任务定义页面单个任务节点启动参数的核心特征是运行期注入、按次生效它不写入工作流定义而是在你点击运行并填写参数的那一刻生效随后被合并进该工作流实例的全局参数中对整个工作流的所有任务节点都有效。注意官方文档明确说明启动参数与全局参数的区别在于配置入口——全局参数在工作流定义页面配置写入定义启动参数在工作流启动页面配置仅对本次启动有效。这使同一份工作流定义可以在不同批次运行时传入不同的业务日期、表名、路径等变量无需修改定义本身。二、配置方式启动页面的三步操作启动参数的配置入口在工作流的启动运行弹窗中。操作步骤如下进入工作流定义页面点击目标工作流右侧的运行按钮打开启动配置弹窗在弹窗的启动参数Startup Parameter区域点击下方的号新增一行参数依次填写参数名称key、参数值value并选择合适的参数值类型点击确定保存。工作流会将这些参数加入全局参数中随后本次运行的所有任务节点都可以通过${key}的形式引用。从前端源码看启动参数的每一行由 4 个字段构成见 start-modal.tsxprop参数名称即 key必填不可为空direct方向IN或OUT新建行默认INtype值类型下拉选择新建行默认VARCHARvalue参数值该参数在本次运行中的取值。其中参数名称非空与参数名称不重复这两条规则前端在表单校验里已经实现use-form.ts中的startParamsList校验器会遍历每一行检查prop是否为空、是否存在重复 key对应源码见 use-form.ts。提交时启动参数列表会以 JSON 字符串形式序列化后随启动请求一起发送见 use-modal.ts。三、参数值类型详解配置启动参数时需要为每个参数选择数据类型。前端下拉框提供 11 种可选类型见 data_type.ts与后端枚举一一对应类型说明后端枚举定义VARCHAR字符串默认类型0INTEGER整数1LONG长整型2FLOAT浮点数3DOUBLE双精度浮点数4DATE日期格式YYYY-MM-DD5TIME时间格式HH:MM:SS6TIMESTAMP时间戳7BOOLEAN布尔值8LIST字符串列表LISTVARCHAR9FILE文件参数10后端类型定义见 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方法它优先按MapString,String形式解析逐项构造Property方向IN、类型VARCHAR解析失败时再尝试按Property列表的 JSON 数组格式解析。转换后的启动参数列表最终进入工作流命令Command作为该次运行实例的全局参数随任务分发到执行端。4. 任务执行期替换任务脚本中的${dt}在任务执行时由参数引擎替换为实际值。这一点从参数优先级文档可以得到佐证当多个来源定义了同名参数时DolphinScheduler 有明确的取舍规则见下一节。六、优先级规则同名参数谁说了算由于全局参数、本地参数、启动参数等可能定义了同名的 keyDolphinScheduler 必须规定优先级。官方文档 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}可混合使用内置参数在运行时按调度时间自动求值详见 内置参数。常见使用建议命名唯一启动参数 key 尽量与工作流定义中的全局参数、节点本地参数保持语义一致但避免冲突以免触发优先级规则造成值不符合预期类型匹配日期类参数建议直接用VARCHAR传yyyy-MM-dd或yyyyMMdd格式字符串脚本内自由格式化仅当需要参与数值运算或与数据库字段类型严格对应时才选择INTEGER、DOUBLE、DATE等类型补数与重跑使用运行页面的时间范围或补数功能时启动参数会一并作用于补出的每个工作流实例重复运行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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考