Camel Report Maven 插件

Camel Report Maven 插件支持以下目标（goal）：

camel-report:validate - 校验源代码中无效的 Camel 端点 URI
camel-report:route-coverage - 在单元测试之后，报告 Camel 路由的覆盖率

camel-report:validate

用于校验源代码中配置错误的 Camel 内容：

端点 URI
Simple 表达式或谓词
重复的路由 ID
seda/direct 端点对
属性文件中的配置

之后，你可以在命令行中运行 validate 目标，也可以在 IDEA 或 Eclipse 等 Java 编辑器中运行。

mvn camel-report:validate

你也可以启用该插件，让它在构建过程中自动运行，从而捕获这些错误。

<plugin>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-report-maven-plugin</artifactId>
  <executions>
    <execution>
      <phase>process-classes</phase>
      <goals>
        <goal>validate</goal>
      </goals>
    </execution>
  </executions>
</plugin>

阶段决定了插件何时运行。在上面的示例中，阶段为 process-classes，它会在主源代码编译完成后运行。

Maven 插件也可以配置为校验测试源代码，这意味着需要相应地将阶段改为 process-test-classes，如下所示：

<plugin>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-report-maven-plugin</artifactId>
  <executions>
    <execution>
      <configuration>
        <includeTest>true</includeTest>
      </configuration>
      <phase>process-test-classes</phase>
      <goals>
        <goal>validate</goal>
      </goals>
    </execution>
  </executions>
</plugin>

在任意 Maven 项目上运行该 goal

你也可以在任意 Maven 项目上运行 validate goal，而无需将该插件添加到 pom.xml 文件中。这样做的前提是使用插件的完全限定名来指定它。例如，要在 Apache Camel 的 camel-example-cdi 上运行该 goal，可以执行

cd camel-example-cdi
mvn org.apache.camel:camel-report-maven-plugin:2.20.0:validate

随后运行并输出以下内容：

[INFO] ------------------------------------------------------------------------
[INFO] Building Camel :: Example :: CDI 3.0.0
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] --- camel-report-maven-plugin:3.0.0:validate (default-cli) @ camel-example-cdi ---
[INFO] Endpoint validation success: (4 = passed, 0 = invalid, 0 = incapable, 0 = unknown components)
[INFO] Simple validation success: (0 = passed, 0 = invalid)
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

验证通过，共校验了 4 个端点。现在假设我们在源代码中的某个 Camel 端点 URI 里打错了一个字符，例如：

@Uri("timer:foo?period=5000")

是修改为在 period 选项中包含一个拼写错误

@Uri("timer:foo?perid=5000")

再次运行 validate 目标时，会报告以下内容：

[INFO] ------------------------------------------------------------------------
[INFO] Building Camel :: Example :: CDI 3.0.0
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] --- camel-report-maven-plugin:3.0.0:validate (default-cli) @ camel-example-cdi ---
[WARNING] Endpoint validation error at: org.apache.camel.example.cdi.MyRoutes(MyRoutes.java:32)

    timer:foo?perid=5000

                       perid    Unknown option. Did you mean: [period]


[WARNING] Endpoint validation error: (3 = passed, 1 = invalid, 0 = incapable, 0 = unknown components)
[INFO] Simple validation success: (0 = passed, 0 = invalid)
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

选项

Maven 插件的 validate 目标支持以下选项，可以通过命令行（使用 -D 语法）配置，也可以在 pom.xml 文件的 <configuration> 标签中定义。

参数	默认值	说明
downloadVersion	true	是否允许从互联网下载 Camel catalog 版本。当项目使用的 Camel 版本与本插件默认使用的版本不同时，需要启用此选项。
failOnError	false	当发现无效的 Camel 端点时是否导致构建失败。默认情况下，插件仅以 WARN 级别记录这些错误。
coverageThreshold	100	使用 failOnError 时，路由覆盖率的最低百分比。
overallCoverageThreshold	0	使用 failOnError 时，所有路由整体覆盖率的最低百分比。
logUnparseable	false	是否记录无法解析的端点 URI（因此无法进行验证）。
includeJava	true	是否将 Java 文件纳入验证，以检查其中无效的 Camel 端点。
includeXml	true	是否将 XML 文件纳入验证，以检查其中无效的 Camel 端点。
includeTest	false	是否包含测试源代码。
includes		过滤 Java 和 XML 文件的名称，仅包含与给定模式列表（通配符和正则表达式）中任一模式匹配的文件。多个值可用逗号分隔。
excludes		过滤 Java 和 XML 文件的名称，排除与给定模式列表（通配符和正则表达式）中任一模式匹配的文件。多个值可用逗号分隔。
ignoreUnknownComponent	true	是否忽略未知组件。
ignoreIncapable	true	是否忽略无法解析端点 URI 或 simple 表达式的情况。
ignoreLenientProperties	true	是否忽略使用宽松属性（lenient properties）的组件。启用后，URI 的验证会更严格，但会对因使用宽松属性而出现在 URI 中、并不属于该组件的属性报错。例如，使用 HTTP 组件在端点 URI 中提供查询参数。
ignoreDeprecated	true	是否忽略端点 URI 中使用的已废弃选项。
duplicateRouteId	true	是否验证重复的路由 ID。路由 ID 应当唯一，如果存在重复项，Camel 将无法启动。
directOrSedaPairCheck	true	是否验证 direct/seda 端点是否发送到不存在的消费者。
configurationFiles	application.properties	要验证的配置文件的位置，默认为 application.properties。多个值可用逗号分隔，并支持通配符模式匹配。
showAll	false	是否显示所有端点和 simple 表达式（包括有效和无效的）。
downloadTransitiveArtifacts	false	当声明了 sourcesArtifacts 时，可使用此标志下载传递依赖。请谨慎启用此标志，因为它会尝试下载整个依赖树。
sourcesArtifacts		包含 camel 路由的源码传递依赖列表，可用于下载项目可能依赖的、包含 camel 路由的额外依赖。
extraMavenRepositories		额外 Maven 仓库的列表。

例如，要从命令行开启忽略已弃用选项的使用，可以运行：

mvn camel-report:validate -Dcamel.ignoreDeprecated=true

请注意，-D 命令参数必须以 camel. 作为前缀，例如选项名称为 camel.ignoreDeprecated。

校验包含测试

如果你有一个 Maven 项目，那么你也可以运行该插件来校验单元测试源代码中的端点。你可以按照如下的 -D 风格传入选项：

cd myproject
mvn org.apache.camel:camel-report-maven-plugin:3.0.0:validate -Dcamel.includeTest=true

校验传递依赖中的 Apache Camel 路由

如果你的路由使用了当前项目中不存在的 direct 或 seda 端点，而这些路由声明在项目的某个依赖中，那么你可以相应地修改插件配置，使 Camel 校验插件能够将这些路由纳入考量。特别是，要让校验插件处理传递依赖，需要 sources jar 包，例如：

当前项目中定义了如下 Camel 路由 from("direct:in").to("direct:out")
路由 from("direct:out") 声明在你的某个依赖中，例如 my.company:routes-dependency:1.0
如果 routes-dependency 的源码 jar 已发布到 Maven 仓库，则可以使用如下插件配置：

<plugin>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-report-maven-plugin</artifactId>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>validate</goal>
      </goals>
      <configuration>
        <sourcesArtifacts>
          <sourcesArtifact>my.company:routes-dependency:jar:sources:1.0</sourcesArtifact>
        </sourcesArtifacts>
        <extraMavenRepositories>
          <extraMavenRepository>http://internal.repo:8080/maven</extraMavenRepository>
        </extraMavenRepositories>
      </configuration>
    </execution>
  </executions>
</plugin>

camel-report:route-coverage

用于生成 Camel 路由在单元测试中覆盖率的报告。就像你可以生成 Java 代码覆盖率报告一样，这个插件提供的是针对 Camel 路由的同类报告。因此，你可以借助它了解 Camel 路由中哪些部分已被使用，哪些尚未被使用。

Camel 在测试期间通过 JMX 采集指标数据，并据此计算路由覆盖率。你必须确保 camel-management JAR 位于 classpath 中（可以仅限测试作用域），例如在 pom.xml 文件中声明如下 Maven 依赖：

<!-- JMX is needed for route coverage testing -->
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-management</artifactId>
    <scope>test</scope>
</dependency>

	仅支持常规的 `@Test` 方法。例如，使用 `@ParameterizedTest` 可能会导致报告结果不准确。

启用路由覆盖率

在运行单元测试时，可以通过以下任一方式启用路由覆盖率：

设置全局 JVM 系统属性，为所有测试类启用
如果使用 camel-test-spring-junit5 模块，可在每个测试类上使用 @EnableRouteCoverage 注解
如果使用 camel-test 模块，可在每个测试类中重写 isDumpRouteCoverage 方法

通过 JVM 系统属性启用

你可以打开 JVM 系统属性 CamelTestRouteCoverage，为所有测试用例启用路由覆盖率。这可以在 maven-surefire-plugin 的配置中完成：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <configuration>
    <systemPropertyVariables>
      <CamelTestRouteCoverage>true</CamelTestRouteCoverage>
    </systemPropertyVariables>
  </configuration>
</plugin>

或者在运行测试时通过命令行执行：

mvn clean test -DCamelTestRouteCoverage=true

通过 @EnableRouteCoverage 注解启用

你需要在单元测试类中启用路由覆盖率。如果你使用 camel-test-spring-junit5 进行测试，可以通过在测试类上添加 @EnableRouteCoverage 注解来实现：

@CamelSpringBootTest
@SpringBootTest(classes = SampleCamelApplication.class)
@EnableRouteCoverage
public class FooApplicationTest {

通过 isDumpRouteCoverage 方法启用

不过，如果你使用的是 camel-test，并且单元测试继承了 CamelTestSupport，则可以按如下方式开启路由覆盖率统计：

仅 Java：在 CamelTestSupport 中启用路由覆盖率

@Override
public boolean isDumpRouteCoverage() {
    return true;
}

	需要进行路由覆盖率统计的路由必须分配唯一的 id，换句话说，你不能使用匿名路由。

通过 routeId 来实现：

Java
XML
YAML

from("jms:queue:cheese").routeId("cheesy")
  .to("log:foo")
  ...

<route id="cheesy">
  <from uri="jms:queue:cheese"/>
  <to uri="log:foo"/>
  ...
</route>

- route:
    id: cheesy
    from:
      uri: jms:queue:cheese
      steps:
        - to:
            uri: log:foo

生成路由覆盖率报告

使用以下命令完成单元测试后：

mvn test

然后即可运行该目标以生成路由覆盖率报告。

mvn camel-report:route-coverage

随后它会报告哪些路由缺少路由覆盖率，并精确指出对应的源代码行号：

[INFO] --- camel-camel-report-plugin:3.0.0:route-coverage (default-cli) @ camel-example-spring-boot-xml ---
[INFO] Discovered 1 routes
[INFO] Route coverage summary:

File:	src/main/resources/my-camel.xml
RouteId:	hello

  Line #      Count   Route
  ------      -----   -----
      28          1   from
      29          1     transform
      32          1     filter
      34          0       to
      36          1     to

Coverage: 4 out of 5 (80.0%)

从这里可以看到，倒数第二行中 to 那一行在计数列中的值为 0，因此未被覆盖。我们还可以看到，这是源代码文件中的第 34 行，位于 my-camel.xml XML 文件中。

选项

Maven 插件的 coverage 目标支持以下选项，这些选项既可以通过命令行配置（使用 -D 语法），也可以在 pom.xml 文件的 <configuration> 标签中定义。

参数	默认值	说明
failOnError	false	当任一路由的覆盖率未达到 100% 时，是否判定为失败。
includeTest	false	是否包含测试源代码。
includes		用于过滤 Java 和 XML 文件的名称，仅包含与给定模式列表（通配符或正则表达式）中任意一项匹配的文件。多个值可用逗号分隔。
excludes		用于过滤 Java 和 XML 文件的名称，排除与给定模式列表（通配符或正则表达式）中任意一项匹配的文件。多个值可用逗号分隔。
anonymousRoutes	false	已弃用是否允许匿名路由（未分配任何 route id 的路由）。使用 route id 可以更安全地将路由覆盖率数据与路由源代码对应起来。匿名路由用于路由覆盖率时安全性较差，因为更难确切知道测试的路由对应源代码中的哪一条路由。
generateJacocoXmlReport	false	是否生成 Jacoco XML 格式的覆盖率报告。启用后将生成文件：`target/site/jacoco/xmlJacoco.xml`
generateHtmlReport	false	是否生成 HTML 格式的覆盖率报告。启用后将生成文件：`target/site/route-coverage/html/index.html`

Camel Maven 报告插件