當今的軟體開發需要使用許多不同的工具和技術來確保代碼質量和穩定性。PMD是一個流行的靜態代碼分析工具，可以幫助開發者在編譯代碼之前發現潛在的問題。在本文中，我們將討論如何在Gradle中使用PMD，並介紹一些最佳實踐。什麼是PMD？ PMD是一個用於Java代碼的靜態代碼分析工具。它可以幫助開發者 ...

當今的軟體開發需要使用許多不同的工具和技術來確保代碼質量和穩定性。PMD是一個流行的靜態代碼分析工具，可以幫助開發者在編譯代碼之前發現潛在的問題。在本文中，我們將討論如何在Gradle中使用PMD，並介紹一些最佳實踐。

什麼是PMD？

PMD是一個用於Java代碼的靜態代碼分析工具。它可以幫助開發者找出潛在的問題，如代碼重覆、未使用的變數、錯誤的異常處理等。PMD支持多種規則，可以根據具體項目的需要進行配置。其工作原理參考How PMD Works。

PMD支持通過命令行界面（CLI, Command Line Interface for batch scripting）和其他多種集成方式，比如Maven、Gradle、Java API等等。

PMD在Gradle中配置和使用

Gradle中自帶了PMD插件，插件的預設版本可以通過源碼DEFAULT_PMD_VERSION知道。使用和配置可以參考The PMD Plugin，頁面左上角可以選擇Gradle版本，確保查看的版本和你使用的Gradle版本一致，因為很多PMD的配置屬性或者功能不一定在每個版本都有。

通過頁面左上角選了其他版本後跳轉的地址是Gradle文檔的首頁，而不是PMD插件的文檔頁。我們可以通過修改The PMD Plugin鏈接中的8.0.2為其他版本號即可跳轉到對應Gradle版本包含的PMD插件文檔的頁面。比如：

當前最新版：https://docs.gradle.org/current/userguide/pmd_plugin.html

7.3.3版本：https://docs.gradle.org/7.3.3/userguide/pmd_plugin.html

在項目build.gradle文件中增加以下內容應用插件和擴展PMD，參考Usage和Configuration，更多的配置屬性可以參考PmdExtension。

plugins {
    id 'pmd'
}

pmd {
    // 是否將 PMD 結果輸出到終端
    consoleOutput = true
    // 要使用的PMD版本
    toolVersion = "6.21.0"
    // 規則優先順序閾值，低於這個優先順序則會被忽略
    rulesMinimumPriority = 5
    // 使用的規則集配置文件路徑
    ruleSets = ["category/java/errorprone.xml", "category/java/bestpractices.xml"]
}

插件會生成兩個主要的PMD TaskpmdMain和pmdTest分別對main和test兩個項目源文件目錄使用PMD進行代碼檢查。

找到IDEA Gradle視窗 > Tasks > other，雙擊生成的Task；或者在項目根目錄運行./gradlew pmdMain都可以運行PMD。檢查結果將輸出到終端中（前提是配置了consoleOutput = true），違反了PMD規則的類會給出完整的跳轉路徑以及規則提示信息。

最後還會給出一個報告的地址，內容包含了輸出到終端的信息。Problem列出了規則的提示，點擊可以跳轉到PMD規則描述文檔對應的位置。

Gradle PMD Plugin擴展屬性

在這裡我們將PMD插件的擴展屬性作用進行說明，參考PmdExtension，這個文檔詳細說明瞭各個屬性的作用、預設值和配置示例。如果文檔描述的不是很清楚也可以參考PMD CLI options的對應描述。

consoleOutput

是否將結果輸出到終端（System.out）允許值為true|false。

ignoreFailures

如果出現了警告，是否允許繼續構建，允許值為true|false。

配置為否（false），在執行build的時候（build任務中預設包含了pmdMain和pmdTest），如果發現了代碼有違反規則，將會中斷構建過程；配置為是（true），將不會中斷構建，只是輸出報告信息。

maxFailures

停止構建前允許的最大失敗次數。

incrementalAnalysis

是否開啟增量分析，允許值為true|false。在pmd docs Incremental Analysis中詳細描述了增量分析的相關信息。簡單來說，開啟了增量分析，PMD會緩存分析數據和結果，後續分析僅查看那些新的/已更改的文件，以此顯著減少分析的時間，在Gradle中，這個功能使用PMD6.0.0及以上版本才有。

但是有一些情況會導致增量分析的緩存失效：使用PMD的版本發生了變化；使用的規則集已更改；被分析的代碼的類路徑已更改；被分析代碼依賴的庫的類路徑已更改。具體參考When is the cache invalidated?

在以上前提下，即使切換分支緩存也是有效的，甚至還支持在不同的機器重覆使用緩存文件。參考Can I reuse a cache created on branch A for analyzing my project on branch B? 和Can I reuse a cache file across different machines?

reportsDir

報告生成的路徑。

ruleSetFiles

要使用的自定義規則集文件路徑，可以在files()中填多個路徑。

ruleSetFiles = files("config/pmd/myRuleSet.xml")

ruleSetConfig

跟ruleSetFiles的作用一樣，不過只能填一個文件路徑。

ruleSetConfig = resources.text.fromFile("config/pmd/myRuleSet.xml")

ruleSets

指定使用的規則集，預設值為["category/java/errorprone.xml"]。建議如果配置了ruleSetFiles或者ruleSetConfig，就將ruleSets配置為空（ruleSets = []），以免互相干擾，官方文檔Custom ruleset給出的例子也是如此。

ruleSets = ["category/java/errorprone.xml", "category/java/bestpractices.xml"]

rulesMinimumPriority

每個規則都有個優先順序，是從 1 到 5 的整數，其中 1 是最高優先順序，參考[Message and priority overriding，每個規則的優先順序參考Java Rules。rulesMinimumPriority的作用是配置報告的最低優先順序，低於這個優先順序的規則將被忽略。比如配置rulesMinimumPriority = 4，優先順序為 5 的規則將被忽略。

sourceSets

作為 check 和 build 任務的一部分進行分析的源代碼集合，配置方式參考SourceSet。

targetJdk

PMD使用的JDK版本。有些規則可能會要求JDK的最低或者最高版本，具體要求參考Java Rules。

threads

PMD 運行時使用的線程數。

toolVersion

要使用的PMD的版本。

為項目自定義合適的規則集

規則分類和查找

PMD能檢測的語音有很多種（後面內容以Java為例），針對不同的語音，PMD內置了很多檢測規則，並歸為了以下幾個類別：

最佳實踐（Best Practices）：這些規則執行普遍接受的最佳實踐。
代碼風格（Code Style）：這些規則強制執行特定的編碼風格。
設計（Design）：幫助您發現設計問題的規則。
文檔（Documentation）：這些規則與代碼文檔有關。
容易出錯（Error Prone）：用於檢測損壞、極度混亂或容易出現運行時錯誤的構造的規則。
多線程（Multithreading）：這些是在處理多個執行線程時標記問題的規則。
性能（Performance）：標記次優代碼的規則。
安全性（Security）：標記潛在安全漏洞的規則。

在Java Rules列出了所有相關的規則，點擊藍色字元可以跳轉到規則的詳細描述頁面。

下圖是規則AbstractClassWithoutAbstractMethod文檔描述的信息，其他規則的描述可能還會包含JDK版本的要求，其他可配置屬性等等。

需要註意有的規則可能被標記為Deprecated代表被棄用了。

配置規則集

我們可以編輯XML格式的規則集文件，指定我們項目要執行的規則，參考Making rulesets。下麵是沒有包含任何規則的規則集文件的模版。

<?xml version="1.0"?>

<ruleset name="Custom Rules"
    xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd">

    <description>
        My custom rules
    </description>


    <!-- Your rules will come here -->

</ruleset>

從上文我們可以知道PMD內置的每個規則都會提供引用實例，我們引用單個規則的時候，只需要將示例的XML代碼複製到規則集文件中即可。

<rule ref="category/java/errorprone.xml/EmptyCatchBlock" />

從ref中填寫的路徑category/java/bestpractices.xml/AbstractClassWithoutAbstractMethod我們可以明顯看到它是按照內置規則集文件路徑/規則名稱的格式組織的，一個內置規則集文件對應了一個分類。

我們可以引用內置規則集文件實現批量引入分類下的所有規則，每個分類對應的XML文件名可以參考GitHub pmd-java resources。再通過exclude指定規則的名稱來排除某些規則。

<rule ref="category/java/codestyle.xml">
    <exclude name="WhileLoopsMustUseBraces"/>
    <exclude name="IfElseStmtsMustUseBraces"/>
</rule>

我們可以使用exclude-pattern排除某些文件，使其不被PMD檢查，也可以使用include-pattern包含的方式。如果兩種方式都包含相同的文件，最終這個文件會被PMD檢查。

<?xml version="1.0"?>
<ruleset name="myruleset"
		xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd">
    <description>My ruleset</description>

    <exclude-pattern>.*/some/package/.*</exclude-pattern>
    <exclude-pattern>.*/some/other/package/FunkyClassNamePrefix.*</exclude-pattern>
    <include-pattern>.*/some/package/ButNotThisClass.*</include-pattern>

    <!-- Rules here ... -->

</ruleset>

規則集文件編輯好後，使用ruleSetFiles或者ruleSetConfig配置路徑。比如下麵配置的意思是指向了項目根目錄下的/code-analysis/pmd/rulesets/custom-rule.xml。

ruleSetFiles = files("${project.rootDir}/code-analysis/pmd/rulesets/custom-rule.xml"

配置規則

規則引用的同時，我們可以覆蓋其原有的一些配置，比如提示消息message和優先順序priority。

<rule ref="category/java/errorprone.xml/EmptyCatchBlock"
      message="Empty catch blocks should be avoided" >
      <priority>5</priority>
</rule>

某些規則可能有特定的屬性，我們也可以將其覆蓋。這些特定的屬性Java Rules中都有提供，比如下麵這個例子參考NPathComplexity。

<rule ref="category/java/design.xml/NPathComplexity">
    <properties>
        <property name="reportLevel" value="150"/>
    </properties>
</rule>

有些屬性可以提供多個值，這種情況下可以通過分隔符來提供，比如豎線（|）或逗號（,）。

<property name="legalCollectionTypes"
          value="java.util.ArrayList|java.util.Vector|java.util.HashMap"/>

抑制警告

有時候PMD可能會產生誤報，這種時候我們可以通過抑制警告讓PMD跳過對這些代碼的檢查。

從Java 1.5開始可以使用註解@SuppressWarnings來標記類或者方法。

@SuppressWarnings('PMD')抑制所有PMD的警告。
@SuppressWarnings("PMD.UnusedLocalVariable")抑制規則UnusedLocalVariable的警告。
@SuppressWarnings({"PMD.UnusedLocalVariable", "PMD.UnusedPrivateMethod"})抑規則UnusedLocalVariable和UnusedPrivateMethod的警告。
@SuppressWarnings("unused")JDK裡面的unusedPMD也遵守，抑制所有跟未使用相關的警告。比如：UnusedLocalVariable和UnusedPrivateMethod。

在警告提示的代碼行的末尾加上註釋// NOPMD也可以抑制這一行引起的警告，參考NOPMD。

在規則集文件中也可以配置要抑制警告的文件，匹配的方式可以是正則表達式或者XPath，具體可以瞭解The property violationSuppressRegex和The property violationSuppressXPath。

第三方規則集

除了PMD內置的規則集，我們還可以引入第三方規則集。在3rd party rulesets中列出了一些，還有阿裡Java開發規範p3c也基於PMD開發一套規則集，從它的pom.xml可以瞭解到是基於PMD6.15.0版本。

參考Dependency management引入規則集依賴，在規則集配置中引入提供的規則即可。

dependencies {
		pmd "com.alibaba.p3c:p3c-pmd:2.1.1"
}

需要註意的是，第三方的規則集很可能沒有按照PMD內置規則集那樣分類，它們提供的規則配置文件目錄也可能不一樣，比如p3c的規則配置文件都在/resources/rulesets/目錄下並獨自定義了一套分類。

其他技巧

PMD的最新官方文檔地址是：https://docs.pmd-code.org/latest/pmd_userdocs_tools.html。鏈接中的latest對應了版本號，指向的是當前最新版本，如果想查看其他版本的文檔，修改為對應的版號即可。比如6.39.0版本的鏈接為：https://docs.pmd-code.org/pmd-doc-6.39.0/index.html。不過可能只有比較新的一些版本才能看到對應的文檔。

官方提供了一個PMD的最佳實踐可以瞭解下。

PMD還有跟特定語言相關的文檔，比如Java support，裡面有支持的JDK版本等信息。

如果使用過程中遇到了問題，可以參考Getting Help從這些網站裡面尋找幫助github discussions、github issues、stackoverflow tagged pmd。

PMD官方文檔還提供了Copy/Paste Detector (CPD)關信息，CPD可以用於檢測重覆代碼。還提及了Duplicate Code教我們遇到重覆代碼如何消除，以及一個關於設計模式的網站Design Patterns。

關於PMD這個名字，並沒有特殊的含義，作者純粹只是覺得這幾個字母放一起作為名稱挺好的，來自What does 'PMD' mean?

參考

GitHub - pmd

PMD - docs

Gradle - The PMD Plugin

提高代碼質量！詳解在Gradle項目中使用PMD的正確姿勢