Apache DolphinScheduler 参数上下文（Parameter Context）：跨任务参数传递完整指南

Apache DolphinScheduler 参数上下文Parameter Context跨任务参数传递完整指南【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/gh_mirrors/do/dolphinschedulerApache DolphinScheduler 的参数上下文Parameter Context机制允许参数在任务之间相互引用包括局部参数引用全局参数以及上下游任务之间的参数传递。本文以官方文档 docs/docs/en/guide/parameter/context.md 为主体结合仓库源码系统讲解参数引用方式、setValue语法、六种支持参数传递的任务类型、参数优先级规则以及 Shell / SQL / Python / SubProcess / Kubernetes 五类任务的完整实战示例。读完本文你将能够独立设计出「上游计算、下游消费」的参数化工作流。说明本文配套的界面截图均位于 docs/img/new_ui/dev/parameter 目录可直接点击图片文件名查看原图。一、什么是参数上下文DolphinScheduler 中的参数体系共包含五种来源它们的定义位置各不相同参数类型定义位置参考文档项目级参数项目管理页面project-parameter.md全局参数工作流定义页面global.md启动参数工作流启动页面startup-parameter.md参数上下文上游任务节点传递本文局部参数任务节点的「自定义参数」local.md参数上下文Parameter Context特指由上游任务节点通过日志输出等方式传递下来的参数集合。它打通了任务与任务之间的数据通道让一个任务的计算结果可以成为下游任务的输入从而实现「任务间引用」。当不同来源的参数出现同名冲突时DolphinScheduler 按如下优先级从高到低取值启动参数 局部参数 参数上下文 全局参数 项目级参数该优先级规则在 priority.md 中有完整定义与示例验证。局部任务引用全局参数使用前提是已在工作流定义页定义好 全局参数。引用方式与 局部参数 的用法类似区别在于参数的 value 需要配置为全局参数的 key运行时 DolphinScheduler 会自动完成替换。参数传递的约束条件当前仅支持单向传递上游 → 下游不支持反向传递若节点之间没有依赖关系局部参数无法向上游传递只有存在依赖边时下游节点才能拿到上游的输出下游节点若定义了与上游参数同名的参数会覆盖上游传来的值。二、支持参数传递的任务类型根据官方文档以下六类任务支持参数上下文传递任务类型说明Shell通过echo ${setValue(...)}输出参数SQL通过查询结果列输出参数Procedure存储过程输出参数Python通过print(${setValue(...)})输出参数SubProcess子流程内定义 OUT 参数向上传递给父流程下游任务Kubernetes通过通用日志格式${(keyvalue)}或#{(keyvalue)}输出参数在定义上游节点时若需要把节点结果传给有依赖关系的下游节点需在节点设置的自定义参数Custom Parameters中添加一个OUT方向的参数。对于SubProcess 节点无需在节点设置中添加参数而是需要在子工作流定义中设置OUT方向参数。从源码结构看参数上下文的数据载体被称为varPool变量池。每个任务节点的 OUT 参数最终都会被序列化合并进 varPool供下游节点消费。三、核心语法${setValue(keyvalue)}参数传递的底层原理是任务运行时将结果以特定格式写入日志DolphinScheduler 捕获日志中的格式串并解析出 key-value 对写入参数上下文。输出语句的标准格式为${setValue(keyvalue)}key必须与对应自定义参数的prop参数名一致value为该参数的值外层建议使用单引号避免 Shell 展开。源码级解析原理日志解析逻辑位于 TaskOutputParameterParser.java通过logLine.indexOf(${setValue()与logLine.indexOf(#{setValue()定位变量池起始位置支持跨行解析若一行内未找到结束符)}会将后续行持续追加进当前参数表达式默认单个参数最多 1024 行超出则跳过并告警最终调用parseOutputParam校验格式必须以${setValue(或#{setValue(开头、以)}结尾并按第一个拆分为 key 与 value例如outputParam.substring(11, outputParam.length() - 2)截取表达式主体再split(, 2)得到键值对。因此在实际使用中必须严格保证格式完整${setValue(与)}缺一不可否则该参数不会被捕获。两种前缀的适用场景前缀典型场景注意点${setValue(keyvalue)}Shell 任务中输出常量变量值含特殊字符时建议配合repr()或转义#{setValue(keyvalue)}引用变量动态拼装值如 bash 变量使用变量时外层必须用双引号对应实现见 TaskOutputParameterParser.java源码依次尝试匹配${setValue(与#{setValue(两种前缀。OUT 方向参数的合并规则所有 OUT 参数会汇入 varPool。合并逻辑位于 VarPoolUtils.java只有Direct.OUT的参数才会被保留进结果 varPool非 OUT 方向会被跳过并打印提示日志当不同 varPool 中出现相同prop且方向相同时后合并进来的值生效。这解释了为什么「只有 OUT 方向才会被定义为可输出变量」——例如文档示例中value参数方向为 IN值 66 只在 Node_A 自身可见不会被传递到下游。四、完整示例Shell 传参 → SQL 消费本节复现官方文档的经典链路Node_AShell产出参数 → Node_BShell验证 → Node_mysqlSQL消费查询。1. 创建 SHELL 任务并设置参数创建 Node_A 任务在自定义参数中添加两个参数并写入如下脚本echo ${setValue(output1)}参数说明参数名方向值/赋值方式说明valueIN66仅当前节点可见不参与传递outputOUT脚本${setValue(output1)}赋值传递给下游节点当 SHELL 节点运行时日志中一旦检测到${setValue(output1)}格式就会把 1 赋给output下游节点可直接使用该变量。运行后可在【工作流实例】页面找到对应节点实例查看该变量的值。界面配置截图见 context_parameter01.png。创建 Node_B 任务主要用于测试并输出上游 Node_A 传递过来的参数配置截图见 context_parameter02.png。2. 创建 SQL 任务并使用参数当 SHELL 任务完成后可在 SQL 任务中把上游传递的output作为查询条件。同时SQL 查询结果的列可以继续作为 OUT 参数输出例如将查询出的id重命名为ID并输出SELECT id AS ID FROM your_table WHERE id ${output};界面配置截图见 context_parameter03.png。SQL 节点输出参数的规则实现见 SqlParameters.java 的dealOutParam方法查询结果只有一行、一个或多个字段prop名称需与字段名一致数据类型选择除LIST之外的任意结构参数按 SQL 查询结果中的同名列赋值查询结果有多行、一个或多个字段prop名称需与字段名一致数据类型选择LIST查询结果会被转换为LISTVARCHAR后再转成 JSON 作为参数值。3. 保存工作流并设置全局参数点击保存工作流图标在【设置全局】中设置全局参数output和value配置截图见 context_parameter04.png。4. 查看运行结果工作流创建完成后上线运行并查看结果Node_A 运行结果context_log01.pngNode_B 运行结果context_log02.pngNode_mysql 运行结果context_log03.png结果解读虽然 Node_A 的脚本里output被赋值为 1但日志中仍显示全局参数初始值 100。根据参数优先级启动参数 局部参数 参数上下文 全局参数 项目级参数Node_B 中output的值为1——证明output参数确实按预期在工作流中传递Node_mysql 也使用该值完成了查询操作。而value的值 66 只出现在 Node_A 中原因是其方向为IN只有 OUT 方向的参数才会被定义为可输出变量。五、Python 任务向下游传参在 Python 任务中使用print(${setValue(key%s)} % value)DolphinScheduler 会从输出中捕获${setValue(keyvalue}格式并解析参数传递给下游界面配置见 python_context_param.png。特殊注意事项当变量值包含换行符\n时如value hello \n world需要特殊处理。直接print会导致参数无法传递给后续流程应使用repr()print(${setValue(key%s)} % repr(value))这样\n会被转义为字面量而非真实换行从而保证日志解析器能够完整捕获参数。六、SubProcess 任务向下游传参在子工作流定义中定义OUT方向参数作为输出参数这些参数可传递给父工作流中 SubProcess 节点的下游任务。操作步骤在子工作流中定义输出创建 A 任务在自定义参数中添加var1、var2参数并编写脚本见 context-subprocess01.png保存子工作流并设置全局参数保存subprocess_example1工作流设置全局参数var1见 context-subprocess02.png在父工作流中使用子流程节点新建工作流添加 SubProcess 任务并选择subprocess_example1作为子节点见 context-subprocess03.png创建下游 Shell 任务作为 sub_process 任务的下游编写脚本输出参数见 context-subprocess04.png运行并查看结果下游任务成功输出了var1见 context-subprocess05.png。结果解读虽然 A 任务输出了var1、var2两个参数但子工作流定义中只声明了OUT参数var1因此最终只有var1被传递到下游——再次验证「只有 OUT 方向才会输出为变量」。这与 全局参数文档 中的定义一致工作流定义页配置的OUT方向参数即为该工作流的输出参数会传递给父工作流中对应 SubProcess 任务的下游任务。七、Kubernetes 任务向下游传参Kubernetes 任务中不同编程语言可能使用不同的日志框架为兼容这些框架DolphinScheduler 提供了通用日志数据格式${(keyvalue)} #{(keyvalue)}用户可在应用的终端日志中按此格式输出数据其中key为对应参数的 propvalue为参数值。DolphinScheduler 会从输出日志中捕获${(keyvalue)}或#{(keyvalue)}并解析传递到下游示例见 k8s_context_param.png。特别提醒并非总能采集到 Pod 日志。如果用户重定向了日志输出流DolphinScheduler 将无法采集日志用于解析此时输出参数同样无法使用。八、参数覆盖与同名冲突的处理在实际工作流设计中同名参数会频繁出现需要遵循以下两条规则详见 priority.md规则一多来源同名参数的取值优先级启动参数 局部参数 参数上下文 全局参数 项目级参数。例如某节点自身定义了局部参数status值为 2同时工作流全局参数也有status值为 -1SQL 执行时取局部参数 2全局参数值被丢弃。规则二多个上游节点传递同名参数时的取值下游节点优先使用非空值的参数若多个上游均传了非空值则取最早完成的上游任务的值。注意当上游节点之间不存在依赖关系时下游节点无法获取其参数例如无依赖的noUseParam节点传参无法被下游消费这一点同样适用于所有任务类型。九、补充技巧结合setValue的三种输出姿势结合 local.md 的说明setValue有更灵活的用法可帮助你在实战中按需选择1. 简单常量输出Shellecho ${setValue(set_val123)}2. 引用自定义参数动态输出Shell使用变量时必须用双引号echo #{setValue(set_val_param${val})}3. 引用 bash 变量输出Shelllines_num$(wget url -q -O - | wc -l | xargs) echo #{setValue(set_val_var${lines_num})}三种方式都需要配合在自定义参数中声明对应的OUT参数下游用echo ${set_val}即可取值。十、最佳实践与排查建议命名一致性setValue中的 key 必须与自定义参数的prop完全一致SQL 输出的 prop 必须与结果集列名一致否则参数无法匹配格式完整性${setValue(必须以)}收尾避免被日志解析器跳过见 TaskOutputParameterParser.java 的格式校验方向要设对只有OUT方向的参数才会进入 varPool 被下游消费IN 参数仅在当前节点可见见 VarPoolUtils.java依赖关系决定可见性下游节点必须与上游存在依赖边才能收到参数换行符处理Python 传参时值内含\n必须用repr()转义日志采集前提Kubernetes 任务需确保日志输出流未被重定向否则无法采集参数。通过合理运用参数上下文你可以把复杂的多任务编排拆解为「上游产出 → 下游消费」的清晰数据链路让 Apache DolphinScheduler 的工作流真正具备跨任务的参数化编排能力。【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/gh_mirrors/do/dolphinscheduler创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考