則全解析：從語法樹分析到CI門禁落地)
簡介SonarQube自定義Java規(guī)則集壓縮包面向使用SonarQube平臺進(jìn)行Java代碼質(zhì)量治理的開發(fā)團(tuán)隊與技術(shù)負(fù)責(zé)人。壓縮包源自一個IntelliJ IDEA工程包含自定義規(guī)則核心邏輯的Java源碼、Maven構(gòu)建配置pom.xml、build.sh構(gòu)建腳本、README文檔以及編譯產(chǎn)物等通過這套規(guī)則可在標(biāo)準(zhǔn)SonarQube規(guī)則集之外針對項目特定編碼規(guī)范與業(yè)務(wù)場景做更細(xì)致的靜態(tài)檢查。包體共485個文件以xml配置、java源碼、jar依賴、class字節(jié)碼為主要構(gòu)成同時涵蓋json、html、png、md等輔助資源整體壓縮包約747MB目錄結(jié)構(gòu)完整包含Git版本庫元數(shù)據(jù)便于學(xué)習(xí)者查看規(guī)則實現(xiàn)與構(gòu)建打包流程。目前已有591人學(xué)習(xí)下載適合正在開發(fā)Sonar插件、希望擴(kuò)展CI流水線中代碼檢查能力的中高級Java開發(fā)人員。1. 自定義 Sonar 規(guī)則的現(xiàn)實意義為什么團(tuán)隊需要 sonar-java-custom-rules.zip當(dāng)團(tuán)隊規(guī)模越過十人、代碼庫超過幾十萬行時發(fā)版前的 Code Review 已經(jīng)攔不住所有問題。SonarQube 內(nèi)置的 Java 規(guī)則覆蓋了典型的壞味道、漏洞和重復(fù)度但業(yè)務(wù)團(tuán)隊的規(guī)范往往不在其中——比如禁止在事務(wù)方法里調(diào)用遠(yuǎn)程接口、DTO 不允許直接傳給 DAO、日志必須帶 traceId。這些規(guī)范寫進(jìn)文檔沒人看寫進(jìn) Checkstyle 又和 Sonar 平臺割裂。sonar-java-custom-rules.zip 這一類項目產(chǎn)物本質(zhì)上是把團(tuán)隊自己的 Java 編碼規(guī)范編譯進(jìn) SonarQube 分析引擎讓機(jī)器在每次構(gòu)建時替人做規(guī)則審查。它的價值不是“多寫幾個規(guī)則”而是把規(guī)則從口頭約定變成自動門禁。這篇文章會帶你把這份壓縮包從“解壓后不知道先看哪個文件”走到“能寫出自己的規(guī)則并跑通全流程”。內(nèi)容覆蓋環(huán)境搭建、規(guī)則編寫三個核心步驟、調(diào)試技巧、回歸測試方法以及我在實際部署中踩過的坑。新手可以按章節(jié)順序操作熟手可以直接跳到第四章和第五章看參數(shù)與邊界問題。2. 從壓縮包到可運行規(guī)則包環(huán)境準(zhǔn)備與最小復(fù)現(xiàn)2.1 先看清 sonar-java-custom-rules.zip 里應(yīng)該有什么一個典型的 Sonar Java 自定義規(guī)則工程解壓后目錄結(jié)構(gòu)大致如下注意這不是我虛構(gòu)的而是社區(qū)里此類項目的通用布局sonar-java-custom-rules/ ├── pom.xml ├── src/ │ ├── main/java/com/example/rules/ │ │ ├── MyJavaRulesPlugin.java │ │ ├── rules/ │ │ │ ├── AvoidUsingForLoopRule.java │ │ │ └── ... │ ├── main/resources/ │ │ └── com/example/rules/ │ │ ├── sonar-way.json │ │ └── sonar-way-profile.json │ └── test/java/com/example/rules/ │ └── rules/ │ ├── AvoidUsingForLoopRuleTest.java │ └── ... └── target/ 構(gòu)建產(chǎn)物通常是 sonar-java-custom-rules-1.0.0.jar這里的pom.xml是骨架它決定了這個工程依賴哪個 SonarQube API 版本以及打出來的 jar 包是否能在你的 SonarQube 服務(wù)器上運行。社區(qū)里最常見的父 POM 坐標(biāo)是org.sonarsource.java:java-custom-rules-parent版本對應(yīng)你 SonarQube 的 Java Plugin 版本例如 SonarQube 9.9 LTS 對應(yīng)java-plugin-api 9.9.x。如果你手頭的 pom 里依賴是 6.x 或 7.x大概率是給老版 SonarQube 用的強(qiáng)行裝到新版服務(wù)器會直接報NoClassDefFoundError。sonar-way.json這個文件容易被忽略它決定規(guī)則默認(rèn)是否啟用。active: true表示規(guī)則在 Quality Profile 里默認(rèn)勾選false則需要在界面手動啟用。文件名里的sonar-way只是一種約定不是必須叫這個真正決定規(guī)則歸屬的是 json 里的規(guī)則key和name。2.2 環(huán)境準(zhǔn)備JDK 版本與 Maven 配置開頭先說明我這里說的環(huán)境不是 SonarQube 服務(wù)器而是你用來構(gòu)建規(guī)則包的開發(fā)機(jī)。自定義規(guī)則工程是個標(biāo)準(zhǔn) Maven 項目所以本地只需要 JDK 和 Maven。需要特別強(qiáng)調(diào)的是 JDK 版本——SonarQube Java Plugin 從 7.x 開始要求 JDK 11 才能編譯自定義規(guī)則而 SonarQube 9.9 LTS 本身需要 JDK 17 才能運行。我見到大量“編譯通過但裝不上”的翻車現(xiàn)場本質(zhì)是本地用了 JDK 8或 Maven 用的 toolchain 指向了舊版本。一個穩(wěn)妥的做法是在pom.xml的properties里顯式聲明properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties然后本地確認(rèn)版本java -version # 期望輸出包含 openjdk 17.x 等字樣 mvn -version # 期望輸出包含 Apache Maven 3.8.x 或更高版本這一步失敗的常見表現(xiàn)是 Maven 編譯時報錯UnsupportedClassVersionError或invalid source release: 17。前者說明你的JAVA_HOME指向了 JDK 8/11后者說明 pom 里寫的 source/target 比你當(dāng)前 JDK 版本新。記住一條原則pom 里的編譯參數(shù)必須小于等于本地 JAVA_HOME 的 JDK 版本但編譯參數(shù)的最低要求是 11對應(yīng)老 SonarQube或 17對應(yīng)新 SonarQube。這里的 java 環(huán)境變量配置是后續(xù)所有操作的地基地基不穩(wěn)后面全部白費。2.3 直接構(gòu)建并確認(rèn) jar 包可加載當(dāng)目錄結(jié)構(gòu)完整且 pom 無報錯時可以直接構(gòu)建驗證。在工程根目錄執(zhí)行mvn clean package -DskipTests執(zhí)行后target/下會生成sonar-java-custom-rules-1.0.0.jar。注意這里我刻意用了-DskipTests不是因為測試不重要而是為了先確認(rèn)編譯鏈路通。等規(guī)則代碼寫好后測試環(huán)節(jié)必須完整跑一遍。接下來進(jìn)入“部署到 SonarQube”的步驟。把 jar 拷貝到 SonarQube 服務(wù)器的extensions/plugins/目錄重啟 SonarQube或者如果你用的是 Docker 部署需要把 jar 重新打進(jìn)容器鏡像里。重啟后到Administration - Marketplace - Plugins里搜索你的插件名通常是MyJavaRules確認(rèn)狀態(tài)是 “Installed” 而不是 “Uninstalled”然后到 Quality Profiles 界面把對應(yīng)規(guī)則激活。這里有一個非常容易讓人蒙圈的細(xì)節(jié)SonarQube 不會因為 jar 加載失敗就拒絕啟動它只是讓你看不到規(guī)則然后在日志里打一條 WARN。所以你以為“裝好了”實際規(guī)則列表里什么都沒有。這時候要去看logs/sonar.log它里面會明文說哪個 jar 缺少依賴或版本不兼容。2.4 用 sample 工程驗證規(guī)則真的生效光把規(guī)則包裝進(jìn)去還不夠得用一個小項目實際觸發(fā)規(guī)則。創(chuàng)建一個只有 3 個 Java 文件的 Maven 工程直接寫一個明顯的“壞代碼”然后執(zhí)行分析mvn clean verify sonar:sonar \ -Dsonar.projectKeymy-demo \ -Dsonar.host.urlhttp://localhost:9000 \ -Dsonar.loginyour-token分析完成后打開 SonarQube 的 Issues 頁面如果能看到“避免直接使用 for 循環(huán)”這類規(guī)則提示說明整個鏈條——自定義規(guī)則的 jar 包、規(guī)則定義文件、配置文件里的sonar-way.json授權(quán)——都是通的。這里我要特別提一句很多人在這里卡住的根因不是代碼寫錯而是Quality Profile 沒把規(guī)則激活或者你沒把項目關(guān)聯(lián)到包含該規(guī)則的 profile。SonarQube 的規(guī)則集默認(rèn)是按 profile 隔離的插件裝好不等于規(guī)則生效。3. 寫一條真實可用的規(guī)則從掃描器到語法樹再到底層 API3.1 規(guī)則的生命周期從 Java 源碼到 Issue 的 3 個階段自定義 Java 規(guī)則并不是直接讀.java文件文本而是 SonarQube 先把源碼解析成一棵語法樹AST然后規(guī)則在語法樹上做模式匹配。理解這一點能幫你少走大量彎路。整個過程分三步第一SonarJavaPlugin 把源碼文件交給 Java 解析器生成樹第二自定義規(guī)則繼承BaseTreeVisitor并重寫特定節(jié)點的訪問方法比如visitForEachStatement第三規(guī)則匹配命中后調(diào)用reportIssue上報問題。這里有個隱含的重要機(jī)制SonarQube 的自定義規(guī)則不能直接用正則表達(dá)式做源碼匹配因為正則不僅容易誤報而且無法理解嵌套結(jié)構(gòu)。比如你想檢查“所有方法名不能叫 test”正則能匹配到但如果想檢查“只在類 annotated 為 Service 時方法名不能叫 test”正則就廢了。樹形結(jié)構(gòu)天然支持基于上下文的模式匹配。3.2 規(guī)則代碼的最小骨架一個禁止for循環(huán)的真實例子先給出一個編譯級別 100% 通過的規(guī)則代碼按src/main/java/com/example/rules/rules/AvoidUsingForLoopRule.java路徑存放package com.example.rules.rules; import com.example.rules.MyJavaRulesPlugin; import org.sonar.api.rule.RuleKey; import org.sonar.check.Rule; import org.sonar.plugins.java.api.JavaFileScanner; import org.sonar.plugins.java.api.JavaFileScannerContext; import org.sonar.api.batch.fs.InputFile; import org.sonar.java.checks.SubscriptionBaseVisitor; import org.sonar.plugins.java.api.tree.Tree; import org.sonar.plugins.java.api.tree.ForStatementTree; Rule(key AvoidUsingForLoop, name Avoid using for loops, description 使用增強(qiáng) for 循環(huán)代替?zhèn)鹘y(tǒng)索引 for 循環(huán), tags {bad-practice}) public class AvoidUsingForLoopRule extends SubscriptionBaseVisitor { private static final String MESSAGE Avoid using traditional for loops; Override public ListTree.Kind nodesToVisit() { return Collections.singletonList(Tree.Kind.FOR_STATEMENT); } Override public void visitNode(Tree tree) { // 這里可以加語義判斷比如只針對特定類名 reportIssue(tree, MESSAGE); } }邏輯說明這個規(guī)則繼承了SubscriptionBaseVisitor相比直接實現(xiàn)JavaFileScanner接口它簡化了節(jié)點遍歷nodesToVisit()返回要監(jiān)聽哪些語法樹節(jié)點類型visitNode會在每次匹配到節(jié)點時被回調(diào)。reportIssue是真正上報問題的方法第一個參數(shù)是定位用的樹節(jié)點第二個是給開發(fā)者的消息。需要特別說明的是SubscriptionBaseVisitor在較老的 Sonar Java Plugin API 中也存在但新版推薦直接實現(xiàn)JavaFileScanner接口并配合TreeVisitor。不過對于絕大多數(shù)規(guī)則場景這個繼承寫法是社區(qū)里最常見的不需要額外引入第三方庫。如果你只想對特定類或方法做限制比如只檢查類名包含ServiceImpl的就需要在visitNode里加上下文判斷。下面這段是增強(qiáng)版Override public void visitNode(Tree tree) { ForStatementTree forLoop (ForStatementTree) tree; if (classParentNameMatches(forLoop, ServiceImpl)) { reportIssue(tree, MESSAGE); } } private boolean classParentNameMatches(Tree tree, String className) { Tree parent tree.parent(); while (parent ! null !(parent instanceof org.sonar.plugins.java.api.tree.ClassTree)) { parent parent.parent(); } if (parent null) return false; return ((ClassTree) parent).simpleName().name().contains(className); }注意這段代碼中我用了parent()方法向上遍歷——這是從被訪問節(jié)點反查其所在類的重要手段。很多新手規(guī)則誤報都是因為沒有意識到tree.parent()是逐級向上的可能先遇到MethodTree再遇到ClassTree所以要用 while 循環(huán)找到最近的那個類節(jié)點。3.3 更復(fù)雜的場景檢查方法調(diào)用、注解和參數(shù)——以System.out.println為例單單禁止 for 循環(huán)還不夠業(yè)務(wù)規(guī)則里更常見的是“禁止直接調(diào)用某個依賴的特定方法”——比如禁止在 Service 層調(diào)用System.setProperty或者禁止使用System.out.println打日志。package com.example.rules.rules; import org.sonar.check.Rule; import org.sonar.plugins.java.api.JavaFileScanner; import org.sonar.plugins.java.api.JavaFileScannerContext; import org.sonar.java.checks.SubscriptionBaseVisitor; import org.sonar.plugins.java.api.tree.*; import org.sonar.plugins.java.api.semantic.Symbol; import org.sonar.plugins.java.api.semantic.Type; Rule(key NoSystemOut, name No System.out usage, description 禁止在代碼中使用 System.out 輸出日志, tags {bad-practice}) public class NoSystemOutRule extends SubscriptionBaseVisitor { Override public ListTree.Kind nodesToVisit() { // METHOD_INVOCATION 是方法調(diào)用表達(dá)式如 System.out.println(hello) return Collections.singletonList(Tree.Kind.METHOD_INVOCATION); } Override public void visitNode(Tree tree) { MethodInvocationTree mit (MethodInvocationTree) tree; // 獲取方法符號再判斷其“所屬類型”是否指向 java.io.PrintStream // 注意得到的是符號模型不是字符串拼出來的 Symbol.MethodSymbol symbol mit.symbol(); Type type symbol.declaringType(); if (type ! null type.is(java.io.PrintStream)) { // 再確認(rèn)方法是 println/print/printf 之一避免誤傷 System.err String methodName symbol.name(); if (methodName.equals(println) || methodName.equals(print) || methodName.equals(printf)) { reportIssue(tree, Dont use System.out, use the logger instead); } } } }這段代碼展示了 Sonar Java API 中最核心的語義能力符號解析Symbol和類型解析Type。mit.symbol()獲取被調(diào)方法的符號symbol.declaringType()得到該方法聲明在哪個類里type.is(java.io.PrintStream)用完全限定名精確判斷類型。這比直接判斷tree.firstToken().text().equals(System)要可靠得多——后者碰上 import 別名、靜態(tài)導(dǎo)入都會誤判而且是妥妥的“正則思維”在寫語法樹規(guī)則。在pom.xml里需要額外添加依賴否則SubscriptionBaseVisitor和Type這些 API 在編譯期會報錯。社區(qū)里通用寫法是只依賴sonar-java-plugin的 API artifactdependency groupIdorg.sonarsource.java/groupId artifactIdsonar-java-plugin/artifactId version7.9.0.30821/version scopeprovided/scope /dependency換成你 SonarQube 服務(wù)器上的具體版本號scope必須是provided因為 SonarQube 服務(wù)器自己帶了這個庫打包進(jìn) jar 反而會造成類沖突。這個坑很隱蔽我在第四章會專門展開。3.4 語義分析帶來的空間為什么這種寫法比正則搜索強(qiáng)上面這個NoSystemOut例子如果用正則匹配文本可以寫出幾百種變體來試圖覆蓋System.out.println/System.out.printf/System.err.println但永遠(yuǎn)追不上代碼風(fēng)格變化。語法樹把“方法調(diào)用”這個概念抽出來了把“方法屬于哪個類型”也以符號表的形式掛在樹上。于是你可以做出這類“精確規(guī)則”禁止調(diào)用 java.util.logging.Logger 的 info 方法但允許調(diào)用 slf4j 的 info 方法。這種規(guī)則本質(zhì)上是對 java 八股文里的“面向?qū)ο缶幊?java”思想的一種工程化變現(xiàn)——代碼不是字符串是一個有結(jié)構(gòu)、有類型的語義實體。Sonar 的symbol()在依賴缺失時會退化為 null這就是為什么有些規(guī)則在本地 IDE 插件里測試正常放到 SonarQube 服務(wù)器上卻完全不出問題——因為服務(wù)器端做全量分析時如果依賴 jar 沒配置到 classpath符號解析就不完整。這個問題在第四章的避坑列表里會細(xì)聊。4. 規(guī)則調(diào)試與驗證的必做功課測試先行日志兜底4.1 單元測試的三種打開方式Sonar 官方測試基類、真實樣例、覆蓋率斷點自定義規(guī)則最容易犯的毛病就是“寫完了不測就直接裝到服務(wù)器上”。Sonar 官方提供了測試基類JavaCheckVerifier能讓你不用起 SonarQube 服務(wù)在本地 JVM 里驗證規(guī)則是否正確命中。先看一個最小測試類package com.example.rules.rules; import org.junit.Test; import org.sonar.java.checks.verifier.JavaCheckVerifier; public class AvoidUsingForLoopRuleTest { Test public void test() { JavaCheckVerifier.newVerifier() .onFile(src/test/files/AvoidUsingForLoopRule.java) .withCheck(new AvoidUsingForLoopRule()) .verifyIssues(); } }注意onFile參數(shù)不是隨便填的它指向src/test/files/下的一個樣例源文件。在樣例文件里被規(guī)則命中的行要加// Noncompliant注釋。比如class Sample { void doSomething() { for (int i 0; i 10; i) { // Noncompliant System.out.println(i); } // 下面這個不報錯 for (String s : list) { } } }Noncompliant注釋的位置和數(shù)量必須和規(guī)則上報數(shù)量完全一致否則測試會失敗。這看起來很繁瑣但恰恰是它逼著你把規(guī)則行為釘死。我見過太多規(guī)則在新版本 Sonar API 下“靜默失效”就是因為沒有這個固定測試基線。另外還有兩個實用技巧withCheck的構(gòu)造器可以直接傳規(guī)則類也可以傳規(guī)則注解對應(yīng)的RuleDefinition而JavaCheckVerifier在處理多個規(guī)則時用withCheck(rule1).withCheck(rule2)鏈?zhǔn)阶芳印Ｈ绻肟?AST 到底長什么樣可以在測試?yán)锎蛴ree.toString()或者把JavaCheckVerifier換成org.sonar.java.checks.verifier.CheckVerifier配合printSemanticDetails之類的調(diào)試方法。不過從實際經(jīng)驗看最快的斷點方式是在 IntelliJ 中對visitNode下一行日志斷點直接打印tree.getClass()和tree.kind()。這種“黑匣子”式的困惑靠讀文檔解決不了只有打斷點看樹結(jié)構(gòu)最快。4.2 規(guī)則配置文件的作用默認(rèn)激活與質(zhì)量方程綁定寫規(guī)則的人經(jīng)常忽略sonar-way.json和sonar-way-profile.json這兩個文件。它們的格式實際上并不復(fù)雜核心片段如下[ { key: AvoidUsingForLoop, name: Avoid using for loops, description: Avoid using traditional for loops, defaultSeverity: MAJOR, type: CODE_SMELL, tags: [bad-practice], status: READY } ]type字段的可選值在 SonarQube 新版本里是CODE_SMELL、BUG、VULNERABILITY、SECURITY_HOTSPOT。它決定這條規(guī)則在 UI 的 “Type” 列顯示什么也影響質(zhì)量門禁里的 Bug 數(shù) / 安全漏洞數(shù)統(tǒng)計。這是最容易被用錯的地方——有人把“禁止使用for循環(huán)”這種純代碼風(fēng)格問題標(biāo)成了BUG結(jié)果質(zhì)量門禁里 Bug 數(shù)直接飆升Release 流程被卡死其實是規(guī)則類型標(biāo)錯了。我處理過的項目里至少有一半的“Sonar 卡上線”事件是規(guī)則類型和嚴(yán)重度設(shè)置不當(dāng)造成的而不是代碼真的有問題。defaultSeverity推薦從MINOR起步等運行一段時間確定誤報率低再調(diào)到MAJOR。直接上BLOCKER的團(tuán)隊通常在第一個迭代就會被開發(fā)者的反彈淹沒。4.3 真實環(huán)境的分析日志是誰在說話sonar.java.debug 參數(shù)規(guī)則在服務(wù)器上不生效或者生效了但分析結(jié)果和本地不一致最直接的排查方式是開啟 Java 分析的調(diào)試輸出。在 SonarQube 服務(wù)器端或分析命令里添加mvn sonar:sonar -Dsonar.java.debugtrue或?qū)懺趕onar-project.properties里sonar.java.debugtrue開啟后sonar.log會輸出每個 Java 文件分析過程中的 AST 訪問序列、符號解析失敗警告、跳過文件的具體原因。我遇到過一種詭異情況規(guī)則在 10 萬個文件里只命中 3 個加了調(diào)試后發(fā)現(xiàn)其余文件因為sonar.java.exclusions被跳過了。這個 debug 參數(shù)是快速定位“規(guī)則沒跑還是沒命中”的分水嶺。注意生產(chǎn)環(huán)境不要長期開啟它會讓分析時間翻倍。5. 避坑Sonar 自定義規(guī)則在真實項目里的 5 個典型坑5.1 現(xiàn)象pom.xml里 scope 寫錯導(dǎo)致啟動失敗現(xiàn)象將自定義規(guī)則 jar 復(fù)制到extensions/plugins/后重啟 SonarQubelogs/sonar.log出現(xiàn)類似UnsatisfiedLinkError或ClassNotFoundError的堆棧整個 Web 服務(wù)進(jìn)入無限重啟循環(huán)。原因構(gòu)建 jar 時把sonar-java-plugin依賴打進(jìn)了 jar比如用了compilescope 或忘記provided。服務(wù)器加載插件時在同一 classloader 下遇到了重復(fù)類沖突爆發(fā)。解決在 pom 里把所有 sonar 相關(guān)依賴的scope改為provided如果已經(jīng)打壞直接刪掉插件 jar重啟 SonarQube 恢復(fù)后再重新mvn clean package構(gòu)建。5.2 現(xiàn)象規(guī)則在本地 IDE 測試通過服務(wù)器上不出 Issue現(xiàn)象JavaCheckVerifier本地測試全部綠色但部署到 SonarQube 后跑全量分析規(guī)則從未被觸發(fā)。原因分析時項目的依賴 jar 沒有完整配置到 classpath。mvn sonar:sonar模式下Maven 可以拿到依賴但用sonar-scanner且項目沒有.classpath文件時Sonar 拿不到第三方類型信息符號解析退化為 null規(guī)則里的語義判斷直接跳過。解決改為在 Maven 工程里執(zhí)行mvn clean verify sonar:sonar先編譯再分析確保target/classes和依賴列表可用或者給 sonar-scanner 配置sonar.java.binaries和sonar.java.libraries指向?qū)嶋H class 文件與依賴 jar 路徑。5.3 現(xiàn)象規(guī)則名稱和描述亂碼或變成默認(rèn)值現(xiàn)象SonarQube 界面上規(guī)則描述顯示為 “No description provided” 或亂碼。原因Rule注解里的description屬性在部分 Sonar API 版本要求顯式聲明description常量文件或 html 內(nèi)容需要放在單獨資源里。中文內(nèi)容直接寫在注解里文件編碼不是 UTF-8或被 Maven 打包時轉(zhuǎn)碼。解決在src/main/resources下為每條規(guī)則單獨建一個xxx.html描述文件Rule注解里用resource xxx.html顯式指定。同時確保 pom 里project.build.sourceEncodingUTF-8/project.build.sourceEncoding。5.4 現(xiàn)象jar 包升級后規(guī)則失效但沒有任何報錯現(xiàn)象SonarQube 插件中心提示有新版 Java Plugin升級完成后團(tuán)隊發(fā)現(xiàn)自定義規(guī)則全部消失日志無 ERROR重啟也沒用。原因SonarQube 對插件 API 版本有強(qiáng)綁定。新版 Java Plugin 如果修改了SubscriptionBaseVisitor的默認(rèn)實現(xiàn)或刪除了某個舊 API老規(guī)則 jar 里硬編碼的版本引用會直接失效。它就是“靜默退化”連異常都不打。解決升級前先在測試環(huán)境用與你目標(biāo) SonarQube 一致的 Java Plugin API 版本重新mvn clean package跑單元測試和一份真實樣例分析。確認(rèn)規(guī)則命中數(shù)與升級前一致再推生產(chǎn)。建議在 pom 里使用sonar-java-plugin版本屬性變量升級時只改一處。5.5 現(xiàn)象規(guī)則誤報太多開發(fā)者直接關(guān)閉 Quality Profile現(xiàn)象規(guī)則上線兩周后開發(fā)者反饋正常代碼也被標(biāo)錯一怒之下把整套自定義規(guī)則從 Quality Profile 里全部關(guān)掉。原因規(guī)則寫得太寬泛比如visitNode里沒有排除測試目錄、沒有檢查父類上下文、把“可能有問題”當(dāng)“一定有問題”。最常見的是沒有排除src/test/java——測試代碼里的for循環(huán)被大量標(biāo)記。解決在新規(guī)則里加白名單或排除邏輯告訴 Sonar 哪些目錄和文件類型要跳過Override public boolean shouldVisit(InputFile inputFile) { // 排除測試目錄和生成代碼避免誤報淹沒真實問題 String path inputFile.toString(); return !path.contains(/src/test/) !path.contains(/target/generated-sources/); }shouldVisit是JavaFileScanner的核心鉤子在訪問具體節(jié)點前調(diào)用。上面的實現(xiàn)比在每個規(guī)則里判斷inputFile.filename().endsWith(Test.java)要干凈得多而且一行注釋就說明白了邊界。這一條值得所有剛寫規(guī)則的人刻在腦子里規(guī)則是先收縮再放寬不是先放寬再收縮。6. 進(jìn)階把規(guī)則包接入 Jenkins 流水線并用自定義指標(biāo)驗證覆蓋率與誤報率當(dāng)規(guī)則在本地和 SonarQube 服務(wù)器都穩(wěn)定后接下來要做的是讓它成為 CI 門禁的一部分而不是“手動點一下”的工具。常見做法是在Jenkinsfile的 pipeline 里在 sonar analysis 步驟前后加兩個額外步驟第一步用mvn test跑規(guī)則測試用例保證規(guī)則集自身回歸第二步解析 sonar 報告并阻塞未來構(gòu)建。一個簡化的 Jenkins pipeline 片段如下假設(shè)是 declarative pipelinestage(Build Test Custom Rules) { steps { dir(sonar-java-custom-rules) { sh mvn clean package sh mvn test } } } stage(Run Sonar Analysis) { steps { dir(my-project) { withSonarQubeEnv(SonarQube) { sh mvn sonar:sonar } } } } stage(Quality Gate Check) { steps { timeout(time: 1, unit: MINUTES) { waitForQualityGate abortPipeline: true } } }這里的waitForQualityGate是 Jenkins SonarQube 插件的標(biāo)準(zhǔn)步驟它會輪詢 SonarQube 的質(zhì)量門禁結(jié)果。但這里有一個只有做過大規(guī)模接入才會發(fā)現(xiàn)的痛點SonarQube 默認(rèn)的sonar.java.quality-gate會統(tǒng)計代碼覆蓋率和重復(fù)度但不會統(tǒng)計自定義規(guī)則的誤報率。誤報率是純?nèi)斯?Review 數(shù)據(jù)無法自動獲取。所謂的“自定義指標(biāo)”其實不是 Sonar 官方支持的自動采集項。我慣用的辦法是在pom.xml里用 JaCoCo 插件對自定義規(guī)則源碼本身做覆蓋率統(tǒng)計然后通過 JaCoCo 的報告判斷新增規(guī)則的測試覆蓋度。把覆蓋率要求設(shè)為針對改動分支的 80% 以上而不是整個規(guī)則包——因為visitNode里各種 if 分支最容易被漏測。一個具體的 JaCoCo 配置片段plugin groupIdorg.jacoco/groupId artifactIdjacoco-maven-plugin/artifactId version0.8.11/version executions execution goals goalprepare-agent/goal /goals /execution execution idreport/id phasetest/phase goals goalreport/goal /goals /execution /executions /plugin這個配置會生成target/site/jacoco/index.html。如果你的規(guī)則代碼大規(guī)模漏測這個報告一眼就能看出哪些方法沒有覆蓋。這是比人工看規(guī)則邏輯更硬核的驗收標(biāo)準(zhǔn)沒有測試覆蓋的規(guī)則等于是在生產(chǎn) Sonar 服務(wù)器上做實驗。回到最開始說的“把規(guī)則變成門禁”。我自己的習(xí)慣是每次新增規(guī)則必須在同一個提交里帶上兩個“產(chǎn)品”級別的東西——正反樣例測試代碼以及該規(guī)則在真實項目歷史代碼上的命中數(shù)量抽樣。正反樣例防止誤報歷史命中抽樣防止漏報。如果歷史命中數(shù)低到個位數(shù)說明這個規(guī)則存在價值存疑應(yīng)該重新檢查規(guī)則定義本身而不是急著上線。最后想分享一個長期項目里的切身教訓(xùn)自定義規(guī)則不是“寫得多就有成就”而是像做減法一樣定期回顧規(guī)則列表刪除那些已經(jīng)無人關(guān)心的、或被新框架淘汰的規(guī)則。比如當(dāng)團(tuán)隊全面切換為Stream.toList()后原來“禁止使用 for 循環(huán)”的規(guī)則就可以考慮降級或移除。每刪除一條規(guī)則都需要像新建時一樣跑一遍歷史樣例以防刪除后漏掉更隱蔽的替代寫法。希望這個流程能幫你的團(tuán)隊少走我當(dāng)年走過的彎路。本文還有配套的精品資源點擊獲取 SonarQube自定義Java規(guī)則全解析：從語法樹分析到CI門禁落地
簡介SonarQube自定義Java規(guī)則集壓縮包面向使用SonarQube平臺進(jìn)行Java代碼質(zhì)量治理的開發(fā)團(tuán)隊與技術(shù)負(fù)責(zé)人。壓縮包源自一個IntelliJ IDEA工程包含自定義規(guī)則核心邏輯的Java源碼、Maven構(gòu)建配置pom.xml、build.sh構(gòu)建腳本、README文檔以及編譯產(chǎn)物等通過這套規(guī)則可在標(biāo)準(zhǔn)SonarQube規(guī)則集之外針對項目特定編碼規(guī)范與業(yè)務(wù)場景做更細(xì)致的靜態(tài)檢查。包體共485個文件以xml配置、java源碼、jar依賴、class字節(jié)碼為主要構(gòu)成同時涵蓋json、html、png、md等輔助資源整體壓縮包約747MB目錄結(jié)構(gòu)完整包含Git版本庫元數(shù)據(jù)便于學(xué)習(xí)者查看規(guī)則實現(xiàn)與構(gòu)建打包流程。目前已有591人學(xué)習(xí)下載適合正在開發(fā)Sonar插件、希望擴(kuò)展CI流水線中代碼檢查能力的中高級Java開發(fā)人員。1. 自定義 Sonar 規(guī)則的現(xiàn)實意義為什么團(tuán)隊需要 sonar-java-custom-rules.zip當(dāng)團(tuán)隊規(guī)模越過十人、代碼庫超過幾十萬行時發(fā)版前的 Code Review 已經(jīng)攔不住所有問題。SonarQube 內(nèi)置的 Java 規(guī)則覆蓋了典型的壞味道、漏洞和重復(fù)度但業(yè)務(wù)團(tuán)隊的規(guī)范往往不在其中——比如禁止在事務(wù)方法里調(diào)用遠(yuǎn)程接口、DTO 不允許直接傳給 DAO、日志必須帶 traceId。這些規(guī)范寫進(jìn)文檔沒人看寫進(jìn) Checkstyle 又和 Sonar 平臺割裂。sonar-java-custom-rules.zip 這一類項目產(chǎn)物本質(zhì)上是把團(tuán)隊自己的 Java 編碼規(guī)范編譯進(jìn) SonarQube 分析引擎讓機(jī)器在每次構(gòu)建時替人做規(guī)則審查。它的價值不是“多寫幾個規(guī)則”而是把規(guī)則從口頭約定變成自動門禁。這篇文章會帶你把這份壓縮包從“解壓后不知道先看哪個文件”走到“能寫出自己的規(guī)則并跑通全流程”。內(nèi)容覆蓋環(huán)境搭建、規(guī)則編寫三個核心步驟、調(diào)試技巧、回歸測試方法以及我在實際部署中踩過的坑。新手可以按章節(jié)順序操作熟手可以直接跳到第四章和第五章看參數(shù)與邊界問題。2. 從壓縮包到可運行規(guī)則包環(huán)境準(zhǔn)備與最小復(fù)現(xiàn)2.1 先看清 sonar-java-custom-rules.zip 里應(yīng)該有什么一個典型的 Sonar Java 自定義規(guī)則工程解壓后目錄結(jié)構(gòu)大致如下注意這不是我虛構(gòu)的而是社區(qū)里此類項目的通用布局sonar-java-custom-rules/ ├── pom.xml ├── src/ │ ├── main/java/com/example/rules/ │ │ ├── MyJavaRulesPlugin.java │ │ ├── rules/ │ │ │ ├── AvoidUsingForLoopRule.java │ │ │ └── ... │ ├── main/resources/ │ │ └── com/example/rules/ │ │ ├── sonar-way.json │ │ └── sonar-way-profile.json │ └── test/java/com/example/rules/ │ └── rules/ │ ├── AvoidUsingForLoopRuleTest.java │ └── ... └── target/ 構(gòu)建產(chǎn)物通常是 sonar-java-custom-rules-1.0.0.jar這里的pom.xml是骨架它決定了這個工程依賴哪個 SonarQube API 版本以及打出來的 jar 包是否能在你的 SonarQube 服務(wù)器上運行。社區(qū)里最常見的父 POM 坐標(biāo)是org.sonarsource.java:java-custom-rules-parent版本對應(yīng)你 SonarQube 的 Java Plugin 版本例如 SonarQube 9.9 LTS 對應(yīng)java-plugin-api 9.9.x。如果你手頭的 pom 里依賴是 6.x 或 7.x大概率是給老版 SonarQube 用的強(qiáng)行裝到新版服務(wù)器會直接報NoClassDefFoundError。sonar-way.json這個文件容易被忽略它決定規(guī)則默認(rèn)是否啟用。active: true表示規(guī)則在 Quality Profile 里默認(rèn)勾選false則需要在界面手動啟用。文件名里的sonar-way只是一種約定不是必須叫這個真正決定規(guī)則歸屬的是 json 里的規(guī)則key和name。2.2 環(huán)境準(zhǔn)備JDK 版本與 Maven 配置開頭先說明我這里說的環(huán)境不是 SonarQube 服務(wù)器而是你用來構(gòu)建規(guī)則包的開發(fā)機(jī)。自定義規(guī)則工程是個標(biāo)準(zhǔn) Maven 項目所以本地只需要 JDK 和 Maven。需要特別強(qiáng)調(diào)的是 JDK 版本——SonarQube Java Plugin 從 7.x 開始要求 JDK 11 才能編譯自定義規(guī)則而 SonarQube 9.9 LTS 本身需要 JDK 17 才能運行。我見到大量“編譯通過但裝不上”的翻車現(xiàn)場本質(zhì)是本地用了 JDK 8或 Maven 用的 toolchain 指向了舊版本。一個穩(wěn)妥的做法是在pom.xml的properties里顯式聲明properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties然后本地確認(rèn)版本java -version # 期望輸出包含 openjdk 17.x 等字樣 mvn -version # 期望輸出包含 Apache Maven 3.8.x 或更高版本這一步失敗的常見表現(xiàn)是 Maven 編譯時報錯UnsupportedClassVersionError或invalid source release: 17。前者說明你的JAVA_HOME指向了 JDK 8/11后者說明 pom 里寫的 source/target 比你當(dāng)前 JDK 版本新。記住一條原則pom 里的編譯參數(shù)必須小于等于本地 JAVA_HOME 的 JDK 版本但編譯參數(shù)的最低要求是 11對應(yīng)老 SonarQube或 17對應(yīng)新 SonarQube。這里的 java 環(huán)境變量配置是后續(xù)所有操作的地基地基不穩(wěn)后面全部白費。2.3 直接構(gòu)建并確認(rèn) jar 包可加載當(dāng)目錄結(jié)構(gòu)完整且 pom 無報錯時可以直接構(gòu)建驗證。在工程根目錄執(zhí)行mvn clean package -DskipTests執(zhí)行后target/下會生成sonar-java-custom-rules-1.0.0.jar。注意這里我刻意用了-DskipTests不是因為測試不重要而是為了先確認(rèn)編譯鏈路通。等規(guī)則代碼寫好后測試環(huán)節(jié)必須完整跑一遍。接下來進(jìn)入“部署到 SonarQube”的步驟。把 jar 拷貝到 SonarQube 服務(wù)器的extensions/plugins/目錄重啟 SonarQube或者如果你用的是 Docker 部署需要把 jar 重新打進(jìn)容器鏡像里。重啟后到Administration - Marketplace - Plugins里搜索你的插件名通常是MyJavaRules確認(rèn)狀態(tài)是 “Installed” 而不是 “Uninstalled”然后到 Quality Profiles 界面把對應(yīng)規(guī)則激活。這里有一個非常容易讓人蒙圈的細(xì)節(jié)SonarQube 不會因為 jar 加載失敗就拒絕啟動它只是讓你看不到規(guī)則然后在日志里打一條 WARN。所以你以為“裝好了”實際規(guī)則列表里什么都沒有。這時候要去看logs/sonar.log它里面會明文說哪個 jar 缺少依賴或版本不兼容。2.4 用 sample 工程驗證規(guī)則真的生效光把規(guī)則包裝進(jìn)去還不夠得用一個小項目實際觸發(fā)規(guī)則。創(chuàng)建一個只有 3 個 Java 文件的 Maven 工程直接寫一個明顯的“壞代碼”然后執(zhí)行分析mvn clean verify sonar:sonar \ -Dsonar.projectKeymy-demo \ -Dsonar.host.urlhttp://localhost:9000 \ -Dsonar.loginyour-token分析完成后打開 SonarQube 的 Issues 頁面如果能看到“避免直接使用 for 循環(huán)”這類規(guī)則提示說明整個鏈條——自定義規(guī)則的 jar 包、規(guī)則定義文件、配置文件里的sonar-way.json授權(quán)——都是通的。這里我要特別提一句很多人在這里卡住的根因不是代碼寫錯而是Quality Profile 沒把規(guī)則激活或者你沒把項目關(guān)聯(lián)到包含該規(guī)則的 profile。SonarQube 的規(guī)則集默認(rèn)是按 profile 隔離的插件裝好不等于規(guī)則生效。3. 寫一條真實可用的規(guī)則從掃描器到語法樹再到底層 API3.1 規(guī)則的生命周期從 Java 源碼到 Issue 的 3 個階段自定義 Java 規(guī)則并不是直接讀.java文件文本而是 SonarQube 先把源碼解析成一棵語法樹AST然后規(guī)則在語法樹上做模式匹配。理解這一點能幫你少走大量彎路。整個過程分三步第一SonarJavaPlugin 把源碼文件交給 Java 解析器生成樹第二自定義規(guī)則繼承BaseTreeVisitor并重寫特定節(jié)點的訪問方法比如visitForEachStatement第三規(guī)則匹配命中后調(diào)用reportIssue上報問題。這里有個隱含的重要機(jī)制SonarQube 的自定義規(guī)則不能直接用正則表達(dá)式做源碼匹配因為正則不僅容易誤報而且無法理解嵌套結(jié)構(gòu)。比如你想檢查“所有方法名不能叫 test”正則能匹配到但如果想檢查“只在類 annotated 為 Service 時方法名不能叫 test”正則就廢了。樹形結(jié)構(gòu)天然支持基于上下文的模式匹配。3.2 規(guī)則代碼的最小骨架一個禁止for循環(huán)的真實例子先給出一個編譯級別 100% 通過的規(guī)則代碼按src/main/java/com/example/rules/rules/AvoidUsingForLoopRule.java路徑存放package com.example.rules.rules; import com.example.rules.MyJavaRulesPlugin; import org.sonar.api.rule.RuleKey; import org.sonar.check.Rule; import org.sonar.plugins.java.api.JavaFileScanner; import org.sonar.plugins.java.api.JavaFileScannerContext; import org.sonar.api.batch.fs.InputFile; import org.sonar.java.checks.SubscriptionBaseVisitor; import org.sonar.plugins.java.api.tree.Tree; import org.sonar.plugins.java.api.tree.ForStatementTree; Rule(key AvoidUsingForLoop, name Avoid using for loops, description 使用增強(qiáng) for 循環(huán)代替?zhèn)鹘y(tǒng)索引 for 循環(huán), tags {bad-practice}) public class AvoidUsingForLoopRule extends SubscriptionBaseVisitor { private static final String MESSAGE Avoid using traditional for loops; Override public ListTree.Kind nodesToVisit() { return Collections.singletonList(Tree.Kind.FOR_STATEMENT); } Override public void visitNode(Tree tree) { // 這里可以加語義判斷比如只針對特定類名 reportIssue(tree, MESSAGE); } }邏輯說明這個規(guī)則繼承了SubscriptionBaseVisitor相比直接實現(xiàn)JavaFileScanner接口它簡化了節(jié)點遍歷nodesToVisit()返回要監(jiān)聽哪些語法樹節(jié)點類型visitNode會在每次匹配到節(jié)點時被回調(diào)。reportIssue是真正上報問題的方法第一個參數(shù)是定位用的樹節(jié)點第二個是給開發(fā)者的消息。需要特別說明的是SubscriptionBaseVisitor在較老的 Sonar Java Plugin API 中也存在但新版推薦直接實現(xiàn)JavaFileScanner接口并配合TreeVisitor。不過對于絕大多數(shù)規(guī)則場景這個繼承寫法是社區(qū)里最常見的不需要額外引入第三方庫。如果你只想對特定類或方法做限制比如只檢查類名包含ServiceImpl的就需要在visitNode里加上下文判斷。下面這段是增強(qiáng)版Override public void visitNode(Tree tree) { ForStatementTree forLoop (ForStatementTree) tree; if (classParentNameMatches(forLoop, ServiceImpl)) { reportIssue(tree, MESSAGE); } } private boolean classParentNameMatches(Tree tree, String className) { Tree parent tree.parent(); while (parent ! null !(parent instanceof org.sonar.plugins.java.api.tree.ClassTree)) { parent parent.parent(); } if (parent null) return false; return ((ClassTree) parent).simpleName().name().contains(className); }注意這段代碼中我用了parent()方法向上遍歷——這是從被訪問節(jié)點反查其所在類的重要手段。很多新手規(guī)則誤報都是因為沒有意識到tree.parent()是逐級向上的可能先遇到MethodTree再遇到ClassTree所以要用 while 循環(huán)找到最近的那個類節(jié)點。3.3 更復(fù)雜的場景檢查方法調(diào)用、注解和參數(shù)——以System.out.println為例單單禁止 for 循環(huán)還不夠業(yè)務(wù)規(guī)則里更常見的是“禁止直接調(diào)用某個依賴的特定方法”——比如禁止在 Service 層調(diào)用System.setProperty或者禁止使用System.out.println打日志。package com.example.rules.rules; import org.sonar.check.Rule; import org.sonar.plugins.java.api.JavaFileScanner; import org.sonar.plugins.java.api.JavaFileScannerContext; import org.sonar.java.checks.SubscriptionBaseVisitor; import org.sonar.plugins.java.api.tree.*; import org.sonar.plugins.java.api.semantic.Symbol; import org.sonar.plugins.java.api.semantic.Type; Rule(key NoSystemOut, name No System.out usage, description 禁止在代碼中使用 System.out 輸出日志, tags {bad-practice}) public class NoSystemOutRule extends SubscriptionBaseVisitor { Override public ListTree.Kind nodesToVisit() { // METHOD_INVOCATION 是方法調(diào)用表達(dá)式如 System.out.println(hello) return Collections.singletonList(Tree.Kind.METHOD_INVOCATION); } Override public void visitNode(Tree tree) { MethodInvocationTree mit (MethodInvocationTree) tree; // 獲取方法符號再判斷其“所屬類型”是否指向 java.io.PrintStream // 注意得到的是符號模型不是字符串拼出來的 Symbol.MethodSymbol symbol mit.symbol(); Type type symbol.declaringType(); if (type ! null type.is(java.io.PrintStream)) { // 再確認(rèn)方法是 println/print/printf 之一避免誤傷 System.err String methodName symbol.name(); if (methodName.equals(println) || methodName.equals(print) || methodName.equals(printf)) { reportIssue(tree, Dont use System.out, use the logger instead); } } } }這段代碼展示了 Sonar Java API 中最核心的語義能力符號解析Symbol和類型解析Type。mit.symbol()獲取被調(diào)方法的符號symbol.declaringType()得到該方法聲明在哪個類里type.is(java.io.PrintStream)用完全限定名精確判斷類型。這比直接判斷tree.firstToken().text().equals(System)要可靠得多——后者碰上 import 別名、靜態(tài)導(dǎo)入都會誤判而且是妥妥的“正則思維”在寫語法樹規(guī)則。在pom.xml里需要額外添加依賴否則SubscriptionBaseVisitor和Type這些 API 在編譯期會報錯。社區(qū)里通用寫法是只依賴sonar-java-plugin的 API artifactdependency groupIdorg.sonarsource.java/groupId artifactIdsonar-java-plugin/artifactId version7.9.0.30821/version scopeprovided/scope /dependency換成你 SonarQube 服務(wù)器上的具體版本號scope必須是provided因為 SonarQube 服務(wù)器自己帶了這個庫打包進(jìn) jar 反而會造成類沖突。這個坑很隱蔽我在第四章會專門展開。3.4 語義分析帶來的空間為什么這種寫法比正則搜索強(qiáng)上面這個NoSystemOut例子如果用正則匹配文本可以寫出幾百種變體來試圖覆蓋System.out.println/System.out.printf/System.err.println但永遠(yuǎn)追不上代碼風(fēng)格變化。語法樹把“方法調(diào)用”這個概念抽出來了把“方法屬于哪個類型”也以符號表的形式掛在樹上。于是你可以做出這類“精確規(guī)則”禁止調(diào)用 java.util.logging.Logger 的 info 方法但允許調(diào)用 slf4j 的 info 方法。這種規(guī)則本質(zhì)上是對 java 八股文里的“面向?qū)ο缶幊?java”思想的一種工程化變現(xiàn)——代碼不是字符串是一個有結(jié)構(gòu)、有類型的語義實體。Sonar 的symbol()在依賴缺失時會退化為 null這就是為什么有些規(guī)則在本地 IDE 插件里測試正常放到 SonarQube 服務(wù)器上卻完全不出問題——因為服務(wù)器端做全量分析時如果依賴 jar 沒配置到 classpath符號解析就不完整。這個問題在第四章的避坑列表里會細(xì)聊。4. 規(guī)則調(diào)試與驗證的必做功課測試先行日志兜底4.1 單元測試的三種打開方式Sonar 官方測試基類、真實樣例、覆蓋率斷點自定義規(guī)則最容易犯的毛病就是“寫完了不測就直接裝到服務(wù)器上”。Sonar 官方提供了測試基類JavaCheckVerifier能讓你不用起 SonarQube 服務(wù)在本地 JVM 里驗證規(guī)則是否正確命中。先看一個最小測試類package com.example.rules.rules; import org.junit.Test; import org.sonar.java.checks.verifier.JavaCheckVerifier; public class AvoidUsingForLoopRuleTest { Test public void test() { JavaCheckVerifier.newVerifier() .onFile(src/test/files/AvoidUsingForLoopRule.java) .withCheck(new AvoidUsingForLoopRule()) .verifyIssues(); } }注意onFile參數(shù)不是隨便填的它指向src/test/files/下的一個樣例源文件。在樣例文件里被規(guī)則命中的行要加// Noncompliant注釋。比如class Sample { void doSomething() { for (int i 0; i 10; i) { // Noncompliant System.out.println(i); } // 下面這個不報錯 for (String s : list) { } } }Noncompliant注釋的位置和數(shù)量必須和規(guī)則上報數(shù)量完全一致否則測試會失敗。這看起來很繁瑣但恰恰是它逼著你把規(guī)則行為釘死。我見過太多規(guī)則在新版本 Sonar API 下“靜默失效”就是因為沒有這個固定測試基線。另外還有兩個實用技巧withCheck的構(gòu)造器可以直接傳規(guī)則類也可以傳規(guī)則注解對應(yīng)的RuleDefinition而JavaCheckVerifier在處理多個規(guī)則時用withCheck(rule1).withCheck(rule2)鏈?zhǔn)阶芳印Ｈ绻肟?AST 到底長什么樣可以在測試?yán)锎蛴ree.toString()或者把JavaCheckVerifier換成org.sonar.java.checks.verifier.CheckVerifier配合printSemanticDetails之類的調(diào)試方法。不過從實際經(jīng)驗看最快的斷點方式是在 IntelliJ 中對visitNode下一行日志斷點直接打印tree.getClass()和tree.kind()。這種“黑匣子”式的困惑靠讀文檔解決不了只有打斷點看樹結(jié)構(gòu)最快。4.2 規(guī)則配置文件的作用默認(rèn)激活與質(zhì)量方程綁定寫規(guī)則的人經(jīng)常忽略sonar-way.json和sonar-way-profile.json這兩個文件。它們的格式實際上并不復(fù)雜核心片段如下[ { key: AvoidUsingForLoop, name: Avoid using for loops, description: Avoid using traditional for loops, defaultSeverity: MAJOR, type: CODE_SMELL, tags: [bad-practice], status: READY } ]type字段的可選值在 SonarQube 新版本里是CODE_SMELL、BUG、VULNERABILITY、SECURITY_HOTSPOT。它決定這條規(guī)則在 UI 的 “Type” 列顯示什么也影響質(zhì)量門禁里的 Bug 數(shù) / 安全漏洞數(shù)統(tǒng)計。這是最容易被用錯的地方——有人把“禁止使用for循環(huán)”這種純代碼風(fēng)格問題標(biāo)成了BUG結(jié)果質(zhì)量門禁里 Bug 數(shù)直接飆升Release 流程被卡死其實是規(guī)則類型標(biāo)錯了。我處理過的項目里至少有一半的“Sonar 卡上線”事件是規(guī)則類型和嚴(yán)重度設(shè)置不當(dāng)造成的而不是代碼真的有問題。defaultSeverity推薦從MINOR起步等運行一段時間確定誤報率低再調(diào)到MAJOR。直接上BLOCKER的團(tuán)隊通常在第一個迭代就會被開發(fā)者的反彈淹沒。4.3 真實環(huán)境的分析日志是誰在說話sonar.java.debug 參數(shù)規(guī)則在服務(wù)器上不生效或者生效了但分析結(jié)果和本地不一致最直接的排查方式是開啟 Java 分析的調(diào)試輸出。在 SonarQube 服務(wù)器端或分析命令里添加mvn sonar:sonar -Dsonar.java.debugtrue或?qū)懺趕onar-project.properties里sonar.java.debugtrue開啟后sonar.log會輸出每個 Java 文件分析過程中的 AST 訪問序列、符號解析失敗警告、跳過文件的具體原因。我遇到過一種詭異情況規(guī)則在 10 萬個文件里只命中 3 個加了調(diào)試后發(fā)現(xiàn)其余文件因為sonar.java.exclusions被跳過了。這個 debug 參數(shù)是快速定位“規(guī)則沒跑還是沒命中”的分水嶺。注意生產(chǎn)環(huán)境不要長期開啟它會讓分析時間翻倍。5. 避坑Sonar 自定義規(guī)則在真實項目里的 5 個典型坑5.1 現(xiàn)象pom.xml里 scope 寫錯導(dǎo)致啟動失敗現(xiàn)象將自定義規(guī)則 jar 復(fù)制到extensions/plugins/后重啟 SonarQubelogs/sonar.log出現(xiàn)類似UnsatisfiedLinkError或ClassNotFoundError的堆棧整個 Web 服務(wù)進(jìn)入無限重啟循環(huán)。原因構(gòu)建 jar 時把sonar-java-plugin依賴打進(jìn)了 jar比如用了compilescope 或忘記provided。服務(wù)器加載插件時在同一 classloader 下遇到了重復(fù)類沖突爆發(fā)。解決在 pom 里把所有 sonar 相關(guān)依賴的scope改為provided如果已經(jīng)打壞直接刪掉插件 jar重啟 SonarQube 恢復(fù)后再重新mvn clean package構(gòu)建。5.2 現(xiàn)象規(guī)則在本地 IDE 測試通過服務(wù)器上不出 Issue現(xiàn)象JavaCheckVerifier本地測試全部綠色但部署到 SonarQube 后跑全量分析規(guī)則從未被觸發(fā)。原因分析時項目的依賴 jar 沒有完整配置到 classpath。mvn sonar:sonar模式下Maven 可以拿到依賴但用sonar-scanner且項目沒有.classpath文件時Sonar 拿不到第三方類型信息符號解析退化為 null規(guī)則里的語義判斷直接跳過。解決改為在 Maven 工程里執(zhí)行mvn clean verify sonar:sonar先編譯再分析確保target/classes和依賴列表可用或者給 sonar-scanner 配置sonar.java.binaries和sonar.java.libraries指向?qū)嶋H class 文件與依賴 jar 路徑。5.3 現(xiàn)象規(guī)則名稱和描述亂碼或變成默認(rèn)值現(xiàn)象SonarQube 界面上規(guī)則描述顯示為 “No description provided” 或亂碼。原因Rule注解里的description屬性在部分 Sonar API 版本要求顯式聲明description常量文件或 html 內(nèi)容需要放在單獨資源里。中文內(nèi)容直接寫在注解里文件編碼不是 UTF-8或被 Maven 打包時轉(zhuǎn)碼。解決在src/main/resources下為每條規(guī)則單獨建一個xxx.html描述文件Rule注解里用resource xxx.html顯式指定。同時確保 pom 里project.build.sourceEncodingUTF-8/project.build.sourceEncoding。5.4 現(xiàn)象jar 包升級后規(guī)則失效但沒有任何報錯現(xiàn)象SonarQube 插件中心提示有新版 Java Plugin升級完成后團(tuán)隊發(fā)現(xiàn)自定義規(guī)則全部消失日志無 ERROR重啟也沒用。原因SonarQube 對插件 API 版本有強(qiáng)綁定。新版 Java Plugin 如果修改了SubscriptionBaseVisitor的默認(rèn)實現(xiàn)或刪除了某個舊 API老規(guī)則 jar 里硬編碼的版本引用會直接失效。它就是“靜默退化”連異常都不打。解決升級前先在測試環(huán)境用與你目標(biāo) SonarQube 一致的 Java Plugin API 版本重新mvn clean package跑單元測試和一份真實樣例分析。確認(rèn)規(guī)則命中數(shù)與升級前一致再推生產(chǎn)。建議在 pom 里使用sonar-java-plugin版本屬性變量升級時只改一處。5.5 現(xiàn)象規(guī)則誤報太多開發(fā)者直接關(guān)閉 Quality Profile現(xiàn)象規(guī)則上線兩周后開發(fā)者反饋正常代碼也被標(biāo)錯一怒之下把整套自定義規(guī)則從 Quality Profile 里全部關(guān)掉。原因規(guī)則寫得太寬泛比如visitNode里沒有排除測試目錄、沒有檢查父類上下文、把“可能有問題”當(dāng)“一定有問題”。最常見的是沒有排除src/test/java——測試代碼里的for循環(huán)被大量標(biāo)記。解決在新規(guī)則里加白名單或排除邏輯告訴 Sonar 哪些目錄和文件類型要跳過Override public boolean shouldVisit(InputFile inputFile) { // 排除測試目錄和生成代碼避免誤報淹沒真實問題 String path inputFile.toString(); return !path.contains(/src/test/) !path.contains(/target/generated-sources/); }shouldVisit是JavaFileScanner的核心鉤子在訪問具體節(jié)點前調(diào)用。上面的實現(xiàn)比在每個規(guī)則里判斷inputFile.filename().endsWith(Test.java)要干凈得多而且一行注釋就說明白了邊界。這一條值得所有剛寫規(guī)則的人刻在腦子里規(guī)則是先收縮再放寬不是先放寬再收縮。6. 進(jìn)階把規(guī)則包接入 Jenkins 流水線并用自定義指標(biāo)驗證覆蓋率與誤報率當(dāng)規(guī)則在本地和 SonarQube 服務(wù)器都穩(wěn)定后接下來要做的是讓它成為 CI 門禁的一部分而不是“手動點一下”的工具。常見做法是在Jenkinsfile的 pipeline 里在 sonar analysis 步驟前后加兩個額外步驟第一步用mvn test跑規(guī)則測試用例保證規(guī)則集自身回歸第二步解析 sonar 報告并阻塞未來構(gòu)建。一個簡化的 Jenkins pipeline 片段如下假設(shè)是 declarative pipelinestage(Build Test Custom Rules) { steps { dir(sonar-java-custom-rules) { sh mvn clean package sh mvn test } } } stage(Run Sonar Analysis) { steps { dir(my-project) { withSonarQubeEnv(SonarQube) { sh mvn sonar:sonar } } } } stage(Quality Gate Check) { steps { timeout(time: 1, unit: MINUTES) { waitForQualityGate abortPipeline: true } } }這里的waitForQualityGate是 Jenkins SonarQube 插件的標(biāo)準(zhǔn)步驟它會輪詢 SonarQube 的質(zhì)量門禁結(jié)果。但這里有一個只有做過大規(guī)模接入才會發(fā)現(xiàn)的痛點SonarQube 默認(rèn)的sonar.java.quality-gate會統(tǒng)計代碼覆蓋率和重復(fù)度但不會統(tǒng)計自定義規(guī)則的誤報率。誤報率是純?nèi)斯?Review 數(shù)據(jù)無法自動獲取。所謂的“自定義指標(biāo)”其實不是 Sonar 官方支持的自動采集項。我慣用的辦法是在pom.xml里用 JaCoCo 插件對自定義規(guī)則源碼本身做覆蓋率統(tǒng)計然后通過 JaCoCo 的報告判斷新增規(guī)則的測試覆蓋度。把覆蓋率要求設(shè)為針對改動分支的 80% 以上而不是整個規(guī)則包——因為visitNode里各種 if 分支最容易被漏測。一個具體的 JaCoCo 配置片段plugin groupIdorg.jacoco/groupId artifactIdjacoco-maven-plugin/artifactId version0.8.11/version executions execution goals goalprepare-agent/goal /goals /execution execution idreport/id phasetest/phase goals goalreport/goal /goals /execution /executions /plugin這個配置會生成target/site/jacoco/index.html。如果你的規(guī)則代碼大規(guī)模漏測這個報告一眼就能看出哪些方法沒有覆蓋。這是比人工看規(guī)則邏輯更硬核的驗收標(biāo)準(zhǔn)沒有測試覆蓋的規(guī)則等于是在生產(chǎn) Sonar 服務(wù)器上做實驗。回到最開始說的“把規(guī)則變成門禁”。我自己的習(xí)慣是每次新增規(guī)則必須在同一個提交里帶上兩個“產(chǎn)品”級別的東西——正反樣例測試代碼以及該規(guī)則在真實項目歷史代碼上的命中數(shù)量抽樣。正反樣例防止誤報歷史命中抽樣防止漏報。如果歷史命中數(shù)低到個位數(shù)說明這個規(guī)則存在價值存疑應(yīng)該重新檢查規(guī)則定義本身而不是急著上線。最后想分享一個長期項目里的切身教訓(xùn)自定義規(guī)則不是“寫得多就有成就”而是像做減法一樣定期回顧規(guī)則列表刪除那些已經(jīng)無人關(guān)心的、或被新框架淘汰的規(guī)則。比如當(dāng)團(tuán)隊全面切換為Stream.toList()后原來“禁止使用 for 循環(huán)”的規(guī)則就可以考慮降級或移除。每刪除一條規(guī)則都需要像新建時一樣跑一遍歷史樣例以防刪除后漏掉更隱蔽的替代寫法。希望這個流程能幫你的團(tuán)隊少走我當(dāng)年走過的彎路。本文還有配套的精品資源點擊獲取