如何使用 gradle-pmd-plugin 将自定义 java pmd 规则添加到 gradle 项目？

Question

在处理项目arch4u-pmd 期间，我们创建了几个基于java 的pmd 规则，在基于XML 的规则集our-rules.xml 中配置它们，并将其作为普通的java lib/artifact (io.github.abc:my-pmd-rules:0.1.0) 发布到我们的工件存储库中。 工件结构如下所示：

> unzip -l my-pmd-rules-0.1.0.jar   
Archive:  my-pmd-rules-0.1.0.jar   
  Length      Date    Time    Name
---------  ---------- -----   ----
        0  02-15-2022 00:24   META-INF/
      139  02-15-2022 00:24   META-INF/MANIFEST.MF
        0  02-15-2022 00:24   io/
        0  02-15-2022 00:24   io/github/
        0  02-15-2022 00:24   io/github/rules/
        ...
     4781  02-15-2022 00:24   io/github/rules/MissingMandatoryAnnotation.class
     ...
     1138  02-15-2022 00:24   io/github/rules/our-rules.xml
     ...

我们如何使用pmd plugin 将它们添加到 Gradle 项目中？

我们必须处理以下材料/问题/答案：

1. https://stackoverflow.com/search?page=2&tab=Relevance&q=pmd%20classpath
2. ClassNotFoundException: Using custom java rule for PMD ruleset
3. Gradle's PMD plugin: what are acceptable arguments?
4. Adding a ruleset to PMD?
5. Adding custom rules in PMD - class not found issue
6. https://discuss.gradle.org/t/pmd-ruleset-not-available-in-classpath/7201
7. https://discuss.gradle.org/t/custom-rules-with-pmd-plugin/5859/4
8. How to configure PMD Auxiliary classpath in Sonar
9. https://docs.gradle.org/current/userguide/pmd_plugin.html
10. https://github.com/gradle/gradle/blob/master/subprojects/code-quality/src/main/groovy/org/gradle/api/plugins/quality/PmdPlugin.java
11. Custom PMD rule with Gradle 也不行

    tasks.withType(Pmd) {
       pmdClasspath += file("path/to/rules.jar")
    }
    

Answer 1

在 Gradle pmd 插件的官方文档中，有一个依赖部分在没有真实示例的情况下从高层次上解释了这一方面：

1. pmd - 要使用的 PMD 库
2. pmdAux - 在分析期间可用于类型解析的附加库。如果 PMD 抱怨缺少课程，这可能会很有用。

为了将自定义的 java 规则添加到您的项目中

1. 使用 Gradle 插件

   apply plugin: 'pmd'
   
   repositories {
      mavenCentral() // if your rules in Maven Central
      mavenLocal()   // if your rules is in .m2 folder 
      maven {
         // if your rules are in some custom/self-hosted artifacts repository like Nexus
      }
   }
   
   dependencies {
      ...
      pmd "io.github.abc:my-pmd-rules:0.1.0" 
      pmd "commons-io:commons-io:2.11.0"     // required dependency by pmd engine
      ...
   }
   
   pmd {
      consoleOutput = true
      ruleSetFiles = files("io/github/rules/our-rules.xml")    // exactly path as in your lib classpath
      ruleSets = []                                            // Keep it as is, workaround for pmd
   }
   

2. 使用 Maven 插件

   ...
   <build>
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-pmd-plugin</artifactId>
        <version>3.15.0</version>
        <executions>
          <execution>
            <phase>test</phase>
            <goals>
              <goal>check</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <printFailingErrors>true</printFailingErrors>
          <rulesets>
            ...
            <ruleset>io/github/rules/our-rules.xml</ruleset> <!-- exactly path as in your lib classpath -->
            ...
          </rulesets>
          <excludeRoots>
            <excludeRoot>target/generated-sources/</excludeRoot>
          </excludeRoots>
        </configuration>
        <dependencies>
          <!-- your custom rules -->
          <dependency>
            <groupId>io.github.abc</groupId>
            <artifactId>my-pmd-rules</artifactId>
            <version>0.1.0</version>
          </dependency>
        </dependencies>
      </plugin>
      ...
    </plugins>
   </build>
    ...
   

3. 如果您已经有一个规则集并且您只想包含自定义 Java 规则（来自库），您可以直接在您的规则集 xml 中按原样定义它：

     <!-- Define a rule -->
     <rule name="TheRuleName"
           language="java"
           externalInfoUrl="https://link.to.your.rule.official.docs.com"
           message="The violation message regarding your rule"
           class="io.github.rules.MissingMandatoryAnnotation">
       <priority>3</priority>
       <properties>
          ...
       </properties>
     </rule>