企业官网建设流程全解析

Camunda External Task Client (Java) 实战指南：远程 Service Task 的抓取、锁定与任务处理

【免费下载链接】camunda-bpm-platformCamunda 7 CE is End of Life (EoL). Please check out Camunda 8 instead (https://github.com/camunda/camunda) or read about Camunda 7 Enterprise End of Life (https://camunda.com/blog/2025/02/camunda-7-enterprise-end-of-life-extension/) – Camunda 7 CE was a flexible framework for workflow and decision automation using BPMN and DMN.项目地址: https://gitcode.com/GitHub_Trending/ca/camunda-bpm-platform

导读

本文以当前仓库clients/java/README.md为骨架，结合camunda-external-task-client模块的源码、集成测试与pom.xml，系统讲解如何用 Java 客户端将 Camunda Platform 7 工作流中的 Service Task 以「外部任务（External Task）」的形式交给独立的 Worker 进程处理。读完本文，你将掌握客户端的 Maven 引入方式、ExternalTaskClientBuilder与TopicSubscriptionBuilder两套流式配置 API 的全部参数、ExternalTaskService的任务操作（完成、报错、报 BPMN 错误、延长锁、解锁、设置变量），以及原始类型与对象类型流程变量的序列化共享机制，并能直接照搬示例接入自己的业务系统。

说明：Camunda 7 CE（Community Edition）已进入 EoL 阶段，本仓库clients/java/client/pom.xml中亦注明 7.24.0 是发布到 Maven Central 的最后一个社区版。本文内容适用于仓库当前版本（7.24.0-SNAPSHOT），请结合自身许可与运维策略使用。

一、什么是 External Task Client：把 Service Task 搬到进程外

在传统工作流引擎中，Service Task 通常由引擎内部的 JavaDelegate 或表达式直接执行，这意味着业务代码必须与引擎部署在同一个进程里。Camunda 的外部任务（External Task）模式则反其道而行之：BPMN 中的 Service Task 只声明一个camunda:topic，引擎本身不做任何业务计算，而是把任务「出借」给外部 Worker。

clients/java模块正是官方提供的 Java 版外部任务客户端，它允许你为工作流设置远程 Service Task。整体交互模型是经典的Fetch & Lock：

1. Worker 通过客户端周期性向引擎 REST API 发起fetch-and-lock请求，按topic领取任务；
2. 引擎将符合条件的任务锁定给该 Worker（锁定期间其他 Worker 无法领取），并把任务上下文（变量、流程实例信息等）返回给客户端；
3. Worker 执行业务逻辑，然后通过complete完成任务，或通过handleFailure/handleBpmnError反馈失败与业务错误；
4. 任务完成（或失败处理）后，流程实例在引擎侧继续推进。

仓库入口文档位于 clients/java/README.md，客户端本体在 clients/java/client 目录，其中src/main/java/org/camunda/bpm/client/是全部核心实现，src/it/java/org/camunda/bpm/client/下是与真实引擎联调的集成测试。

特性清单（Features）

根据 README，该客户端提供如下核心能力，后续章节会逐一结合源码展开：

• Complete External Tasks—— 完成任务（ExternalTaskService.complete(...)）；
• Extend the lock duration of External Tasks—— 延长任务锁定时长（extendLock(...)）；
• Unlock External Tasks—— 主动解锁，释放任务供其他 Worker 领取（unlock(...)）；
• Report BPMN errors as well as failures—— 上报 BPMN 错误（handleBpmnError(...)）与执行失败（handleFailure(...)）；
• Share primitive and object typed process variables with the Workflow Engine—— 与引擎共享基本类型与对象类型的流程变量（ClientValues与ValueMapper体系）。

若你使用 Spring Boot

README 开头特别提示：若你使用的是 Spring Boot 场景，应转向 Spring Boot External Task Client（仓库内对应目录为 spring-boot-starter/starter-client，内含spring与spring-boot两个子模块及独立 README）。本文聚焦纯 Java 版客户端。

二、环境准备（Prerequisites）

• Java：使用所对应 Camunda Platform 7 版本支持的 JDK 版本（当前仓库为 7.24.x 系列）；
• Camunda Platform 7：客户端通过 REST API 与引擎通信，因此需要一个运行中的 Camunda Platform 7 引擎实例（含 REST API 部署）；
• 网络可达：Worker 所在进程需能访问引擎 REST API 的baseUrl。

三、Maven 坐标与依赖引入

在项目的pom.xml中加入如下依赖（README 原样给出的坐标）：

<dependency> <groupId>org.camunda.bpm</groupId> <artifactId>camunda-external-task-client</artifactId> <version>${version}</version> </dependency>

其中${version}需替换为实际使用的版本（当前仓库对应版本为7.24.0-SNAPSHOT，见 clients/java/client/pom.xml 的<version>与<parent>声明）。

从该pom.xml的依赖声明可以看到客户端的底层技术栈与直接依赖：

测试与集成测试阶段还会用到camunda-bpmn-model（构造 BPMN 模型）、camunda-spin-dataformat-all、assertj-core、junit等，但它们不是运行期必需依赖。

四、客户端配置：ExternalTaskClientBuilder 全参数详解

客户端通过ExternalTaskClient.create()返回流式构建器ExternalTaskClientBuilder（接口定义见 ExternalTaskClientBuilder.java，默认实现见 ExternalTaskClientBuilderImpl.java）。该构建器的 JavaDoc 中明确写着：“A fluent builder to configure the Camunda client”。

最小可用示例：

ExternalTaskClient client = ExternalTaskClient.create() .baseUrl("http://localhost:8080/engine-rest") // 必填：引擎 REST API 地址 .workerId("my-worker") // 可选：自定义 Worker ID .maxTasks(10) // 可选：单次请求最多抓取任务数 .build();

4.1 全部配置项一览

下表综合接口 JavaDoc 与ExternalTaskClientBuilderImpl构造函数中的默认值（见 ExternalTaskClientBuilderImpl.java），全部配置项均可链式调用：

4.2 build() 的校验规则

build()在以下情况下会抛出ExternalTaskClientException（见 ExternalTaskClientBuilder.java 的 JavaDoc）：

• baseUrl为null或空字符串；
• 无法获取主机名（自动生成 workerId 失败）；
• maxTasks不大于 0；
• asyncResponseTimeout不大于 0；
• lockDuration不大于 0。

4.3 集群 / Spring Cloud 场景的 UrlResolver

当引擎以集群方式部署或你使用了 Spring Cloud 的服务发现时，baseUrl不再适用。此时实现UrlResolver接口（见 UrlResolver.java），在每次请求时动态返回可用实例地址。ExternalTaskClientBuilder的 JavaDoc 中给出了基于 Spring CloudDiscoveryClient的示例骨架：从服务实例列表中随机挑选一个实例的 URI 作为getBaseUrl()的返回值。这保证了某个引擎实例不可达时，Worker 仍能通过服务发现路由到健康实例。

4.4 认证与请求拦截器

addInterceptor(ClientRequestInterceptor)允许你在请求发送前修改请求。仓库内置了基础认证实现 BasicAuthProvider.java，可用于引擎开启了 Basic Auth 的场景；拦截器体系定义见 ClientRequestInterceptor.java，请求上下文封装在 ClientRequestContext.java。

五、主题订阅：TopicSubscriptionBuilder 全参数详解

创建客户端后，通过client.subscribe(topicName)得到TopicSubscriptionBuilder（接口见 TopicSubscriptionBuilder.java，实现见 TopicSubscriptionBuilderImpl.java）。一个客户端可以订阅多个 topic，每个 topic 绑定一个ExternalTaskHandler。

client.subscribe("credit-score-topic") // BPMN 模型中 camunda:topic 指定的名称 .lockDuration(30_000) // 该主题的锁定时间，覆盖客户端级默认值 .variables("customerId", "amount") // 仅抓取需要的变量，减小负载 .handler((externalTask, externalTaskService) -> { // 业务逻辑 externalTaskService.complete(externalTask); }) .open(); // 开始异步抓取

5.1 全部配置项一览

5.2 open() 的校验规则与异步执行

open()将主题订阅发布为异步执行，出现以下情况抛出ExternalTaskClientException（见 TopicSubscriptionBuilder.java）：

• topic 名称为null或空字符串；
• lockDuration不大于 0；
• handler为null；
• 该 topic 名称已被订阅（不允许重复订阅同名 topic）。

5.3 ExternalTaskHandler：业务代码的入口

ExternalTaskHandler是一个函数式接口（ExternalTaskHandler.java），只有一个方法：

void execute(ExternalTask externalTask, ExternalTaskService externalTaskService);

它「对每个被抓取并锁定的任务执行一次」，ExternalTask携带任务上下文，ExternalTaskService提供对任务的后续操作。

集成测试 ExternalTaskHandlerIT.java 展示了完整链路：部署带外部任务的 BPMN 模型 → 启动流程实例 →client.subscribe(EXTERNAL_TASK_TOPIC_FOO).handler(handler).open()→ 断言 handler 收到的任务携带正确的processDefinitionId、processDefinitionKey、businessKey、processInstanceId、activityId、topicName、lockExpirationTime等信息。这是“订阅-抓取-回调”闭环的实测证据。

六、ExternalTask：任务上下文模型

ExternalTask接口（ExternalTask.java）封装了从引擎带回的任务上下文，主要 getter 包括：

• 标识类：getId()、getActivityId()、getActivityInstanceId()、getExecutionId()、getProcessInstanceId()、getProcessDefinitionId()、getProcessDefinitionKey()、getProcessDefinitionVersionTag()；
• 业务类：getBusinessKey()、getTopicName()、getTenantId()、getPriority()、getWorkerId()、getRetries()、getLockExpirationTime()、getCreateTime()；
• 错误类：getErrorMessage()、getErrorDetails()（最近一次上报失败时的信息）；
• 变量类：
  • getVariable(String)/getAllVariables()—— 未类型化（untyped）取值；
  • getVariableTyped(String)/getAllVariablesTyped()—— 类型化取值（TypedValue/VariableMap），可传deserializeObjectValue控制是否反序列化对象；
  • getExtensionProperty(String)/getExtensionProperties()—— 扩展属性，需订阅时开启includeExtensionProperties(true)，BPMN 活动上通过camunda:extensionProperties定义。

七、任务操作：ExternalTaskService 全 API

ExternalTaskService（ExternalTaskService.java）提供对已抓取任务的全部交互能力，几乎所有方法都支持「传ExternalTask对象」或「传String externalTaskId」两种重载。

7.1 完成任务

// 无变量 externalTaskService.complete(externalTask); // 携带流程变量（设置到任务的祖先执行层级） externalTaskService.complete(externalTask, variables); // 同时携带流程变量与局部变量（局部变量设置到外部任务实例所在执行） externalTaskService.complete(externalTask, variables, localVariables); // 直接传任务 ID externalTaskService.complete(externalTaskId, variables, localVariables);

7.2 上报失败（handleFailure）

externalTaskService.handleFailure(externalTask, "error message", // 失败原因 "error details", // 详细错误描述 retries, // 剩余重试次数，必须 >= 0；设为 0 会创建 Incident 且任务不再被抓取（除非重试次数被调高） retryTimeout); // 重试前等待毫秒数，必须 >= 0，之后任务重新可被抓取

另有重载可同时携带variables与localVariables：handleFailure(taskId, errorMessage, errorDetails, retries, retryTimeout, variables, localVariables)。当retries = 0时，引擎会为任务创建 Incident，Incident 消息即errorMessage，对应集成测试 IncidentDto 与ExternalTaskHandlerIT中的失败用例。

7.3 上报 BPMN 错误（handleBpmnError）

// 最小形式：errorCode 用于匹配 BPMN 模型中的错误处理器 externalTaskService.handleBpmnError(externalTask, errorCode); // 附带错误消息 externalTaskService.handleBpmnError(externalTask, errorCode, errorMessage); // 附带错误消息与变量（错误被捕获时传递给执行） externalTaskService.handleBpmnError(externalTask, errorCode, errorMessage, variables); // 传任务 ID 的形式 externalTaskService.handleBpmnError(externalTaskId, errorCode, errorMessage, variables);

errorCode用于识别 BPMN 错误处理器（如边界错误事件）。集成测试ExternalTaskHandlerIT中通过部署含BoundaryEvent+ErrorEventDefinition的流程，验证了上报 BPMN 错误后流程沿错误边界继续流转的行为。

7.4 锁定相关：lock / unlock / extendLock

// 手动锁定：适用于通过非 fetch & lock 途径（如 REST API）获取的任务 externalTaskService.lock(externalTaskId, lockDuration); externalTaskService.lock(externalTask, lockDuration); // 解锁：清除任务的锁过期时间与 workerId，使任务可被其他 Worker 领取 externalTaskService.unlock(externalTask); // 延长锁：为仍在执行中的任务延长锁定时长（毫秒） externalTaskService.extendLock(externalTask, newDuration); externalTaskService.extendLock(externalTaskId, newDuration);

extendLock是长耗时任务的关键 API：默认锁定 20 秒，若业务执行超过锁定时长，需在处理过程中持续延长锁，否则任务会被引擎判定为“锁过期”而重新分发给其他 Worker，造成重复执行。

7.5 设置变量（setVariables）

// 按流程实例 ID 设置变量（变量设置到任务的祖先执行层级） externalTaskService.setVariables(processInstanceId, variables); // 按任务对象设置变量 externalTaskService.setVariables(externalTask, variables);

变量 Map 可以同时包含类型化与非类型化变量。

7.6 异常体系

所有引擎交互都可能抛出以下客户端异常（见 exception 包）：

八、与引擎共享流程变量：primitive 与 object 类型

这是 README 特性清单中的最后一项，也是外部任务模式里最常踩坑的地方。客户端通过两层机制完成变量共享：

8.1 变量值映射器（ValueMapper）

客户端为每种变量类型注册了专用的ValueMapper（见 mapper 包），注册逻辑集中在 DefaultValueMappers.java：

• 基本类型：BooleanValueMapper、ByteArrayValueMapper、DateValueMapper、DoubleValueMapper、IntegerValueMapper、LongValueMapper、ShortValueMapper、StringValueMapper、NullValueMapper、NumberValueMapper；
• 对象类型：ObjectValueMapper（Java 对象，序列化为 JSON）、FileValueMapper（文件变量，支持DeferredFileValue延迟下载文件内容）、JsonValueMapper、XmlValueMapper。

DeferredFileValue（见 DeferredFileValue.java）允许先取到文件的元数据，仅在真正访问内容时才从引擎下载，避免大文件随每个任务全量传输。集成测试 FileSerializationIT.java 与 PrimitiveVariableIT.java 覆盖了这些场景。

8.2 序列化格式：JSON 与 XML

ClientValues（ClientValues.java）继承自引擎的Variables，额外提供JSON与XML两种类型化值：

// 类型化 JSON 变量 ClientValues.jsonValue("{\"key\": \"value\"}"); ClientValues.jsonValue(jsonString, true); // 第二个参数 isTransient：临时变量 // 类型化 XML 变量 ClientValues.xmlValue("<root><a>1</a></root>"); ClientValues.xmlValue(xmlString, true);

序列化格式通过 SPI 机制加载（DataFormatProvider/DataFormatConfigurator，见 spi 包）：

• JSON：默认格式（application/json），基于 Jackson 实现（JacksonJsonDataFormat.java），并提供DefaultJsonJacksonTypeDetector/ListJacksonJsonTypeDetector进行类型探测；
• XML：基于 DOM 实现（DomXmlDataFormat.java）；
• Java 序列化：SerializableDataFormat支持java.io.Serializable对象（见 SerializableDataFormat.java）。

客户端默认序列化格式与日期格式可通过构建器的defaultSerializationFormat(...)和dateFormat(...)调整。相关集成测试覆盖了 JsonSerializationIT.java、XmlSerializationIT.java、JavaSerializationIT.java 与 LocalVariableIT.java 等。

九、高级特性：长轮询、退避策略与运行控制

9.1 长轮询（Long Polling）

默认情况下 fetch-and-lock 是同步请求：引擎立即返回当前可用任务（可能为空）。通过.asyncResponseTimeout(millis)开启长轮询：请求会在引擎侧挂起最多指定毫秒数，期间一旦有任务可用立即返回；若超时仍无任务则返回空集。长轮询可显著降低 Worker 空转请求的频率，减轻引擎压力。

9.2 退避策略（Backoff Strategy）

两次请求之间默认采用指数退避策略ExponentialBackoffStrategy（ExponentialBackoffStrategy.java），默认参数为：

• initTime = 500（毫秒，第一次无任务后的等待时间）；
• factor = 2（等待时间的增长基数）；
• maxTime = 60000（毫秒，最大等待时间，封顶）。

其核心逻辑为：reconfigure(List<ExternalTask>)在每次抓取后调用——若抓取结果为空则退避层级level加一，否则重置为 0；calculateBackoffTime()返回min(initTime * factor^(level-1), maxTime)。即：连续抓不到任务时等待时间指数上升（500ms → 1s → 2s → …），一旦有任务则立即恢复零等待，避免对空闲引擎发起高频空转请求。

BackoffStrategy接口（BackoffStrategy.java）要求实现reconfigure(List<ExternalTask>)与calculateBackoffTime()两个方法；JavaDoc 特别提醒：由于同一策略可能被多线程并发调用，自定义实现必须保证线程安全。仓库还提供了针对错误响应的变体ExponentialErrorBackoffStrategy与ErrorAwareBackoffStrategy（见 backoff 包）。

若你自行实现了BackoffStrategy，通过.backoffStrategy(myStrategy)注入；若确需完全关闭退避，使用.disableBackoffStrategy()，但应留意引擎侧负载，并建议配合asyncResponseTimeout使用。

9.3 运行控制与生命周期

ExternalTaskClient（ExternalTaskClient.java）提供：

ExternalTaskClient client = ExternalTaskClient.create().baseUrl(url).build(); client.start(); // 开始持续抓取与锁定任务（默认 build() 后即自动开始） client.stop(); // 停止持续抓取与锁定 boolean active = client.isActive(); // 是否处于活跃抓取状态

若想完全控制启动时机，可调用.disableAutoFetching()，随后手动start()。

十、源码结构与集成测试：从代码到实测

对想要深入源码或贡献代码的读者，建议按以下路径阅读：

• 核心 API：ExternalTaskClient.java、ExternalTaskClientBuilder.java、TopicSubscriptionBuilder.java、ExternalTaskService.java、ExternalTask.java；
• 内部实现：ExternalTaskClientBuilderImpl.java（默认值与校验逻辑）、ExternalTaskServiceImpl.java、TopicSubscriptionManager.java（抓取调度）、RequestExecutor.java（HTTP 执行）；
• DTO 层：task/impl/dto 下的CompleteRequestDto、FailureRequestDto、BpmnErrorRequestDto、ExtendLockRequestDto、LockRequestDto、SetVariablesRequestDto、ExceptionResponseDto，以及 topic/impl/dto 下的FetchAndLockRequestDto、FetchAndLockResponseDto、TopicRequestDto，映射引擎 REST API 的请求/响应体；
• 集成测试：client/src/it/java/org/camunda/bpm/client 下按主题分类：task/ExternalTaskHandlerIT、topic/TopicSubscriptionIT、variable/PrimitiveVariableIT、variable/JsonSerializationIT、variable/XmlSerializationIT、variable/LocalVariableIT等，均通过与真实引擎（EngineRule+ClientRule，见 rule 包）联调验证端到端行为；
• 单元测试：client/src/test/java/org/camunda/bpm/client 下的ExponentialBackoffStrategyTest、ExternalTaskClientBuilderImplTest、ExternalTaskImplTest、DateValueMapperTest等；
• QA 辅助模块：clients/java/qa/engine-variable-test 提供了变量测试用的引擎应用（含Application、Bean、MyExecutionListener），供集成测试复用。

十一、注意事项与适用前提

• 本文所有行为描述均基于当前仓库代码（版本7.24.0-SNAPSHOT）。clients/java/client/pom.xml的<description>明确指出：7.24.0 是发布到 Maven Central 的最后一个社区版，该库之后不再发布新版本；如需延长维护，可考虑 Camunda 企业版（本文不作展开）。
• 客户端仅通过 REST API 与引擎交互，因此引擎必须暴露并允许访问 REST API 端点；
• workerId建议唯一且语义清晰，便于在引擎的 External Task 列表中识别 Worker；
• 长耗时任务务必使用extendLock维持锁，并合理设计retries/retryTimeout与退避策略，避免引擎侧负载与任务重复执行。

结语

Camunda External Task Client (Java) 以“Fetch & Lock”模式把工作流中的 Service Task 从引擎进程内解放出来，让业务代码以独立 Worker 的形式水平扩展、独立发布。本文完整覆盖了 README 声明的全部特性与配置入口，并深入到构建器默认值、退避算法、变量映射器与集成测试等源码细节。动手实践时，可直接以 clients/java/client/src/it/java/org/camunda/bpm/client 下的集成测试为参照，搭建自己的外部任务 Worker。

仓库内相关资源：clients/java/README.md、clients/java/client/pom.xml、spring-boot-starter/starter-client（Spring Boot 版入口）、CONTRIBUTING.md（贡献指南）、LICENSE（Apache License Version 2.0）。

【免费下载链接】camunda-bpm-platformCamunda 7 CE is End of Life (EoL). Please check out Camunda 8 instead (https://github.com/camunda/camunda) or read about Camunda 7 Enterprise End of Life (https://camunda.com/blog/2025/02/camunda-7-enterprise-end-of-life-extension/) – Camunda 7 CE was a flexible framework for workflow and decision automation using BPMN and DMN.项目地址: https://gitcode.com/GitHub_Trending/ca/camunda-bpm-platform