camunda-job-workers

Camunda Job Workers

使用 Java、Camunda Spring Boot 或 TypeScript 为 Camunda 8.8+ 实现 Job Worker。Job Worker 是 Zeebe 引擎将已激活的 Job 交给它处理的处理程序——它运行业务逻辑，然后向引擎报告成功、失败或 BPMN 错误。

前提条件

• Worker 进程可以访问 Camunda 8.8+ 集群（本地 c8run、SaaS 或 Self-Managed——参见 camunda-c8ctl）
• 一个 BPMN 流程，其中至少有一个元素包含与 Worker 的 Job 类型匹配的 <zeebe:taskDefinition type="..."/>（参见 camunda-bpmn）
• 所选 SDK 的工具链——Java 和 Spring 需要 OpenJDK 17+ 以及 Maven/Gradle；TypeScript 需要 Node.js 18+。各 SDK 的特定版本限制（例如 Spring Boot 4 与 3、浏览器支持情况）请参阅各 SDK 的参考文档。本地安装方法请参见 camunda-development。

交叉参考

• camunda-development：首先使用它，判断 Worker 是否适合当前场景（而不是 OOTB 连接器、仅限 JSON 的 protocol-connector 模板，或通过 SDK 实现的自定义 Java 连接器）
• camunda-connectors-development：当集成更适合实现为可复用的 Java 连接器，而非绑定到应用的 Worker 代码时，或当集成需要入站触发器时（Worker 只能出站）
• camunda-bpmn：了解 service-task / receive-task 元素及其 zeebe:taskDefinition，以及用于捕获 Worker BPMN 错误的边界事件
• camunda-feel：了解 zeebe:taskHeaders 中的 FEEL，以及用于处理 Worker 输出变量的网关条件
• camunda-process-mgmt：部署流程、针对正在运行的 Worker 启动实例，以及从集群端检查 Job / incident
• camunda-process-test：了解如何通过嵌入式 Zeebe 引擎驱动 Worker 处理程序进行端到端测试

何时编写 Job Worker

首先查看 camunda-development。与此处相关的简要决策矩阵如下：

• 非 Java 技术栈（TypeScript，以及未来版本可能涵盖的任何其他官方 SDK）：选择 Worker。连接器仅支持 Java。
• Java 技术栈，且逻辑已存在于应用中：使用 Worker 可将逻辑保留在拥有它的代码库中。
• Java 技术栈，逻辑需在多个流程 / 项目 / 集群间复用：优先通过 camunda-connectors-development 实现自定义连接器。
• 入站触发器（外部系统将事件推送到流程中）：始终使用连接器——Worker 只会从引擎拉取已激活的 Job。

Job 生命周期

Worker 与引擎之间的约定包含四种状态：

1. 激活——Worker 请求指定 type 的 Job（轮询），或通过流式连接接收 Job。每次激活都包含一个超时时间（引擎授予的租约；如果 Worker 未及时响应，引擎将在租约到期后把同一 Job 交给其他 Worker）和一个获取变量列表（引擎随 Job 一同发送的流程变量）。
2. 处理——Worker 使用已激活的 job（变量、标头、剩余重试次数、键）运行处理程序代码。
3. 完成——Worker 调用 complete（或在 autoComplete=true 时返回值）。引擎会将 Worker 的输出变量合并到流程作用域，并推进令牌。变量会按照 BPMN 规则从 Job 作用域向上传播到外层作用域。
4. 失败——Worker 可以显式调用 fail 并提供剩余重试次数和可选的退避时间，也可以抛出异常。如果重试次数降至零，引擎会生成一个 incident，实例将暂停，直到操作员解决问题（参见 camunda-process-mgmt）。

激活超时与重试次数相互独立。 超时意味着引擎会重新分配 Job，但不会减少重试次数；调用 fail 且仍有剩余重试次数时，同一 Job 会在退避时间后重新投递。对于运行时间较长的处理程序，应通过 UpdateJobTimeout 延长超时时间，避免租约过期。

幂等性 — 每个作业至少处理两次

引擎的至少一次投递保证意味着，对于同一个 job.key，处理器可能会运行多次。激活超时、网络故障，以及 complete 调用失败后的重试，都会导致重新投递。处理器必须具备幂等性。

以下两种模式都很有效：

• 在下游系统中使用幂等令牌。 使用 job.key（或根据流程变量确定性派生的值）作为请求 ID、Idempotency-Key 标头或数据库唯一约束。同一作业重试时会命中相同的键，因此操作会被抑制。
• 写入前先检查。 在执行副作用之前，查询下游系统中是否已有对应标记。如果系统支持，这种方式成本很低；但并非始终可用。

在 Worker 进程中本地存储“这个作业是否运行过”的状态并不算幂等性——进程可能会崩溃、扩容或被替换。

失败模式 — 三条不同路径

具体选择取决于失败属于暂时性基础设施问题、建模后的业务结果，还是意外的编程错误：

1. 暂时性失败 → 失败并重试，采用退避策略。 网络超时、下游 5xx、代理不可达。处理器会递减重试次数，并要求引擎在退避后重新投递。重试次数归零时会引发事件。

2. 业务结果 → BPMN 错误。 处理器成功识别出 BPMN 中建模的失败情形，例如付款被拒、库存为空、许可证被拒。抛出一个 BPMN 错误，其代码由错误边界事件（或子流程中的错误结束事件）捕获。作业不会重试——引擎会转入错误路径。

3. 编程错误 → 未处理异常。 NullPointerException、未处理的 Promise 拒绝、类型错误。SDK 会回退到零退避失败——引擎立即重新投递，耗尽重试次数后引发事件。绝不要将未处理异常用作控制流信号：零退避会导致集群频繁空转，而且未来的 SDK 变更可能会重新定义默认行为。

SDK 特定的调用签名（Spring 中的 CamundaError.jobError / CamundaError.bpmnError，Java 客户端中的 newFailCommand / newThrowErrorCommand，TypeScript 中的 job.fail / job.error）请参阅各 SDK 的参考文档。

自动完成与显式完成

Camunda Spring Boot Starter 的 @JobWorker 默认会自动完成：处理器的返回值会序列化为作业的输出变量。当处理器需要自行调用 complete（条件变量、异步响应、所有权转移）时，请设置 autoComplete = false。

Java 客户端和 TypeScript SDK 不会自动完成——处理器必须在每条代码路径上调用 complete、fail 或 error。遗漏终止调用会导致作业的租约一直持续到激活超时。

选择 SDK

SDK	适用场景
Camunda Spring Boot Starter — camunda-spring-boot-starter (ref)	新的 Java 应用程序。注解驱动（@JobWorker）、自动完成，通过 application.yaml 配置。Java 的默认路径。
Java 客户端 — camunda-client-java (ref)	独立 JVM 应用程序、非 Spring 框架、集成 Zeebe 访问能力的库。较底层的构建器 API。取代已弃用的 Zeebe Java Client（在 8.10 中移除）。
TypeScript — @camunda8/orchestration-cluster-api (ref)	Node.js Worker、托管在浏览器中的客户端、8.9+ 项目。仅当明确需要 gRPC 流式传输、面向低于 8.8 的目标版本，或受迁移障碍影响时，才回退使用 @camunda8/sdk（仅限 Node.js）。

Spring Boot 4 与 3——高风险路由

默认的 Camunda Spring Boot Starter（camunda-spring-boot-starter）随 Spring Boot 4.0.x 一同打包，并且要求使用 Spring Boot 4.0.x。

仍在使用 Spring Boot 3.5.x 的应用应将 camunda-spring-boot-3-starter 用作迁移桥梁——Spring 对 3.5.x 系列的 OSS 支持将于 2026 年 6 月结束。不要在同一 classpath 中混用这两个 Starter：SB4 Starter 无法在 Spring Boot 3 应用上启动，而 SB3 Starter 会将冲突的传递依赖引入 Spring Boot 4 应用。

所有 Starter 模块都要求使用 OpenJDK 17+。

常见陷阱

• 忘记完成、失败或报错结束作业（Java 客户端、TypeScript）。租约会超时，引擎随后会重新派发作业。处理器必须在每条代码路径上恰好调用一次终止调用。Spring 的 autoComplete = true 会处理成功返回的情况；失败路径仍需显式发出信号。
• 将未处理的异常视为 BPMN 错误。 未处理的异常是编程错误，而不是建模的结果。SDK 会将作业的 retries 减 1，并将 retryBackoff 设为 0——引擎会立即重新派发作业、耗尽重试次数并引发事件。
• 在 Worker 进程中存储“已处理”状态。 崩溃和扩容都会使其丢失。幂等性应由下游系统保障，或存储在能在重新派发后保留的流程变量中。
• 轮询与请求超时不匹配。 激活请求的超时时间必须短于网关／负载均衡器的中断阈值，否则 Worker 会断开连接并陷入循环重连。SDK 默认值合理——请谨慎修改。

参考资料

有关 SDK 的具体信息，请阅读 references/ 中的文档：

• worker-sdk-java.md — camunda-client-java：客户端引导、JobWorkerBuilder、命令构建器、流式处理、多租户、OAuth 配置
• worker-sdk-spring.md — Camunda Spring Boot Starter：@JobWorker 参数参考、@Variable / @VariablesAsType、CamundaError、配置属性树、Spring Boot 4 与 3 的 Starter 选择
• worker-sdk-typescript.md — @camunda8/orchestration-cluster-api：createJobWorker / createThreadedJobWorker、作业处理器返回值形式、何时回退到 @camunda8/sdk