技術文章 » 提高程式碼質量！詳解在Gradle專案中使用PMD的正確姿勢

提高程式碼質量！詳解在Gradle專案中使用PMD的正確姿勢

2023-04-10 06:05:15

當今的軟體開發需要使用許多不同的工具和技術來確保程式碼質量和穩定性。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內建了很多檢測規則，並歸為了以下幾個類別：

  1. 最佳實踐（Best Practices）：這些規則執行普遍接受的最佳實踐。
  2. 程式碼風格（Code Style）：這些規則強制執行特定的編碼風格。
  3. 設計（Design）：幫助您發現設計問題的規則。
  4. 檔案（Documentation）：這些規則與程式碼檔案有關。
  5. 容易出錯（Error Prone）：用於檢測損壞、極度混亂或容易出現執行時錯誤的構造的規則。
  6. 多執行緒（Multithreading）：這些是在處理多個執行執行緒時標記問題的規則。
  7. 效能（Performance）：標記次優程式碼的規則。
  8. 安全性（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