Apache Camel 3.x 到 4.0 迁移指南

本文档旨在帮助你将 Apache Camel 应用程序从 3.20 或更高版本迁移到 4.0。如果你是从较早的 Camel 3.x 版本（例如 3.14）升级而来，请务必先阅读各个版本的 Camel 3.x 升级指南 升级到 3.20 版本，然后再升级到 Camel 4。

Java 版本

Camel 4 支持 Java 17，不再支持 Java 11。

已移除的组件

以下组件已被移除：

日志记录

Camel 4 已将日志门面 API slf4j-api 从 1.7 升级到 2.0。

JUnit 4

所有基于 JUnit 4.x 的 camel-test 模块都已被移除。现在所有测试模块均使用 JUnit 5。

API 变更

要获取 ManagedCamelContext，应使用以下方式：

ManagedCamelContext managed = camelContext.getCamelContextExtension().getContextPlugin(ManagedCamelContext.class);

这可以通过许多其他高级 Camel 功能来实现，例如 RoutesLoader 或 ModelToXMLDumper：

RoutesLoader loader = camelContext.getCamelContextExtension().getContextPlugin(RoutesLoader.class);

EIP 变更

移除了所有 EIP 中 <description> 的 lang 属性。

InOnly 和 InOut EIP 已被移除。取而代之的是使用 SetExchangePattern 或 To，你可以在其中指定所使用的交换模式。

Poll Enrich EIP

与所有其他 EIP 一样，被轮询的端点 URI 现在作为属性存储在 Exchange 上（键为 CamelToEndpoint）。此前 URI 是作为消息头存储的。

CircuitBreaker EIP

camel-resilience4j 中的以下选项被错误地未定义为属性：

这些选项未在 YAML DSL 中暴露，而在 XML DSL 中，你需要从以下形式迁移：

<circuitBreaker>
    <resilience4jConfiguration>
        <timeoutEnabled>true</timeoutEnabled>
        <timeoutDuration>2000</timeoutDuration>
    </resilience4jConfiguration>
...
</circuitBreaker>

改用注解（attribute）：

<circuitBreaker>
    <resilience4jConfiguration timeoutEnabled="true" timeoutDuration="2000"/>
...
</circuitBreaker>

XML DSL

用于为路由或节点设置描述的 <description> 已从元素更改为属性。

之前：

<route id="myRoute">
  <description>Something that this route do</description>
  <from uri="kafka:cheese"/>
  ...
</route>

修改后：

<route id="myRoute" description="Something that this route do">
  <from uri="kafka:cheese"/>
  ...
</route>

类型转换器

String → java.io.File 转换器已被移除。

跟踪

Tracer 和 Backlog Tracer 不再包含由 Rest DSL、路由模板或 Kamelet 创建的路由所产生的内部跟踪事件。可以通过在 tracer 中设置 traceTemplates=true 来启用此功能。

Backlog Tracer 已增强并修复了对消息头（也包括流类型）的跟踪。这意味着之前 InputStream 类型的消息头不会被跟踪，而现在会被包含在内。这可能导致消息头的流已定位到末尾，随后记录该消息头时，其值看起来为空。

UseOriginalMessage / UseOriginalBody

当在 OnException、OnCompletion 或错误处理器中启用 useOriginalMessage 或 useOriginalBody 时，原始消息体将被防御性复制，并在可能的情况下转换为 StreamCache，以确保在访问时可以重新读取该消息体。之前原始消息体不会被转换为 StreamCache，这可能导致消息体无法读取或流已被关闭。

Camel 健康检查

健康检查现在默认开箱即用时仅执行就绪检查。

Camel 提供的 CamelContextCheck 同时作为就绪检查和存活检查，因此开箱即用至少各有一个。

默认仅启用基于消费者的健康检查。

生产者健康检查

选项 camel.health.components-enabled 已重命名为 camel.health.producers-enabled。

某些组件（尤其是 AWS）也提供了针对生产者的健康检查。在 Camel 3.x 中，这些健康检查无法正常工作，已在源代码中禁用。为了在 Camel 4 中延续这一行为，基于生产者的健康检查被禁用。

请注意，camel-kafka 自带在 Camel 3 中可以正常工作的基于生产者的健康检查，因此在 Camel 4 中的这一变更意味着该健康检查已被禁用。

你必须全局启用生产者健康检查，例如在 application.properties 中：

camel.health.producers-enabled = true

JMX

Camel 现在还在处理器 MBean 的树结构中包含了 doCatch 和 doFinally 的 MBean。

ManagedChoiceMBean 已将 choiceStatistics 重命名为 extendedInformation。ManagedFailoverLoadBalancerMBean 已将 exceptionStatistics 重命名为 extendedInformation。

CamelContextMBean 和 CamelRouteMBean 已移除方法 dumpRouteAsXml(boolean resolvePlaceholders, boolean resolveDelegateEndpoints)。

YAML DSL

Camel 3.14 及更早版本中允许将 steps 作为 route 子节点的向后兼容模式已被移除。

旧语法：

- route:
    from:
      uri: "direct:info"
    steps:
    - log: "message"

应改为：

- route:
    from:
      uri: "direct:info"
      steps:
      - log: "message"

Backlog Tracing

选项 backlogTracing=true 现在会在启动时自动启用跟踪器。之前的行为令人意外地只是让跟踪器可用，之后需要手动启用。若要恢复旧行为，可以设置 backlogTracingStandby=true。

请将类 org.apache.camel.api.management.mbean.BacklogTracerEventMessage 从 camel-management-api JAR 移动到 camel-api JAR 中的 org.apache.camel.spi.BacklogTracerEventMessage。

org.apache.camel.impl.debugger.DefaultBacklogTracerEventMessage 已被重构为接口 org.apache.camel.spi.BacklogTracerEventMessage，并包含有关被跟踪消息的一些额外细节。例如，Camel 现在会捕获第一条和最后一条跟踪记录，其中包含输入消息和输出消息（如果为 InOut）。

XML 序列化

使用 ModelToXMLDumper 的默认 XML 序列化已得到改进，现在使用的是 camel-xml-io 模块中生成的 XML 序列化器，而不是来自 camel-jaxb 的基于 JAXB 的序列化器。

OpenAPI Maven 插件

camel-restdsl-openapi-plugin Maven 插件现在在生成的 Rest DSL 代码中使用 platform-http 作为默认的 rest 组件。此前默认值是 servlet。不过，platform-http 是更好的默认值，可与 Spring Boot 和 Quarkus 开箱即用。

组件变更

Category

org.apache.camel.Category 的枚举数量已从 83 个减少到 37 个，这意味着使用了已删除值的自定义组件需要从剩余的值中选择一个。我们这样做是为了整合 Camel 社区中组件类别的数量。

camel-openapi-rest-dsl-generator

该 dsl-generator 已将其底层模型类（apicurio-data-models）从 1.1.27 更新到 2.0.3。

camel-atom

camel-atom 组件已将第三方 atom 客户端从 Apache Abdera 更换为 RSSReader。这意味着 feed 对象从 org.apache.abdera.model.Feed 变为 com.apptasticsoftware.rssreader.Item。

camel-azure-cosmosdb

itemPartitionKey 已更新。它现在是一个 String，而不再是 PartitionKey。更多细节参见 CAMEL-19222。

camel-bean

当使用 method 选项指向特定方法，并使用参数类型和值时，例如："bean:myBean?method=foo(com.foo.MyOrder, true)"，现在所有类类型都必须使用 .class 语法，即 com.foo.MyOrder 应写为 com.foo.MyOrder.class。

上面的示例现在应如下所示：

"bean:myBean?method=foo(com.foo.MyOrder.class, true)"

这也适用于 String、int 等 Java 类型：

"bean:myBean?method=bar(String.class, int.class)"

camel-box

已从 Box Java SDK v2 升级到 v4，其中一些方法签名发生了变化。获取文件缩略图的方法已不再可用。

camel-caffeine

keyType 参数已被移除。缓存的键现在只能是 String 类型。更多信息参见 CAMEL-18877。

camel-fhir

底层的 hapi-fhir 库已从 4.2.0 升级到 6.2.4。只有 Delete API 方法发生了变化，现在返回 ca.uhn.fhir.rest.api.MethodOutcome 而不再是 org.hl7.fhir.instance.model.api.IBaseOperationOutcome。有关底层变更的更详细列表，请参阅 https://hapifhir.io/hapi-fhir/blog/（Camel 中仅使用了 hapi-fhir 客户端）。

camel-google

基于 API 的组件 camel-google-drive、camel-google-calendar、camel-google-sheets 和 camel-google-mail 已从 Google Java SDK v1 升级到 v2，并更新至最新的 API 修订版本。camel-google-drive 和 camel-google-sheets 的一些 API 方法有所变化，而其他组件与之前保持一致。

camel-http

该组件已升级为使用 Apache HttpComponents v5，这会影响底层客户端的配置方式。超时配置由原来的 3 个（connectionRequestTimeout、connectTimeout 和 socketTimeout）变为 4 个（connectionRequestTimeout、connectTimeout、soTimeout 和 responseTimeout），并且其中一些的默认值也发生了变化，详情请参阅文档。

请注意，socketTimeout 已从 HttpClient 的可配置参数中移除，请改用 responseTimeout。

最后，soTimeout 选项以及包含在 SocketConfig 中的所有参数都需要加上 httpConnection. 前缀，其余参数（包括在 HttpClientBuilder 和 RequestConfig 中定义的参数）仍然与之前一样需要加上 httpClient. 前缀。

camel-http-common

org.apache.camel.http.common.HttpBinding 中的 API 为了更具可复用性而略有变化。parseBody 方法现在接收 HttpServletRequest 作为输入参数。并且所有的 HttpMessage 都已改为泛型 Message 类型。

camel-kubernetes

io.fabric8:kubernetes-client 库已升级，并且移除了一些已弃用的 API 用法。之前以 replace 为前缀的操作现在改以 update 为前缀。

例如 replaceConfigMap 现在改为 updateConfigMap，replacePod 现在改为 updatePod，等等。类 KubernetesOperations 中对应的常量也已重命名。REPLACE_CONFIGMAP_OPERATION 现在改为 UPDATE_CONFIGMAP_OPERATION，REPLACE_POD_OPERATION 现在改为 UPDATE_POD_OPERATION，等等。

camel-web3j

camel-web3j 已将 web3j JAR 从 3.x 升级到 5.0，其中包含许多 API 变更，因此之前的一些 API 调用已不再提供。

camel-main

以下常量已从 BaseMainSupport / Main 移至 MainConstants：

camel-micrometer

指标名称已重命名，以遵循 Micrometer 命名规范 Naming Meters。

camel-jbang

命令 camel dependencies 已重命名为 camel dependency。

在 Camel JBang 中，init 和 run 目标的 -dir 参数已重命名，需像其他所有选项一样使用两个短横线 --dir。

camel stop 命令现在默认会停止所有正在运行的集成（--all 选项已被移除）。

占位符替换已改为使用 #name 而非 $name 语法。

camel-jpa

选项 transactionManager 已被移除，新增了名为 transactionStrategy 的选项，它作为与实现厂商无关的抽象层，使配置 Spring Transaction 或 Quarkus Transaction 更为简便。

camel-openapi-java

camel-openapi-java 组件已改为使用 io.swagger.v3 库，替代了 io.apicurio.datamodels。因此，公开方法 org.apache.camel.openapi.RestOpenApiReader.read() 的返回类型现在是 io.swagger.v3.oas.models.OpenAPI，而不再是 io.apicurio.datamodels.openapi.models.OasDocument。当解析 OpenAPI 2.0 (swagger) 规范时，swagger 解析器会自动将其升级为 OpenAPI 3.0.x。此版本还支持 OpenAPI 3.1.x 规范。相关的 spring-boot starter 组件也已修改为使用新的返回类型。

camel-optaplanner

camel-optaplanner 组件已改为使用 SolverManager。如果您在 Camel 3 中使用了 SolverManager，则不再需要在路由中使用布尔值 useSolverManager。已废弃的 ProblemFactChange 已被 ProblemChange 取代。

新的 URI 路径为：

仅限 Java：新的 OptaPlanner URI 语法

from("optaplanner:myProblemName")
  .to("...")

你可以通过以下 2 种方式传入 OptaPlanner 的 SolverManager：

• 作为 #parameter
• 作为 header

在 Spring Boot 或 Quarkus 上运行 camel-optaplanner 时，建议使用 Spring Boot 或 Quarkus 自身的方式来创建 SolverManager。

也可以迁移传统的 Camel OptaPlanner 路由，只需按下面代码所示放置 XML 配置文件即可。Camel OptaPlanner 会为这些传统路由创建 SolverManager：

纯 Java 方式：带 XML 配置文件的传统 OptaPlanner 路由

from("optaplanner:myProblemName?configFile=PATH/TO/CONFIG.FILE.xml")
  .to("...")

Solver Daemon 解决方案应迁移到使用 SolverManager。

camel-platform-http-vertx

如果路由或消费者处于挂起状态，则现在返回 HTTP 状态码 503，而不是 404。

camel-salesforce

生成的 DTO 中 blob 字段的属性名不再附加 Url。例如，ContentVersionUrl 属性现在简化为 ContentVersion。

camel-slack

Slack 消费者的默认延迟从 0.5 秒改为 10 秒，以避免过于频繁地被 Slack 限流。

camel-spring-rabbitmq

camel-spring-rabbitmq 中的 replyTimeout 选项已修正，默认值从 5 秒改为 30 秒（这是 Spring 使用的默认值）。

Camel Spring Boot

camel-spring-boot 依赖不再包含 camel-spring-xml。如果要在 Spring Boot 上使用 Camel 并继续使用传统的 Spring XML 文件 <beans>，请引入 camel-spring-boot-xml-starter 依赖。

优雅停机

在 Spring Boot 关闭时，Apache Camel 的关闭会稍晚一些。这样可以先让 Spring Boot 的优雅停机完成（优雅地停止 Spring Boot HTTP 服务器），随后 Camel 再执行自身的优雅停机。

从技术上讲，camel-spring 将 getPhase() 的返回值从 Integer.MAX_VALUE 改为了 Integer.MAX_VALUE - 2049。这为 Spring Boot 服务优先关闭留出了空间。

camel-micrometer-starter

uri 标签现在默认是静态的而非动态的，因为包含动态值的 URI 可能会生成过多的标签。可以通过设置 camel.metrics.uriTagDynamic=true 重新启用动态标签。

camel-platform-http-starter

platform-http-starter 已从使用 camel-servlet 改为直接使用 Spring HTTP 服务器。因此，所有 HTTP 端点不再带有 servlet 上下文路径前缀（默认为 camel）。

例如：

纯 Java 方式：不带 servlet 上下文路径的 platform-http 端点

from("platform-http:myservice")
  .to("...")

随后调用 myservice 之前需要包含 context-path，例如 http://localhost:8080/camel/myservice。现在不再使用 context-path，可以直接通过 http://localhost:8080/myservice 调用该端点。

如果路由或消费者处于挂起状态，那么现在将返回 HTTP 状态 503，而不是 404。

camel-twitter

该组件已更新为使用 Twitter4j 4.1.2 版本，该版本移动了其部分类所使用的包。如果访问特定的 Twitter 相关数据（例如推文状态），则需要将所使用的包从 twitter4j.Status 更新为 twitter4j.v1.Status。

从 Camel 4.0.1 升级到 4.0.2

camel-file

使用 readLockMinAge 的 readLock=changed 已恢复为与 3.x 相同的行为。

例如，使用 readLockMinAge=5s 将选取启动时间之前已超过 5 秒的文件。如果你在启动时已有许多陈旧的存量文件，那么 Camel 现在将恢复快速处理，立即选取这些文件。

从 Camel 4.0.0 升级到 4.0.1

camel-aws2-sns

queueUrl 参数已被 queueArn 参数取代。

例如，之前

from("direct:start")
  .to("aws2-sns://mytopic?subject=mySubject&autoCreateTopic=true&subscribeSNStoSQS=true&queueUrl=https://xxxx")

应更改为

from("direct:start")
  .to("aws2-sns://mytopic?subject=mySubject&autoCreateTopic=true&subscribeSNStoSQS=true&queueArn=arn:aws:sqs:xxxxx")