Camel YAML DSL 验证 Maven 插件

Camel YAML DSL 验证 Maven 插件支持以下目标

camel-yaml-dsl-validator:validate - 根据规范验证 YAML 路由是否正确
camel-yaml-dsl-validator:generate-doc-samples - Camel 构建时用于从文档生成 AI 工具的 YAML 示例

camel-yaml-dsl-validator:validate

用于根据生成的 YAML DSL JSON Schema 验证 YAML 路由。

诸如自定义 YamlDeserializerResolver 实现之类的运行时扩展不会被添加到该 Schema 中，因此 validate 目标不接受模块提供的自定义 YAML 步骤名称。该 Maven 插件不会运行 Camel 的 YAML 路由加载器，也不会加载自定义解析器。对于这类路由，除使用该 Schema 验证外，还应使用运行时路由加载测试。

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

mvn camel-yaml-dsl-validator:validate

你还可以启用该插件，使其作为构建过程的一部分自动运行，以便捕获这些错误。

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

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

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

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

在任意 Maven 项目上运行该目标

你也可以在任意 Maven 项目上运行 validate 目标，而不必将该插件添加到 pom.xml 文件中。这样做需要使用插件的全限定名称来指定它。例如，要在 Apache Camel 的 main-yaml 项目上运行该目标，可以执行

cd main-yaml
mvn org.apache.camel:camel-yaml-dsl-validator-maven-plugin:4.18.0:validate

例如，它会输出如下内容（此处强制产生一个错误）

[INFO] --- camel-yaml-dsl-validator:4.18.0:validate (default-cli) @ camel-example-main-yaml ---
[INFO] Found [/Users/davsclaus/workspace/camel-examples/main-yaml/src/main/resources/routes/my-route.camel.yaml] YAML files ...
[INFO] Validating 1 YAML files ...
[WARNING]

Validation error detected in 1 files

    File: my-route.camel.yaml
        /0/route/from: property 'step' is not defined in the schema and the schema does not allow additional properties
        /0/route/from: required property 'steps' not found

选项

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

参数	默认值	描述
skip	false	跳过校验执行。
failOnError	false	当发现无效的 Camel 端点时是否导致构建失败。默认情况下，插件会以 WARN 级别记录这些错误。
includeTest	false	是否包含测试源代码。
includes		用于过滤 YAML 文件名，只包含与给定模式列表（通配符和正则表达式）中任意一个匹配的文件。多个值可用逗号分隔。
excludes		用于过滤 YAML 文件名，排除与给定模式列表（通配符和正则表达式）中任意一个匹配的文件。多个值可用逗号分隔。
onlyCamelYamlExt	false	是否只接受文件名为 xxx.camel.yaml 的文件。默认情况下，接受所有 .yaml 文件。
directories		用于扫描 YAML 文件的额外目录。默认情况下，只扫描项目的资源目录。

例如，要排除某个特定文件：

mvn camel-yaml-dsl-validator:validate -Dcamel.excludes=cheese.yaml

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

使用附加目录进行校验

如果您的 YAML 路由文件存放在标准 Maven 资源目录之外的位置，可以指定附加的扫描目录：

<plugin>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-yaml-dsl-validator-maven-plugin</artifactId>
  <executions>
    <execution>
      <configuration>
        <directories>
          <directory>src/main/routes</directory>
          <directory>src/main/camel</directory>
        </directories>
      </configuration>
      <phase>process-classes</phase>
      <goals>
        <goal>validate</goal>
      </goals>
    </execution>
  </executions>
</plugin>

支持相对路径和绝对路径。相对路径基于项目根目录进行解析。

校验 include 测试

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

cd myproject
mvn org.apache.camel:camel-yaml-dsl-validator:4.18.0:validate -Dcamel.includeTest=true

camel-yaml-dsl-validator:generate-doc-samples

该目标由 Camel 构建本身在 camel-jbang-core 中使用，并非面向最终用户。

它会读取 EIP 文档和用户手册中的 [source,yaml] 路由示例，依据 YAML DSL JSON Schema 对每一个示例进行校验，一旦有示例校验失败便使构建失败。通过校验的示例会写入 eip-samples.json，并以其所展示的 EIP 或文件条目作为键（split、onException、rest、beans 等）。当所使用的目录中没有某个名称对应的文档时，Camel JBang MCP 服务器（以及 Camel TUI）的 camel_catalog_sample 工具就会将这些内容作为后备数据返回。

这些页面在 camel-jbang-core 的 pom.xml 中进行配置：示例作为某个文件条目样本的用户手册页面（pages）、示例以给定条目开头的页面即为该条目的样本（entryPages），以及因为故意展示旧语法而不参与校验的用户手册页面（excludes，例如升级指南）。EIP 文档的每一页都会被读取，并以其文件名作为键。

Camel Maven YAML DSL 验证器插件