camunda-development

Camunda 开发

在为 Camunda 8.8+ 编写任何集成代码之前，先决定使用开箱即用的连接器、自定义连接器模板、通过 Connectors SDK 构建的自定义 Java 连接器，还是任务 Worker。此技能仅提供简要指引——它指出的每条路径都有各自专门的构建技能。

交叉引用

• camunda-connectors：用于浏览并应用现有的 OOTB 连接器模板
• camunda-connectors-development：用于构建自定义连接器（基于协议连接器的纯 JSON 模板，或通过 Connectors SDK 构建的 Java 连接器；涵盖出站和入站）
• camunda-job-workers：用于通过 Java、Spring Boot 或 TypeScript 实现任务 Worker
• camunda-bpmn：用于承载连接器或 Worker 任务的 BPMN 元素（服务任务、消息事件，……）
• camunda-process-test：用于测试生成的流程

决策矩阵

从上到下依次回答问题。遇到第一个答案为“是”的问题时停止。

1. 开箱即用（OOTB）连接器是否能满足此集成需求？ 使用 c8ctl element-template search "<keyword>" 搜索本地目录（参见 camunda-connectors）。如果有模板与目标系统匹配，就直接使用。停止。

2. 此集成是否是在常见协议（REST、SOAP、GraphQL、Kafka、RabbitMQ、AWS SQS/SNS 等）上发起的单次 API 调用，且你是否需要可复用、方便建模的构建块？ → 路径 A——基于协议连接器的纯 JSON 模板。 无需 Java，也无需单独的运行时。自定义协议连接器已发布的模板：使用 FEEL 预填 URL，隐藏 method / base URL / auth，仅暴露特定领域的属性。参见 camunda-connectors-development。

3. 此逻辑是否不止是单次 API 调用（专有协议、包含状态的多步骤编排、非 HTTP I/O、自定义入站触发器），且团队是否使用 Java？ → 路径 B——通过 Connectors SDK 构建自定义 Java 连接器。 由注解驱动，自动生成元素模板，并内置机密 / 内置函数 / Camunda Documents 支持。适用于出站和入站。参见 camunda-connectors-development。

4. 否则——使用非 Java 技术栈，或此逻辑已在你的应用中实现，或需要较底层的 Zeebe API（任务流式处理、自定义激活）。 → 路径 C——任务 Worker。 使用官方 SDK 之一（此处涵盖 Java、Spring Boot、TypeScript；其他 SDK 遵循相同模式）在应用中实现处理程序。如果还需要为 Worker 提供建模界面，可手动编写元素模板 JSON。参见 camunda-job-workers。

对比：任务 Worker 与连接器（SDK）

方面	任务 Worker	连接器（SDK）
语言	任意官方 SDK（Java、Spring Boot、TypeScript 等）	仅 Java
交付方式	与运行它的应用绑定	库，可部署到任意 Connector Runtime
跨环境复用	困难——每个项目都要重新接线	简单——同一个 JAR，可放入任意运行时
侧重点	完整的 Zeebe 客户端（激活、完成、失败、重试）	纯业务逻辑；由运行时处理 Zeebe 接线
机密	自行实现（环境变量、机密管理器）	内置 {{secrets.NAME}} 解析
较底层的 Zeebe API	支持	不支持
任务的建模界面	可选——手动编写元素模板 JSON	标准化——由 @ElementTemplate 生成
元素模板自动生成	无——手动编写 JSON	Maven 插件根据注解生成
内置函数（getText、base64 等）	不支持	支持
Camunda Documents 处理	手动处理	内置
入站触发器	不支持（仅出站任务）	支持（Webhook / Subscription / Polling）

此表解释了决策矩阵背后的原因：连接器以语言覆盖范围换取可复用性和更丰富的功能；Worker 则以这些功能换取语言选择和直接访问 Zeebe 的能力。

实例 — 应用决策矩阵

“订单获批时通知 Slack。团队使用 Node.js。”

1. 有现成的连接器吗？ c8ctl element-template search "slack" 返回 io.camunda.connectors.Slack.v1。机器人消息操作可满足一次性通知的需求，无需自定义 UI。→ 使用它。 到此为止。

“向我们的内部 HTTP 定价 API 提交任务。团队使用 Java。我们希望构建一个可复用的连接器，在 Modeler 中仅公开 customerId、productSku 和 quantity。”

1. 有现成的连接器吗？没有匹配的模板。
2. Java 团队是否要通过某种协议调用单个 API，以构建可复用的基础模块？ 是 — REST。→ 路径 A。 使用已发布的 HTTP REST 连接器模板，通过 FEEL 表达式预填 URL，以便根据 customerId 构建请求 URL；隐藏 method / base URL / auth 字段，仅公开这三个领域属性。仅使用 JSON；无需部署运行时。请参阅 camunda-connectors-development。

“定期从 SFTP 服务拉取发票，并为每个文件启动一个流程。团队使用 Java。”

1. 有现成的连接器吗？没有符合需求的 SFTP 拉取启动事件连接器。
2. 是否通过常见协议调用单个 API？不是 — SFTP、自定义轮询频率、入站触发器。
3. 集成是否复杂，且团队使用 Java？ 是。→ 路径 B，采用轮询入站类型。使用 Connectors SDK 构建。请参阅 camunda-connectors-development。

“使用团队现有的 Node.js 评分服务为客户记录评分。”

1. 有现成的连接器吗？没有。
2. 是否通过某种协议调用单个 API，且团队使用 Java？团队使用 Node.js — 语言不匹配。（你仍然可以用 Java REST 模板封装评分服务，但相关逻辑已经位于 Node.js 应用中，而且没有 Java 团队来维护连接器。）
3. 团队使用 Java 吗？不。→ 路径 C，任务工作器。通过 TypeScript SDK 将现有 Node.js 服务接入，以处理 score-customer 任务。请参阅 camunda-job-workers。

在一个项目中混合使用

工作器和连接器是按任务选择，而非按项目选择。单个 Spring Boot 应用可以并行托管任务工作器（通过 Camunda Spring Boot Starter）和嵌入式连接器运行时（通过 spring-boot-starter-camunda-connectors）——Connectors SDK 本身也构建在 Spring Boot Starter 之上。为每个集成选择合适的方式；无需让整个项目都采用同一条路径。

多制品交付编排（BPMN + workers + DMN + 表单）

当一个流程涉及多个服务任务、用户任务和业务规则任务时，应将实现编排为结构化交接，而不是临时生成：

1. 根据 BPMN 制定明确的实现计划：
   • 服务任务／消息事件集成点 → 连接器或 worker 路径
   • 带有 formId 的用户任务 → .form 交付物
   • 带有 decisionId 的业务规则任务 → .dmn 交付物
2. 在生成制品之前，审查并批准该计划。
3. 在安全的前提下并行实现独立领域：
   • workers／连接器
   • DMN 决策
   • 表单
   • BPMN 执行连线更新
4. 运行领域验证循环：
   • BPMN：c8ctl bpmn lint（并根据需要进行兼容性检查）
   • DMN：npx --yes dmnlint（结构检查）+ FEEL／命中策略测试执行（参见 camunda-dmn）
   • 表单：验证 JSON schema — 必填字段、schemaVersion、组件 key 唯一性（参见 camunda-forms）
5. 部署前运行跨制品连线审计：
   • 每个非连接器的 taskDefinition type（通常是不含连接器风格冒号的值，例如 check-credit）都由 worker 实现；连接器运行时任务类型（例如 io.camunda:slack:1）由连接器模板／运行时解析，而非由自定义 worker 实现
   • 每个被引用的 formId 都存在，且与表单 id 相匹配
   • 每个被引用的 decisionId 都存在于已部署的 DMN 资源中
6. 仅部署验证通过的类别；如果有意排除某个类别，应明确记录，并在修复之前将发布状态保持为部分完成。

这样可以确保大型 Camunda 交付过程可确定、可审查且能够安全迭代。

入站属于连接器范畴

入站触发器 — 即从外部系统流入流程的事件 — 只能通过 Connectors SDK 实现。入站没有 job worker 路径：job workers 只处理引擎已激活的出站作业。

SDK 支持三种入站类型，选择哪一种决定了元素模板适用的 BPMN 元素类型（消息启动事件、中间捕获事件、边界事件等）：

• Webhook — 运行时托管 HTTP 监听器；外部系统调用该监听器。
• Subscription — 运行时与消息代理（Kafka、RabbitMQ、AMQP 等）建立长连接并消费事件。
• Polling — 运行时按计划轮询外部端点。

如果集成是入站的，决策矩阵中的路径 A 和 B 是仅有的选项；路径 C 不适用。参见 camunda-connectors-development。

本地先决条件

决策矩阵会指向一条路径；该路径需要可用的本地工具链。参见 references/prerequisites.md，了解各工作流的概览（每条路径需要哪些工具 — Node.js、JRE、JDK + Maven、Docker）、适用于各种操作系统的验证单行命令，以及通用注意事项（JAVA_HOME 与 PATH、Docker 守护进程与 CLI、为何不应预先拉取 camunda/zeebe:latest）。各路径的具体最低版本要求见对应的技能文档 — 这些要求会随每个 Camunda 版本更新。

参考资料

• prerequisites.md — 本地开发环境矩阵（各工作流所需的 JDK / Node.js / Maven / Docker）、验证单行命令和工具注意事项。