使用Gmavenplus与Groovydoc生成Java Records文档失败求助

先搞定语言级别配置 #

别只单独设置languageLevel，得确保gmavenplus-plugin同时匹配Java和Groovy的版本，不然解析时会出现兼容问题。给个完整的配置示例：

<plugin>
  <groupId>org.codehaus.gmavenplus</groupId>
  <artifactId>gmavenplus-plugin</artifactId>
  <version>4.2.1</version>
  <executions>
    <execution>
      <goals>
        <goal>groovydoc</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <javaVersion>17</javaVersion>
    <groovyVersion>4.0.0</groovyVersion> <!-- 必须用支持Java 17的Groovy版本，比如4.x系列 -->
    <languageLevel>17</languageLevel>
    <sources>
      <source>
        <directory>src/main/java</directory>
        <includes>
          <include>**/*.java</include>
        </includes>
      </source>
      <source>
        <directory>src/main/groovy</directory>
        <includes>
          <include>**/*.groovy</include>
        </includes>
      </source>
    </sources>
  </configuration>
</plugin>

处理参数类型不匹配的报错 #

这个问题多是Groovydoc解析Java Record时的类型映射bug，给两个可行方案：

方案1：分开生成Java和Groovy文档 #

用maven-javadoc-plugin专门生成Java的Javadoc，让gmavenplus只处理Groovy文件，避免冲突：

• 先加Java文档生成插件：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.5.0</version>
  <executions>
    <execution>
      <goals>
        <goal>javadoc</goal>
      </goals>
      <configuration>
        <source>17</source>
      </configuration>
    </execution>
  </executions>
</plugin>

• 然后修改gmavenplus的配置，移除Java源目录的包含：

<sources>
  <source>
    <directory>src/main/groovy</directory>
    <includes>
      <include>**/*.groovy</include>
    </includes>
  </source>
</sources>

方案2：升级gmavenplus-plugin版本 #

旧版本的插件可能存在Java Record的解析漏洞，试试升级到最新兼容版本（比如4.3.2）：

<plugin>
  <groupId>org.codehaus.gmavenplus</groupId>
  <artifactId>gmavenplus-plugin</artifactId>
  <version>4.3.2</version> <!-- 替换为最新稳定版 -->
  <!-- 其余配置保持不变 -->
</plugin>

最后检查环境一致性 #

• 执行mvn -v确认Maven用的JDK是17版本；
• 跑mvn clean install -U清理缓存重新构建，避免旧编译文件搞事情。

内容的提问来源于stack exchange，提问作者Liviu Carausu