简介面向Java开发者的SonarQube自定义规则插件工程包目标是扩展SonarQube对Java源代码的静态代码分析能力。通过内置的自定义规则可以将团队特定的编码规范固化为自动化检查项从而在代码提交前发现潜在缺陷、代码异味和安全问题提升可维护性。资源包共包含485个文件整体体积约747MB其中Java规则源文件43个、XML规则描述与配置60个、JSON文件33个、依赖JAR包31个、编译类文件24个此外还提供HTML文档、示例样本和构建脚本。整个工程基于Maven组织带有pom.xml、build.sh、README等标准文件也保留了完整的.git与.idea目录方便直接导入IntelliJ IDEA进行二次开发与重新打包目前已有592人参与学习。仔细阅读源码与规则定义可以掌握SonarQube插件开发流程、规则注册机制和静态分析原理并据此定制出适合自己团队编码风格的检测规则。1. 自定义规则不是黑匣子sonar-java-custom-rules 拆出来能干什么SonarQube 扫 Java 服务端代码内置规则能管住空指针、资源泄漏、循环嵌套这类通用问题但团队自己的约定它管不了Controller 不准把内部异常抛给前端、工具类必须有私有构造、日志对象必须用 private static final。这些规范只写在 Wiki 里很快就被新人和紧急上线冲掉。这套 sonar-java-custom-rules 拆出来不是一份编译好的规则包而是一个可以直接改代码的 SonarJava 自定义规则插件工程里面有 pom.xml、build.sh、src 目录下的规则定义与测试代码以及完整的 IntelliJ 项目结构。它解决的是“把团队规范变成扫描规则”这件事也回答了 rules 校验规则到底是怎么被 SonarQube 加载执行的。适合刚接手代码质量平台的 Java 开发工程师也适合想搞懂静态检查背后机制的人比如 Java 开发工程师面试题里常追问的 AST 与规则仓库关系。2. 先看机制规则仓库、AST 订阅和问题上报是怎么串起来的2.1 规则仓库是入口RulesDefinition 到底注册了什么在 SonarQube 里一条“规则”其实有两副面孔。Web 界面看到的是它的元数据key、名称、描述、严重程度、类型、标签。而扫描引擎实际执行的是另一副面孔一个能遍历语法树并做判断的类。这两者必须通过“规则仓库”串起来。规则仓库是 SonarQube 里的一个独立命名空间内置的 Java 检查都挂在官方仓库下自定义规则插件则要自己定义一个仓库避免和内置规则的 key 撞车。仓库定义类实现的是RulesDefinition接口。在define(Context context)方法里用createRepository(key, language)创建仓库然后一条一条createRule。看下面这个入口类它是整个插件被 SonarQube 加载的第一站public class CustomRulesPlugin implements Plugin { Override public void define(Context context) { // 注册规则仓库让 SonarQube 知道我们有一组规则 context.addExtension(MyJavaRulesDefinition.class); // 注册检查器让 SonarJava 引擎知道如何去实例化每条规则 context.addExtension(MyJavaCheckRegistrar.class); } }逻辑说明define方法里addExtension的类会被 SonarQube 生命周期实例化。MyJavaRulesDefinition负责描述仓库和规则元数据MyJavaCheckRegistrar负责把规则实现类挂到 SonarJava 分析引擎上。这里很多人第一次看会懵为什么规则定义和规则实现要拆成两个类原因在于 SonarQube 的管理界面和扫描引擎是两条链路——界面要的是元数据引擎要的是可执行代码两者都需要注册缺一个规则就会变成“看得见、跑不了”或者“跑得了、看不见”。再来看仓库定义类。注意语言的写法这里是容易踩坑的点public class MyJavaRulesDefinition implements RulesDefinition { private static final String REPOSITORY_KEY mycompany-java; private static final String REPOSITORY_NAME My Company Java Rules; private static final String LANGUAGE java; Override public void define(Context context) { NewRepository repo context .createRepository(REPOSITORY_KEY, LANGUAGE) .setName(REPOSITORY_NAME); // 每条规则的元数据在这里声明 repo.createRule(NoSystemOut) .setName(禁止System.out输出) .setHtmlDescription(使用SLF4J代替System.out.println) .setSeverity(MAJOR) .setType(RuleType.CODE_SMELL); repo.done(); } }参数说明createRepository的第一个参数是仓库在系统内的唯一标识第二个参数是语言。语言必须写java这个固定值写成Java或者中文仓库在 SonarQube 里能注册成功但 SonarJava 引擎根本不会去执行里面的规则。规则 keyNoSystemOut必须和后面规则类上Rule注解的 key 保持一致前后不一致的结果很恶心Web 端能看到规则名扫描却永远不触发。setSeverity的合法值有 BLOCKER、CRITICAL、MAJOR、MINOR、INFOsetType的取值是 BUG、VULNERABILITY、CODE_SMELL对应 Web 界面上问题类型的三个分类。2.2 规则实现是 AST 订阅不用正则用节点自定义规则的核心实现方式不是正则匹配源码而是订阅语法树节点。SonarJava 会把 Java 源码解析成 AST抽象语法树规则类继承IssuableSubscriptionVisitor重写nodesToVisit()声明自己关心哪些节点类型。分析引擎每遍历到一个匹配的节点就回调visitNode(Tree tree)。这种方式比正则扫描强在哪强在它天然知道语法上下文。比如规则想检查方法调用它能直接知道这个调用外层是不是 if 块、方法名是谁、参数列表是什么。正则做静态检查很容易被注释、字符串、换行干扰AST 没有这个问题。看一个最简单的例子禁止System.out.println。Rule(key NoSystemOut, description 禁止在代码里直接输出到控制台, tags {convention}) public class NoSystemOutRule extends IssuableSubscriptionVisitor { Override public ListTree.Kind nodesToVisit() { // 只关心方法调用类型的节点其余节点不浪费时间 return Collections.singletonList(Tree.Kind.METHOD_INVOCATION); } Override public void visitNode(Tree tree) { MethodInvocationTree mit (MethodInvocationTree) tree; if (!println.equals(mit.methodSelect().lastToken().text())) { return; } // 拿到点号左边的表达式判断是不是 System.out ExpressionTree expression mit.methodSelect().expression(); if (expression ! null expression.symbolType().is(java.lang.System)) { reportIssue(this, mit, 不要直接用 System.out请接入 SLF4J); } } }逻辑说明nodesToVisit的返回值决定这条规则的性能只订阅方法调用节点引擎就不会在类声明、变量声明上浪费时间。visitNode里先用lastToken().text()判断方法名是不是 println再通过methodSelect().expression()拿到点号左边的表达式调用symbolType().is(java.lang.System)确认它是 System 类。两步都通过才报问题缺一步都可能误伤自定义的MySystem.outln()这类代码。参数说明Tree.Kind枚举是 SonarJava 对 AST 节点的分类常见的有CLASS、METHOD_INVOCATION、METHOD、VARIABLE等。symbolType()返回的是符号类型信息is()方法接收的是 Java 类型全限定名必须写完整包名。我见过有人图省事写is(System)结果命中率为零因为符号系统里的类型名都是全限定名。2.3 注册链路一条规则从源码到界面要过四道门把上面两块内容串起来一条自定义规则从源码变成 Web 界面上可配置的规则要经过这四步插件入口类CustomRulesPlugin被 SonarQube 通过插件描述文件找到并实例化。addExtension把RulesDefinition和JavaCheckRegistrar注入上下文。RulesDefinition在管理界面生成仓库和规则元数据SonarQube 写入规则库。扫描 Java 源码时SonarJava 构建 AST执行JavaCheckRegistrar注册的所有访问器命中节点就reportIssue。其中第 2 步和第 4 步之间的“注册”是最容易被忽略的。看JavaCheckRegistrar的实现public class MyJavaCheckRegistrar implements JavaCheckRegistrar { Override public void register(RegistrarContext context) { context.registerClassesForRepository(MyJavaRulesDefinition.REPOSITORY_KEY, NoSystemOutRule.class, UtilityClassPrivateConstructorRule.class); } }逻辑说明registerClassesForRepository的第一个参数是仓库 key必须和RulesDefinition里定义的一致。后面是规则实现类数组SonarJava 会在扫描时把这些类实例化并挂到语法树遍历链路里。这里漏掉任何一条这条规则就是“菜单上有厨房没做”的状态发现时通常已经浪费了一整天。参数说明RegistrarContext是 SonarJava 提供给自定义插件的注册上下文不同版本里这个类的包名和访问方式有调整但接口语义没变过。复制模板代码时优先检查这个类有没有被addExtension注册很多自定义规则插件跑不起来根源都是这个类根本没进 IoC 容器。2.4 插件打包与问题类型决定规则能不能落地还有一个隐藏门打包。自定义规则插件要用sonar-packaging-maven-plugin打包这个插件会在 jar 里生成META-INF/sonar-plugin.propertiesSonarQube 靠这个文件找到插件入口类。pom 里的配置长这样plugin groupIdorg.sonarsource.sonar-packaging-maven-plugin/groupId artifactIdsonar-packaging-maven-plugin/artifactId version1.18.x/version extensionstrue/extensions configuration pluginClasscom.example.sonarqube.CustomRulesPlugin/pluginClass pluginDescription团队自定义Java规则/pluginDescription /configuration /plugin逻辑说明extensions设为true表示让这个 Maven 插件在生命周期里生效并生成插件描述文件。pluginClass指向刚才那个实现Plugin接口的入口类。打包完成后解压 jar 应该能在META-INF下看到sonar-plugin.properties。参数说明pluginDescription会显示在 SonarQube 管理页面的插件列表里建议写清楚规则仓库用途例如“电商订单服务代码规范”。这个文件不生成jar 拷进 SonarQube 的extensions/plugins目录后会被直接忽略web.log 里连报错都不会有是典型的静默失败。除了打包规则类型也要留心。创建规则时如果不调用setTypeSonarQube 默认按CODE_SMELL处理。这意味着你写了一条能发现空指针的规则它却和代码风格问题混在一起质量门禁里“不引入新的 Bug”这个条件根本拦不住它。所以每条规则都要显式声明是 BUG、VULNERABILITY 还是 CODE_SMELL并在Rule注解里补tags标签方便质量配置里检索。3. 把工程跑起来环境、构建与部署的三条主线3.1 pom.xml 里的依赖provided 才是插件的正确姿势工程能跑起来的第一个关键点是依赖配置。拆开这份资源的 pom.xml你会发现核心依赖的 scope 是provided而不是默认的compile。这和普通业务工程的习惯完全不同。看下面的依赖结构properties !-- 以你自己 SonarQube 实例的版本为准主版本号不要跨大版本 -- sonar-plugin-api.version9.9.x/sonar-plugin-api.version java-frontend.version7.4.x/java-frontend.version /properties dependencies dependency groupIdorg.sonarsource.api/groupId artifactIdsonar-plugin-api/artifactId version${sonar-plugin-api.version}/version scopeprovided/scope /dependency dependency groupIdorg.sonarsource.java/groupId artifactIdjava-frontend/artifactId version${java-frontend.version}/version scopeprovided/scope /dependency dependency groupIdorg.sonarsource.java/groupId artifactIdjava-checks-testkit/artifactId version${java-frontend.version}/version scopetest/scope /dependency /dependencies逻辑说明sonar-plugin-api和java-frontend只在编译时出现最终打出的插件 jar 不包含这些类。原因很简单运行环境里的 SonarQube 容器已经带着这些库如果把它们打进 jar运行时会出现两个版本的 API 类加载阶段直接 ClassCastException。java-checks-testkit则是测试专用包含JavaCheckVerifier这类工具类只在mvn test时出现在 classpath 里。参数说明版本号的选择不是“越新越好”而是要对齐目标 SonarQube 实例。插件 API 跨大版本经常有方法签名调整用 7.x 的 API 编译出的插件 jar装到 9.x 的 SonarQube 上启动时会出现NoSuchMethodError或AbstractMethodError。我一般先看生产环境的 SonarQube 版本再反查对应的sonar-plugin-api版本。另外maven.compiler.source和maven.compiler.target也要注意SonarQube 9.x 自带 JRE插件编译级别不能高于运行环境 JDK否则分析时的类型解析会出怪问题。3.2 IDEA 导入与目录定位先分清四个地方资源包里有.idea和.iml是标准的 IntelliJ IDEA 工程。导入方式不复杂解压后用 IDEA 的 Open 直接选中文件夹IDEA 识别到 pom.xml 会询问是否作为 Maven 工程导入确认即可。.idea里的 workspace.xml 包含的是本机路径信息不同机器打开时 IDEA 会重新加载不用管。工程里最容易混淆的是这几个目录的职责目录/文件作用常见误用src/main/java插件入口、规则仓库、规则实现把规则实现类误放到测试目录打包后规则缺失src/test/java基于 JavaCheckVerifier 的单元测试只写了测试类没有配套样例 Java 文件src/test/resources测试用的样例 Java 文件样例文件路径写错测试抛 FileNotFoundExceptiontargetMaven 构建产物目录把旧 jar 当新产物部署改的规则根本没编译进去参数说明target目录是 Maven 每次构建的产物会累积多次构建结果。build.sh里如果用ls target/*.jar | head -n 1这种取法分分钟取到旧 jar。我习惯在脚本里用mvn clean package先清空再构建保证target下只有一个新 jar。3.3 build.sh 的构建链一次打包一次部署这份资源里的build.sh承担了“编译 拷贝 提示重启”的完整链路。常见写法是这样的#!/usr/bin/env bash set -euo pipefail # 1. 编译并打插件包跳过测试可以省时间但建议首次完整跑 mvn clean package JAR_FILE$(ls target/*.jar | grep -v sources | grep -v tests | head -n 1) SONARQUBE_HOME${SONARQUBE_HOME:-/opt/sonarqube} # 2. 拷贝到插件目录SonarQube 只加载这里面的 jar cp $JAR_FILE ${SONARQUBE_HOME}/extensions/plugins/ # 3. 提示重启而不是自动重启生产环境不建议脚本直接重启 echo 插件已安装请在 SonarQube 管理页面确认系统重启后规则仓库可见逻辑说明set -euo pipefail让脚本在中间任何一步失败时立刻退出避免把打到一半的 jar 当作成品拷贝过去。SONARQUBE_HOME用环境变量加默认值的写法兼容个人开发机和生产服务器不同路径的情况。拷贝目标是extensions/plugins注意不是extensions/downloads后者是 SonarQube 做插件在线下载与更新用的目录不会作为已安装插件加载。参数说明grep -v sources | grep -v tests是为了过滤 Maven 生成的 sources 包和 test 包只留主插件 jar。有些模板还会顺手带-DskipTests跳过单测第一次跑建议去掉等确认规则没问题后再提速。3.4 验证安装是否成功先看日志再搜规则最后看插件描述部署完重启 SonarQube别急着拿项目去扫。先走三个验证点任何一个不过都能省下后面排错的时间。第一个是管理后台的插件列表看自定义插件是否出现第二个是web.log里面会打印插件加载异常第三个是看插件描述文件内容确认打包正确。# 查看 web.log 里是否有自定义插件相关的报错 grep -i mycompany\|custom /opt/sonarqube/logs/web.log | tail -n 20 # 直接解压检查插件描述文件不用登录服务器开 jar unzip -p target/mycompany-sonar-java-plugin.jar META-INF/sonar-plugin.properties逻辑说明第一条命令过滤 web.logSonarQube 插件加载失败时错误信息通常会包含插件名或仓库名。第二条命令是排查“插件被静默忽略”的杀手锏。如果unzip -p能看到文件内容里面应该有pluginClass这一行并且指向真实存在的入口类如果提示文件不存在说明sonar-packaging-maven-plugin没有接管打包回到 pom 里检查插件配置。参数说明unzip -p直接输出文件内容到终端不需要解压到磁盘。这步是我每次拿到自定义规则插件包必做的检查比翻 IDEA 的 Build 日志快得多。4. 写一条自己的规则仓库、访问器到测试的完整闭环4.1 先扩展仓库和注册器让新规则被看见前面讲机制时用的是NoSystemOut做例子现在走一遍从新增规则到打包的完整过程。假设团队想要一条规则工具类必须声明私有构造方法防止被外部实例化。第一步是把它写进MyJavaRulesDefinitionpublic class MyJavaRulesDefinition implements RulesDefinition { public static final String REPOSITORY_KEY mycompany-java; Override public void define(Context context) { NewRepository repo context .createRepository(REPOSITORY_KEY, java) .setName(My Company Java Rules); repo.createRule(UtilityClassPrivateConstructor) .setName(工具类需要私有构造方法) .setHtmlDescription(以 Util/Utils/Constants 结尾的类必须声明私有构造方法) .setSeverity(MAJOR) .setTags(convention, design) .setType(RuleType.CODE_SMELL); repo.done(); } }逻辑说明新增规则时先补元数据让管理界面能搜到它。setTags是给规则打标签质量配置里可以用标签过滤这里打了design和convention两个标签方便团队按标准检索。规则 key 用UtilityClassPrivateConstructor和后面规则类的Rule(key UtilityClassPrivateConstructor)一一对应。参数说明setHtmlDescription支持 HTML 片段描述可以在里面写“为什么要有这条规则”的简短说明。这条描述会被搜到写细一点能减少团队里“这规则是不是误报”的质疑。然后是注册器把规则实现类挂到分析引擎上public class MyJavaCheckRegistrar implements JavaCheckRegistrar { Override public void register(RegistrarContext context) { context.registerClassesForRepository( MyJavaRulesDefinition.REPOSITORY_KEY, NoSystemOutRule.class, UtilityClassPrivateConstructorRule.class); } }逻辑说明新增的类名出现在registerClassesForRepository的数组里SonarJava 扫描时才会实例化它。这里漏掉规则就是“菜单上有、厨房没做”的状态管理界面看着一切正常扫描结果永远为空。这个坑我踩过一次后养成了每次改注册器都顺手看一眼仓库 key 的习惯。4.2 访问器订阅类节点再判断构造器修饰符工具类私有构造这条规则订阅的节点类型是CLASS因为只有类声明才需要检查。逻辑分三步判断是不是工具类、找构造器、看构造器修饰符。注意一个隐蔽情况Java 类如果没有显式构造器编译器会生成一个默认的 public 无参构造器。对工具类来说这意味着“没有构造器”本身就是违规。代码要处理的就是这个边界Rule(key UtilityClassPrivateConstructor, description 工具类需要私有构造方法, tags {convention}) public class UtilityClassPrivateConstructorRule extends IssuableSubscriptionVisitor { Override public ListTree.Kind nodesToVisit() { // 只关心类声明其他节点不处理 return Collections.singletonList(Tree.Kind.CLASS); } Override public void visitNode(Tree tree) { ClassTree cls (ClassTree) tree; if (!isUtilityClass(cls)) { return; } boolean hasPrivateConstructor false; for (Tree member : cls.members()) { if (!member.is(Tree.Kind.CONSTRUCTOR)) continue; MethodTree ctor (MethodTree) member; if (ctor.modifiers().modifiers().stream() .anyMatch(m - m.is(Tree.Kind.PRIVATE))) { hasPrivateConstructor true; } } if (!hasPrivateConstructor) { reportIssue(this, cls, 工具类必须有私有构造方法防止被外部实例化); } } private boolean isUtilityClass(ClassTree cls) { String name cls.simpleName(); return name.endsWith(Util) || name.endsWith(Utils) || name.endsWith(Constants); } }逻辑说明nodesToVisit只返回CLASS引擎只会在类节点上回调。isUtilityClass简单按类名后缀判断工程里还可以加上“类内全是 static 方法”的判断但后缀约定通常已经够用。cls.members()返回类的全部成员包括字段、方法、构造器逐个找出构造器后检查是否有private修饰符。如果没有找到任何 private 构造器就报问题。参数说明ctor.modifiers().modifiers()返回的是修饰符集合每个元素是Tree节点用m.is(Tree.Kind.PRIVATE)判断是否为 private。这套写法比直接调symbolType()更底层但能处理一个真实边界构造器上如果同时有Autowired注解修饰符集合里还是能正确找到PRIVATE这个节点不会被注解干扰。默认构造器的情况也被这个逻辑覆盖了——类没有显式构造器时members()里不会有构造器节点hasPrivateConstructor保持 false规则会正确报问题。4.3 样例文件与 JavaCheckVerifier把误报挡在打包前规则写完后测试模板通常是基于样例文件的。SonarJava 测试工具包里的JavaCheckVerifier要求你把存在预期问题的 Java 文件放到指定路径用注释标记问题发生的位置。看这个样例文件// src/test/resources/UtilityClassPrivateConstructor.java class StringUtils { StringUtils() { } // Noncompliant {{工具类必须有私有构造方法}} static String trim(String s) { return s; } } class DateUtil { private DateUtil() { } // compliant static String now() { return now; } }然后是测试类public class UtilityClassPrivateConstructorRuleTest { Test public void should_report_on_public_constructor() { JavaCheckVerifier.verify( src/test/resources/UtilityClassPrivateConstructor.java, new UtilityClassPrivateConstructorRule()); } Test public void should_be_silent_on_private_constructor() { JavaCheckVerifier.verifyNoIssue( src/test/resources/UtilityClassPrivateConstructor.java, new UtilityClassPrivateConstructorRule()); } }逻辑说明verify方法要求样例文件里必须有Noncompliant注释标记并且推荐用{{消息文本}}格式声明问题描述测试框架会把规则实际报告的文本和注释里的文本做比对。verifyNoIssue则要求整个文件一个错误都不能报。两个方法用处不同一个验证规则能发现违规一个验证规则不误伤合规代码。参数说明文件路径是相对于工程根目录的路径不是 classpath。JavaCheckVerifier会自动解析样例文件对应的语法树并注入规则实例。测试时会真实构建 AST所以样例文件必须是能通过编译的合法 Java 代码写了一半的伪代码会导致测试直接挂在语法解析阶段。4.4 参数化RuleProperty 让使用者自己调白名单如果规则里出现“某些类名允许豁免”的需求就得给规则加参数。SonarJava 支持用RuleProperty声明可调参数参数默认值在 Web 界面的质量配置里可以直接改不必重新打包Rule(key UtilityClassPrivateConstructor, description 工具类需要私有构造方法) public class UtilityClassPrivateConstructorRule extends IssuableSubscriptionVisitor { RuleProperty( key excludeClasses, description 不检查的类名后缀逗号分隔, defaultValue ) String excludeClasses; private boolean isUtilityClass(ClassTree cls) { String name cls.simpleName(); if (excludeClasses ! null Arrays.asList(excludeClasses.split(,)).contains(name)) { return false; } return name.endsWith(Util) || name.endsWith(Utils) || name.endsWith(Constants); } }逻辑说明RuleProperty注解的字段会在规则注册时被 SonarQube 扫描到并在质量配置页面生成输入框。这里字段可见性设为包内可见是为了让单元测试能直接给字段赋值因为测试类和规则类放在同包下。如果把字段写成 private测试里只能靠反射改值代码评审时很容易被打回。参数说明defaultValue设置为空字符串是为了兼容旧质量配置——如果这个参数是后加的而线上配置文件里没有对应字段SonarQube 会使用默认值而不是报错。逗号分隔的白名单设计比较轻量满足大多数“个别类要豁免”的场景。5. 避坑与常见问题我在这套包上面踩过的五个坑5.1 规则注册了但 Web 界面看不到现象build.sh 正常执行jar 拷贝到了 SonarQube 的插件目录重启后质量配置里搜不到自定义仓库规则页面也找不到任何新增规则。原因两种可能性排第一的是sonar-packaging-maven-plugin没有配置pluginClass或者pluginClass指向的类不存在导致 jar 里没有META-INF/sonar-plugin.properties。排第二的是插件被放进了extensions/downloads而不是extensions/plugins前者的 jar 不会被当作已安装插件加载。解决先解压 jar 确认sonar-plugin.properties存在检查pluginClass指向的入口类再确认目录是extensions/plugins。这两步都过了再看 web.log 里是否有插件加载失败的异常栈。我每次部署新版本都会强制自己先跑一遍unzip -p检查不再相信“上次就是这么放的”。5.2 SonarQube 起不来日志里全是 NoSuchMethodError现象插件复制进去后重启 SonarQube服务起不来web.log 里抛NoClassDefFoundError或NoSuchMethodError堆栈指向org.sonar.api或com.sonar.plugins.java.api里的类。原因pom 里sonar-plugin-api或java-frontend的版本和目标 SonarQube 大版本不一致。比如用 7.9 API 编译的插件装到 9.x 的 SonarQube 上容器里的 API 类已经没有旧方法了加载时直接抛错。解决把这两个依赖的版本号对齐生产环境 SonarQube 的版本同时确认 scope 是provided。scope 写错的后果是 API 类被打进插件 jar运行时和容器自带的类形成两份出现的问题更隐蔽报错信息可能指向一个根本不是你写的类。5.3 规则能搜到但扫描从不报问题现象Web 规则页面能看到自定义仓库和规则质量配置里也激活了但项目扫描完成后一个问题都没有。原因两个方向排查。第一规则类没有被JavaCheckRegistrar注册规则只是元数据存在于系统里分析引擎根本没执行它。第二规则实现里订阅的Tree.Kind不对比如实际要检查方法调用订阅的却是方法声明节点对不上自然不触发。解决先用单元测试验证规则能报问题——JavaCheckVerifier.verify通过说明实现没问题问题在注册或配置再检查registerClassesForRepository是否包含该类最后确认质量配置里规则的严重程度没有被项目覆盖策略拉低或禁用。这条排查顺序我写进了团队的规则开发文档里。5.4 单测过了真实项目却误报一堆现象样例文件测试全部通过部署后扫描真实项目误报率极高。比如规则把字符串常量里的System.out.println也当成方法调用把注释里的代码片段也标记为问题。原因样例文件写得太干净没有覆盖字符串、注释、lambda、多行表达式这些干扰边界。AST 订阅本身不受注释和字符串干扰但如果你在规则里用了原始的token.text()做判断拿到的文本可能来自字符串内容或者来自Deprecated注解里的引用。解决给样例文件补足干扰场景把违规调用写进注释里写进字符串常量里写进 lambda 表达式里分别标记compliant然后跑verifyNoIssue确认不误报。规则实现里尽量用 AST 节点的结构化信息比如symbolType()、methodSelect()而不是原始文本能避开大量这类问题。5.5 升级 SonarQube 后旧插件直接失效现象SonarQube 从 8.x 升到 9.x扫描开始抛NoSuchMethodError指向IssuableSubscriptionVisitor的某个方法插件代码没动过却像被换了引擎。原因SonarJava 的 API 在 8.x 到 9.x 之间做过多次内部调整reportIssue的方法签名、JavaCheckRegistrar的包名路径都变过旧版编译产物跑在新容器上就会出现接口不兼容。解决升级 SonarQube 后把自定义规则插件也加进升级计划用新容器对应的 API 版本重新编译并跑一遍完整测试。这条我用一次深夜上线换来的教训SonarQube 升级排期里永远要把第三方规则插件列为受影响项不能默认“插件没动就没事”。6. 把规则用起来验证、调试与团队协作的三个技巧6.1 本地验证三件套单测、样例工程扫描、verbose 日志自定义规则的开发节奏和普通业务代码不一样最快的验证路径是三件套。第一件是单元测试mvn -DtestUtilityClassPrivateConstructorRuleTest test单跑某条规则的测试几分钟内确认逻辑边界。第二件是本地拿一个样例工程跑 sonar-scanner这是最接近生产的验证方式样例工程里放上合规和违规两类代码扫描完成后直接看 JSON 报告里的 rule 字段。第三件是开 verbose 日志sonar-scanner -Dsonar.verbosetrue -Dsonar.java.source17逻辑说明-Dsonar.java.source显式声明扫描目标的 Java 版本避免 SonarJava 因为拿不准源码级别而跳过部分语法解析。-Dsonar.verbosetrue会在控制台输出规则加载和执行的详细日志搜索自定义仓库的 key能直接确认规则类有没有进入分析链路。6.2 断点调试与回归习惯从“改完就发”到“跑完再发”遇到规则该报不报的情况最有效的调试方式是在visitNode方法上打断点然后用JavaCheckVerifier的测试方法作为入口跑。IDEA 里可以运行单个测试方法断点命中后能看到tree对应的源码位置、节点类型、修饰符列表比反复部署 SonarQube 快一个量级。我通常先用这个方式确认语法路径再补样例文件。从那以后我每次改完规则都强制自己走一遍固定的四步流程先跑旧测试集确认没破坏其他规则再补新的Noncompliant和compliant样例然后本地样例工程扫描看真实项目里的误报情况最后检查质量配置里规则的激活状态和严重程度确认 Web 端展示正常。这套流程不算复杂但真的能拦住绝大多数翻车尤其是“单测过了上了生产就放飞”那类问题。规则开发是个慢功夫越依赖玄学排查越是前期验证没做到位。希望帮到你。本文还有配套的精品资源点击获取