如果你需要一個自動化的工具幫助你或者你的團隊發現代碼中的缺陷,在提升代碼質量同時減少人工Code Review的成本,那這篇文章非常的適合你。 ...
如果你需要一個自動化的工具幫助你或者你的團隊發現代碼中的缺陷,在提升代碼質量同時減少人工Code Review的成本,那這篇文章非常的適合你。本文圍繞SpotBugs與Gradle集成,將相關配置和使用進行了詳細介紹,並提供了各種能夠為你的項目定製化配置的手段。來源和出處都已在文中關鍵處以超鏈接給出,盡情享受吧。
SpotBugs是什麼?
SpotBugs是一個開源的Java靜態分析工具,旨在幫助開發人員檢測代碼中的潛在缺陷和漏洞。SpotBugs可以通過掃描Java位元組碼來發現潛在的問題,例如空指針引用、類型轉換錯誤、未使用的變數等等。它還可以檢測代碼中的潛在安全漏洞,例如SQL註入、XSS攻擊等。SpotBugs提供了一個用戶友好的GUI和命令行介面,可以輕鬆地與各種構建工具和IDE集成,例如Ant、Maven、Gradle、Eclipse和IntelliJ IDEA。SpotBugs還支持插件和自定義規則,使得開發人員可以根據項目的特定需求和標準對其進行定製化配置。更多詳細信息可以查看SpotBugs官方文檔。
SpotBugs是FindBugs的一個分支,它在FindBugs的基礎上進行了改進和升級,它使用了更先進的演算法和技術來提高分析的準確性和效率。SpotBugs還添加了對新的Java版本的支持,例如Java 8和Java 11。SpotBugs還提供了更好的用戶界面和命令行界面,並支持更多的構建工具和IDE集成。
FindBugs也是一款非常流行的Java靜態分析工具,但是已經停止更新。停更的原因似乎是項目擁有者不願繼續在這個項目上花時間,代碼貢獻者因為沒有許可權也無法繼續迭代和發佈新的版本,在FindBugs GitHub首頁的README文件中提供了兩個文檔項目狀態 2016-November和項目狀態 2017-September,裡面講述了代碼貢獻者當時的一些擔憂和無奈。
SpotBugs與Gradle集成
開始之前先簡單介紹下本文中將會提到的幾個依賴以及它們之間的關係,以便於理解後續內容:
com.github.spotbugs.snom:spotbugs-gradle-plugin
是一個Gradle插件,它將SpotBugs集成到 Gradle構建中,生成SpotBugsTask並可以通過配置屬性來擴展。com.github.spotbugs:spotbugs
這個依賴基本包含了所有SpotBugs檢測器,這些檢測器實現了Bug descriptions中提到的相關Bug檢測項的邏輯。com.h3xstream.findsecbugs:findsecbugs-plugin
在com.github.spotbugs:spotbugs
的基礎上增加了安全相關的檢查器也就是Bug descriptions#Security中描述的相關檢查項。com.github.spotbugs:spotbugs-annotations
是Spotbugs的一個擴展/輔助工具,開發者使用這裡面註解可以讓Spotbugs按照我們的意圖來檢查代碼。
spotbugs-gradle-plugin
spotbugs-gradle-plugin是一個Gradle插件,它將SpotBugs集成到Gradle構建中,生成SpotBugsTask並提供相關配置來擴展,運行SpotBugsTask就可以執行檢查,生成報告等。
預設情況下,這個插件裡面已經包含了一個spotbugs,所以應用了這個插件後一般無需在另外添加com.github.spotbugs:spotbugs
。從SpotBugs version mapping中可以知道spotbugs-gradle-plugin不同版本中預設包含的spotbugs版本之間的關係,比如:com.github.spotbugs.snom:spotbugs-gradle-plugin:5.0.13
包含了com.github.spotbugs:spotbugs:4.7.3
。
SpotBugs Gradle插件要求Gradle版本為7.0或者更高,JDK版本為1.8或者更高。
這個插件會為每個sourceSets生成SpotBugsTask。例如項目中有兩個sourceSets main和test,插件將生成兩個SpotBugsTask(spotbugsMain和spotbugsTest)。
如果不想自動生成SpotBugsTask,可以使用SpotBugs Base插件從頭開始配置,參考com.github.spotbugs-base。
生成的SpotBugsTask執行時需要編譯後的.class文件作為輸入,因此它們將在Java編譯後運行。SpotBugs Gradle增加了check相關的任務依賴,所以簡單的運行./gradlew check
也會執行生成的SpotBugsTask。
參考com.github.spotbugs在build.gradle文件中增加以下內容來引入SpotBugs Gradle插件:
buildscript {
repositories {
maven {
url "https://plugins.gradle.org/m2/"
}
}
dependencies {
classpath "com.github.spotbugs.snom:spotbugs-gradle-plugin:5.0.13"
}
}
apply plugin: "com.github.spotbugs"
插件裡面提供了很多可選的屬性來配置或者擴展插件的行為。
下麵展示了在build.gradle文件增加spotbugs{}
相關屬性的例子,詳細信息可以參考SpotBugsExtension,這裡面有每個屬性作用、可指定的值和其他相關信息。spotbugs{}
中指定的大部分屬性將作為生成的SpotBugsTask配置的預設值,意味著可以通過spotbugs{}
給所有SpotBugsTask配置屬性。
spotbugs {
ignoreFailures = false
showStackTraces = true
showProgress = false
reportLevel = 'default'
effort = 'default'
visitors = [ 'FindSqlInjection', 'SwitchFallthrough' ]
omitVisitors = [ 'FindNonShortCircuit' ]
reportsDir = file("$buildDir/reports/spotbugs")
includeFilter = file('spotbugs-include.xml')
excludeFilter = file('spotbugs-exclude.xml')
onlyAnalyze = ['com.foobar.MyClass', 'com.foobar.mypkg.*']
projectName = name
release = version
extraArgs = [ '-nested:false' ]
jvmArgs = [ '-Duser.language=ja' ]
maxHeapSize = '512m'
}
除了上述方式外,還可直接配置SpotBugsTask,以設置某個任務特定的屬性,比如下麵為名為spotbugsMain的任務單獨進行了設置,跟spotbugs{}
同名的屬性將被覆蓋,詳細信息參考SpotBugsTask。
spotbugsMain {
sourceDirs = sourceSets.main.allSource.srcDirs
classDirs = sourceSets.main.output
auxClassPaths = sourceSets.main.compileClasspath
reports {
html {
required = true
outputLocation = file("$buildDir/reports/spotbugs/main/spotbugs.html")
stylesheet = 'fancy-hist.xsl'
}
}
ignoreFailures = false
showStackTraces = true
showProgress = false
reportLevel = 'default'
effort = 'default'
visitors = [ 'FindSqlInjection', 'SwitchFallthrough' ]
omitVisitors = [ 'FindNonShortCircuit' ]
reportsDir = file("$buildDir/reports/spotbugs")
includeFilter = file('spotbugs-include.xml')
excludeFilter = file('spotbugs-exclude.xml')
baselineFile = file('spotbugs-baseline.xml')
onlyAnalyze = ['com.foobar.MyClass', 'com.foobar.mypkg.*']
projectName = name
release = version
extraArgs = [ '-nested:false' ]
jvmArgs = [ '-Duser.language=ja' ]
maxHeapSize = '512m'
}
後面將會有一段描述比較常用或者重要的屬性。
com.github.spotbugs:spotbugs
因為spotbugs-gradle-plugin中已經包含了spotbugs,所以一般情況下不需要再單獨引入這個依賴。不過可能因為預設帶的版本有Bug、需要跟IDEA的SpotBugs插件使用相同的版本,又或者新版本的檢測器新加了實用的檢測項等原因我們會需要單獨指定版本,下麵提供了兩種方式實現。
在配置spotbugs-gradle-plugin的時候通過toolVersion
指定spotbugs版本。
spotbugs {
toolVersion = '4.7.3'
}
在dependencies
添加依賴並指定依賴版本。
dependencies {
spotbugs 'com.github.spotbugs:spotbugs:4.7.3'
}
findsecbugs-plugin
findsecbugs-plugin是Spotbugs的安全漏洞檢測插件。它在spotbugs的基礎上增加了自己的規則集,專註於檢測安全相關的問題,例如密碼泄漏、SQL 註入、XSS 等,也就是Bug descriptions#Security中描述的相關檢查項。
dependencies {
spotbugsPlugins 'com.h3xstream.findsecbugs:findsecbugs-plugin:1.12.0'
}
spotbugs-annotations
spotbugs-annotations是Spotbugs的一個擴展/輔助工具,裡面提供了很多註解,我們可以在編碼時將它們加在被檢測代碼的相應位置(如屬性、方法、形參、本地變數),讓Spotbugs按照我們的意圖來檢查代碼,以便SpotBugs可以更恰當地發出警告。在Annotations中列舉了所有註解,需要註意裡面有很多已經標記為Deprecated表明已經棄用了。
比如下麵這段代碼,只是輸出value到終端,即使test()傳入null也不會導致空指針。Spotbugs本來不會發出警告,但是由於我們在方法上加了註解edu.umd.cs.findbugs.annotations.NonNull
,Spotbugs會按照我們的意圖進行入參不允許為null的校驗,從而發出警告。
import edu.umd.cs.findbugs.annotations.NonNull;
public class SpotbugsAnnotationsSample {
public static void main(String[] args) {
test(null);
}
public static void test(@NonNull Integer value) {
// 輸出到終端
System.out.println(value);
}
}
下麵是引入這個依賴的例子,參考Refer the version in the build script,這裡面還提到從spotbugs v4版本開始,spotbugs.toolVersion
由 String
變為 Provider<String>
,所以請使用 get()
或其他方式引用實際版本。
dependencies {
compileOnly "com.github.spotbugs:spotbugs-annotations:${spotbugs.toolVersion.get()}"
}
SpotBugs Gradle擴展屬性
includeFilter和excludeFilter
過濾器(Filter file)文件可以定義匹配檢測項、被檢查的類和被檢查方法的一套匹配規則,讓我們可以為項目做定製化。文件配置好後,使用SpotBugsTask提供的屬性指定過濾器文件的路徑,實現包含(includeFilter
)或者排除(excludeFilter
)匹配的內容。
文件是xml格式的,每個匹配規則單獨寫在<Match></Match>
中,使用Types of Match clauses描述的各種標簽組合成匹配規則的內容,在Examples中給出了很多例子作為參考。
我們重點關註下category、code、pattern
來指定Bug descriptions中列出來的檢查項,多個參數用逗號分隔,也可以使用正則表達式,以~
字元開頭。
每個檢查項有唯一的pattern
,比如下圖中的XSS_REQUEST_PARAMETER_TO_SEND_ERROR
和XSS_REQUEST_PARAMETER_TO_SERVLET_WRITER
;多個檢查項可能屬於同一個code
,比如下圖中的XSS
;多個不同的code
可能屬於同一個category
。這三者之間是一個清晰的層級關係,這樣就可以按不同的粒度來配置。
下麵給出了一個使用<Bug>
簡單的例子和描述,更多例子請參考Examples。
<!--匹配指定的這兩個檢查項-->
<Match>
<Bug pattern="XSS_REQUEST_PARAMETER_TO_SEND_ERROR,XSS_REQUEST_PARAMETER_TO_SERVLET_WRITER" />
</Match>
<!--匹配所有code為XSS的檢查項-->
<Match>
<Bug code="XSS" />
</Match>
<!--匹配SECURITY目錄下所有檢查項-->
<Match>
<Bug category="SECURITY" />
</Match>
visitors和omitVisitors
這兩個屬性可以分別指定使用(visitors
)和禁用(omitVisitors
)檢查器,一個檢查器會包含一個或者多個Bug descriptions中提到的檢查項,所以這兩個屬性配置的目的和includeFilter
和excludeFilter
是一樣的,讓我們可以為項目做定製化,只是從檢查器的維度進行配置。
在Detectors中將Spotbugs所有的檢查器都列出來了,在不配置的情況下,Standard detectors中列出來的預設使用,Disabled detectors中列出來的預設禁用。
以檢查器SynchronizationOnSharedBuiltinConstant為例,從下圖我們可以看到,檢查器名稱下麵有段簡短的描述,再往下將檢查器包含的檢查項都列出來了,可以看到上文提到的pattern
和code
,點擊可以跳轉到Filter file文檔相應的位置。我們配置visitors
和omitVisitors
的時候填檢查器的名字SynchronizationOnSharedBuiltinConstant
即可。
effort
effort
是配置代碼檢測預期的級別,級別由低到高分別為min、less、more、max
,級別越高計算成本越高,花費的時間也就越長,在這個文檔Effort裡面有表格清晰的列出了這幾個級別分別包含了哪些檢查內容。effort
的預設值是default
,等同於more
。
jvmArgs
jvmArgs
用於設置JVM參數,因為SpotBugs是Java寫的,自然要在JVM上運行。我們在例子裡面看到了-Duser.language=ja
,這個意思是設置語言為日語,也就是代碼分析的結果展示的語音(輸出到終端或者報告中)。總共有英語(en 預設),日語(ja),法語(fr)三種,在GitHub中可以看到相關展示文本的配置文件。
maxHeapSize
maxHeapSize
是設置JVM最大堆記憶體大小,在spotbugsextension#maxHeapSizea中說了預設值為空,因此會使用Gradle的預設配置,所以一般不用管。
onlyAnalyze
onlyAnalyze
指定哪些代碼要被SpotBugs分析,在大型項目裡面用這個屬性避免沒必要的分析,可能會大大減少運行分析所需的時間。可以指定類名,或者包名,指定包名的時候用.*
和.-
的作用一樣,意思是分析這個包下以及子包中的文件。
onlyAnalyze = ['com.foobar.MyClass', 'com.foobar.mypkg.*']
reportLevel
SpotBugs按嚴重程度高到低將Bug分為了三個等級P1、P2和P3,reportLevel屬性指明達到哪個等級的Bug才需要展示在報告裡面,它可配置值對應有HIGH、MEDIUM、LOW
和DEFAULT
,它們定義在Confidence.groovy中。預設值是DEFAULT
等同於MEDIUM
,意思是要達到P2級別,那就意味著低級別的P3 Bug將被忽略,
reports
reports
配置報告的類型,有html、xml、sarif和text四種,配置在SpotBugsTask中(比如spotbugsMain {}
),再往裡一層可配置的屬性不是很多,參考SpotBugsReport。下麵是html類型報告的配置示例:
spotbugsMain {
reports {
html {
required = true
outputLocation = file("$buildDir/reports/spotbugs/main/spotbugs.html")
stylesheet = 'fancy-hist.xsl'
}
}
}
最佳實踐
配置
在根目錄gradle.properties中配置版本。
spotbugsGradlePluginVersion=5.0.13
findsecbugsPluginVersion=1.12.0
在根目錄build.gradle中增加以下配置:
buildscript {
repositories {
mavenLocal()
maven {
url "https://plugins.gradle.org/m2/"
}
mavenCentral()
}
dependencies {
classpath "com.github.spotbugs.snom:spotbugs-gradle-plugin:${spotbugsGradlePlugin}"
}
}
apply plugin: "com.github.spotbugs"
repositories {
mavenLocal()
maven {
url "https://plugins.gradle.org/m2/"
}
mavenCentral()
}
dependencies {
compileOnly "com.github.spotbugs:spotbugs-annotations:${spotbugs.toolVersion.get()}"
spotbugsPlugins "com.h3xstream.findsecbugs:findsecbugs-plugin:${findsecbugsPluginVersion}"
}
spotbugs {
ignoreFailures = false
showStackTraces = false
showProgress = false
excludeFilter = file("${project.rootDir}/code-analysis/spotbugs/exclude-filter.xml")
extraArgs = [ '-nested:false' ]
}
spotbugsMain {
reports {
html {
required = true
stylesheet = 'fancy-hist.xsl'
}
}
}
如果是多模塊項目按這種方式配置:
buildscript {
repositories {
mavenLocal()
maven {
url "https://plugins.gradle.org/m2/"
}
mavenCentral()
}
dependencies {
classpath "com.github.spotbugs.snom:spotbugs-gradle-plugin:${spotbugsGradlePlugin}"
}
}
allprojects {
apply plugin: "com.github.spotbugs"
repositories {
mavenLocal()
maven {
url "https://plugins.gradle.org/m2/"
}
mavenCentral()
}
dependencies {
compileOnly "com.github.spotbugs:spotbugs-annotations:${spotbugs.toolVersion.get()}"
spotbugsPlugins "com.h3xstream.findsecbugs:findsecbugs-plugin:${findsecbugsPluginVersion}"
}
spotbugs {
ignoreFailures = false
showStackTraces = false
showProgress = false
excludeFilter = file("${project.rootDir}/code-analysis/spotbugs/exclude-filter.xml")
extraArgs = ['-nested:false']
}
spotbugsMain {
reports {
html {
required = true
stylesheet = 'fancy-hist.xsl'
}
}
}
}
在項目根目錄下創建排除檢查項的文件/code-analysis/spotbugs/exclude-filter.xml
,後期再根據需要配置。
<?xml version="1.0" encoding="UTF-8"?>
<FindBugsFilter
xmlns="https://github.com/spotbugs/filter/3.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://github.com/spotbugs/filter/3.0.0 https://raw.githubusercontent.com/spotbugs/spotbugs/3.1.0/spotbugs/etc/findbugsfilter.xsd">
</FindBugsFilter>
使用
在Gradle視窗中雙擊運行spotbugsMain任務即可,檢測完成會在Run視窗中列印出報告地址。
也可以在Terminal視窗中執行./gradlew spotbugsMain
,可能需要先執行chmod +x gradlew
給gradlew文件執行許可權。
如果執行過程中發生類似下麵這種異常可以不用管,只是有部分相關的分析會無法執行,並不會中斷整個過程,其他不相關的部分都會正常檢查完成。在GitHub上issues#527很多人反映了這個問題,但是暫時沒有完美的解決。
The following classes needed for analysis were missing:
apply
test
accept
解讀報告
報告概要(Summary)按包和BUG等級統計了數量。
按目錄瀏覽(Browse by Categories)將發現的缺陷代碼按檢查項中的category、code、pattern
分層展示。
按包名瀏覽(Browse by Packages)就是換了個角度,按照包名 > 類名 > 檢查項pattern
分層展示。
最後一個視窗Info展示分析的代碼文件(Analyzed Files)、分析的源文件夾(Source Files)使用的依賴(Used Libraries)、使用到的SpotBugs插件(Plugins)和分析中產生的異常(Analysis Errors)。
過濾配置
通過includeFilter
和excludeFilter
指定過濾器(Filter file)文件是最靈活的,基本什麼維度都可以控制。但是建議這裡面只配置要包含或者排除哪些檢查項,使用category、code、pattern
配置不同的粒度。
從整體縮小被檢查的代碼範圍使用onlyAnalyze
,如果有必要的話。如果要忽略不檢查具體的類或者方法可以使用註解@SuppressFBWarnings來標記,它來自spotbugs-annotations。
其他技巧
SpotBugs Links裡面列出了跟SpotBugs集成或者相似的工具,有需要可以瞭解下。
參考
[GitHub]spotbugs-gradle-plugin