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