Apache DolphinScheduler HTTP 任务节点完全指南：配置、请求校验与参数传递
项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler 导读
HTTP 任务节点是 Apache DolphinScheduler 中用于发起 HTTP 请求并将其编排进工作流的通用任务类型，支持 GET、POST、PUT、DELETE 四种请求方法，并内置响应校验能力（状态码与响应体内容匹配）。通过本文，你将掌握在 DolphinScheduler 工作流中创建 HTTP 任务、配置请求地址/请求类型/请求参数/请求体/请求头与校验条件的方法，理解底层 OkHttp 执行链路与四种校验条件的判定逻辑，并学会通过 ${taskName.response} 在上下游任务之间传递 HTTP 响应结果。
概述：HTTP 任务节点能做什么
HTTP 任务节点用于执行 HTTP 类型的任务，并支持对 HTTP 请求结果进行校验等扩展功能（见 docs/docs/en/guide/task/http.md）。它是工作流中“调用外部系统接口”的标准手段，典型应用场景包括：
- 在 ETL 流程中触发外部数据平台的同步接口；
- 轮询或探测外部服务的健康状态（HTTP 探活）；
- 调用登录接口获取凭证、调用消息网关推送告警；
- 将多个外部 API 调用串联进 DAG，并把响应结果传给下游任务继续处理。
从源码结构看，该任务以独立插件形式存在，位于 dolphinscheduler-task-plugin/dolphinscheduler-task-http，通过 HttpTaskChannel（见 HttpTaskChannel.java）注册为可被工作流引擎调度的任务通道，运行时由 HttpTask 完成参数解析、请求发送与结果校验。
创建 HTTP 任务
创建 HTTP 任务与创建其他任务类型一致，操作步骤如下：
- 进入
项目管理 -> 项目名称 -> 工作流定义，点击创建工作流按钮进入 DAG 编辑页面； - 从左侧工具栏拖拽 HTTP 节点图标到画布上（拖入节点后即可编辑其配置）。
创建完成后即可进入任务参数配置界面。
任务参数详解
HTTP 任务节点的参数分两部分：通用默认参数与 HTTP 专属参数。通用默认参数（节点名称、运行标志、任务优先级、Worker 分组、失败重试次数、失败重试间隔、CPU 配额、最大内存、超时告警、延时执行时间、资源、前置任务等）请参考 DolphinScheduler 任务参数附录 中的 默认任务参数 一节，此处不再赘述。HTTP 专属参数如下：
| 参数 | 说明 |
|---|---|
| 请求地址 | HTTP 请求 URL。 |
| 请求类型 | 支持 GET、POST、PUT、DELETE。 |
| 请求参数 | 支持 Parameter（查询参数）、Body（请求体）、Headers（请求头）三类。 |
| 校验条件 | 支持默认响应码、自定义响应码、内容包含、内容不包含。 |
| 校验内容 | 当校验条件选择自定义响应码、内容包含、内容不包含时，必须填写校验内容。 |
| 自定义参数 | HTTP 部分的用户自定义参数，会替换脚本/请求中的 ${variable} 占位内容。 |
上述参数与源码中的字段一一对应。HttpParameters（见 HttpParameters.java）定义了请求地址 url、请求方法 httpRequestMethod、请求参数列表 httpRequestParams、请求体 httpRequestBody、校验条件 httpCheckCondition 与校验内容 condition；其中 checkParameters() 强制要求 URL 非空、请求方法非空且连接超时时间 connectTimeout 大于 0，否则 HttpTask.init() 会直接抛出 "http task params is not valid" 异常。
请求类型（HTTP Method）
请求类型由枚举 HttpRequestMethod（见 HttpRequestMethod.java）限定，仅支持四种：GET、POST、PUT、DELETE。HttpTask.sendRequest() 会根据所选方法分派到对应的发送逻辑：
- GET：
OkHttpUtils.get(url, headers, requestParams, connectTimeout, ...)，请求参数以查询字符串形式拼接； - POST：
OkHttpUtils.post(url, headers, null, requestBody, ...)，请求体以 JSON 对象形式提交； - PUT：
OkHttpUtils.put(url, headers, requestBody, ...)； - DELETE：
OkHttpUtils.delete(url, headers, ...)。
完整的调用链见 HttpTask.java。需要特别说明的是：对于 GET/DELETE 类请求使用 Parameter 类型参数，对于 POST/PUT 类请求使用 Body 类型参数，这与 HTTP 协议语义一致。所有方法都基于 OkHttp 实现（dolphinscheduler-common 中的 OkHttpUtils），并统一以三个 connectTimeout 分别作为连接、写入、读取的超时时间。
请求参数、请求体与请求头
请求参数（httpParams）在界面上体现为 Parameter（GET/DELETE 的查询参数）、Headers（请求头）与 Body（POST/PUT 的请求体）三类，底层由 HttpProperty（见 HttpProperty.java）表示，每条记录包含属性名 prop、类型 httpParametersType（HttpParametersType 枚举，见 HttpParametersType.java，取值 PARAMETER 或 HEADERS）和值 value。
请求头的 Content-Type 有特殊处理逻辑：HttpTask.getContentType() 会从 Headers 中提取 Content-Type，若未配置则默认使用 application/json；OkHttpRequestHeaderContentType（见 OkHttpRequestHeaderContentType.java）定义了两种受支持的内容类型：
application/json（默认，未配置 Content-Type 时自动采用）；application/x-www-form-urlencoded。
因此文档中"目前仅支持 application/json、application/x-www-form-urlencoded 格式，若输入其他格式则默认使用 application/json"的说明与源码行为一致。同时 getHeaders() 会过滤掉 Content-Type 本身，避免其作为普通请求头重复发送。
请求体（httpRequestBody）要求必须是合法的 JSON 对象：getRequestBody() 会对请求体做变量占位符替换后解析为 JsonNode，若解析失败返回 null，若解析成功但并非 JSON 对象，则抛出 "Http request body should be a json object" 异常（见 HttpTask.java）。
自定义参数与内置参数
自定义参数指 HTTP 部分的用户自定义参数，运行时会替换请求中的 ${variable} 占位内容。从源码实现看，getHeaders()、getRequestParams()、getRequestBody() 三个方法在处理前都会调用 ParameterUtils.convertParameterPlaceholders(...) 对参数名与参数值进行占位符替换（见 HttpTask.java）。因此 URL、请求头、查询参数、请求体中的任意位置都可以使用 ${变量名} 引用工作流全局参数、上游任务输出参数等内置参数，实现完全动态化的请求构造。
校验条件与校验内容
HTTP 任务节点内置响应校验能力，对应枚举 HttpCheckCondition（见 HttpCheckCondition.java），共四种取值：
| 校验条件 | 校验规则 |
|---|---|
| 默认响应码 | STATUS_CODE_DEFAULT：响应状态码必须为 200（常量 RESPONSE_CODE_SUCCESS，见 HttpConstants.java）。 |
| 自定义响应码 | STATUS_CODE_CUSTOM：响应状态码必须等于校验内容中填写的整数值。 |
| 内容包含 | BODY_CONTAINS：响应体非空且必须包含校验内容（模糊匹配）。 |
| 内容不包含 | BODY_NOT_CONTAINS：响应体非空且必须不包含校验内容（模糊匹配）。 |
当校验条件为自定义响应码、内容包含、内容不包含时，校验内容为必填项；且文档明确说明内容校验采用模糊匹配（子串包含语义）。四种条件的判定逻辑集中在 HttpTask.validateResponse()（见 HttpTask.java）：
- 校验失败时打印包含 URL、状态码、校验条件与响应体的错误日志，并将任务退出码置为
EXIT_CODE_FAILURE； - 校验通过则将退出码置为
EXIT_CODE_SUCCESS； - 若校验条件枚举值超出预期，则抛出
TaskException（"http check condition %s not supported"）。
需要注意的是，无论校验结果如何，HTTP 请求本身都已发出；校验只决定任务实例在 DAG 中是成功还是失败，进而影响下游分支。这一点与测试用例 HttpTaskTest.java 的行为完全一致：该测试使用 MockWebServer 构造模拟响应，覆盖了四种请求方法在默认响应码 200 下的成功场景（testHandleCheckCodeDefaultSuccess）、非 200 状态码的失败场景（testHandleCheckCodeDefaultError）、自定义响应码场景（testHandleCheckCodeCustom）等，可在编写任务后据此理解校验边界。
任务输出参数：response
HTTP 任务执行完成后会产生一个名为 response 的输出参数，类型为 VARCHAR，值为 HTTP 请求的返回结果（JSON 序列化后的完整 OkHttpResponse，包含响应体与状态码）。下游任务可通过 ${taskName.response} 引用该输出参数。例如任务 task1 为 HTTP 任务，则其下游任务可直接使用 ${task1.response} 获取 task1 的响应内容。
从源码实现看，addDefaultOutput()（见 HttpTask.java）在每次请求发送后，以 任务名.response 为属性名、VARCHAR 为数据类型、响应 JSON 字符串为值写入参数池（varPool），再通过 taskExecutionContext.setVarPool(...) 暴露给下游。结合上文的自定义参数机制，这就形成了完整的参数闭环：上游 HTTP 任务产出 response → 下游任务以 ${taskName.response} 引用 → 引用位置经过占位符替换后成为实际请求/命令内容。
实战示例：用 POST 调用登录接口
HTTP 定义了与服务器交互的不同方法，最基本的是 GET、POST、PUT、DELETE。以下用 HTTP 任务节点演示通过 POST 向系统登录页面发送请求以提交数据的完整配置（所有参数均可替换为内置参数）。
主要配置参数如下：
- URL：访问目标资源的地址，此处填写系统登录页面的地址。
- 请求类型：GET、POST、PUT、DELETE。
- Headers（请求头）：请求头信息，目前仅支持
application/json、application/x-www-form-urlencoded两种格式；若填写其他格式，将默认使用application/json。 - HTTP Parameters（请求参数）：GET、DELETE 请求的查询参数。
- HTTP Body（请求体）：POST、PUT 请求的请求体参数。
- 校验条件：默认响应码 200、自定义响应码、内容包含、内容不包含。
- 校验内容：当校验条件为自定义响应码、内容包含、内容不包含时必填，且为模糊匹配。
上图即 HTTP 任务节点的配置界面示例。以一次 POST 登录请求为例，可按下述思路配置：
- URL：填写登录接口地址，如
http://<host>:<port>/login； - 请求类型：选择
POST； - Headers：添加
Content-Type，值选择application/json（或使用默认的 JSON 格式）； - HTTP Body：填写 JSON 请求体，如
{"username": "${username}", "password": "${password}"}，其中的变量在工作流启动或运行参数中注入； - 校验条件：若登录成功接口返回
200及特定响应体，可选择"内容包含"并在校验内容中填写成功标志（如success）；若接口约定返回201等自定义状态码，则选择"自定义响应码"并填写对应值； - 配置完成后确认保存，该节点执行成功与否即由上述校验条件决定，响应内容可通过
${taskName.response}供下游任务使用。
小结
HTTP 任务节点将外部 HTTP 接口调用纳入工作流编排体系，核心能力可概括为四点：四种请求方法的完整支持、JSON 请求体与请求头/查询参数的灵活配置、基于状态码与响应体内容的四类响应校验、以及 response 输出参数与 ${taskName.response} / ${variable} 占位符构成的双向参数传递链路。理解 HttpTask.java 中 checkParameters、sendRequest、validateResponse、addDefaultOutput 四个关键环节，即可在编排复杂 API 调用工作流时准确定位问题并发挥该节点的全部能力。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
