熊猫 Java 开发规范

熊猫企业级 Java 代码质量管理体系建设方案与实施指南

0. 执行摘要 (Executive Summary)

1.1 项目背景与紧迫性

• 可靠性风险极高：存在 94 个 Bug，其中 14 个为阻塞级（Blocker） 的资源泄露问题，20 个为空指针异常（NPE） 风险。这直接解释了为何线上系统偶尔出现内存溢出和莫名崩溃的现象。

• 维护成本巨大的技术债务：扫描发现了 4,130 个代码异味（Code Smells），技术债务（不合规代码预估的修复所需人工工作量时间）高达 75 天 7 小时。这意味着每进行一次功能迭代，开发人员都需要花费大量时间在“排雷”和理解晦涩难懂的遗留代码上，严重拖慢了交付速度。

• 工程化规范缺失：421 次 错误的静态成员访问，370 次 泛型异常抛出，337 次 字符串硬编码。这些数据表明团队缺乏统一的编码标准，且对 Java 面向对象设计原则的理解存在偏差。

1.2 建设目标

1. 阶段一（熔断止损）： 部署“必须”级规则，拦截可能导致崩溃、资损和安全漏洞的代码。目标是让构建失败，强制修复致命问题。

2. 阶段二（规范清洗）： 启用“推荐”级规则，治理代码风格、提升可读性、降低认知复杂度。

3. 阶段三（现代化演进）： 引入单元测试覆盖率要求，并针对 JDK 21 / Spring Boot 3.x 升级预置兼容性规则。

1.3 静态检查规则列表

2. 实施策略与规则分级方法论

2.1 规则优先级定义

2.2 质量门禁（Quality Gate）配置建议

• 新代码：必须满足所有“必须”规则，且整体技术债务（包括”必须+推荐”规则的不合规代码量）比率 < 5%。

• 全量代码：允许存在遗留债务，但不得新增“必须”级别的问题。

3. 详细规则评估与说明：一、编程规约 (Programming Conventions)

3.1 命名风格 (Naming Style)

[必须] 常量命名应符合规范 (Constant names should comply with a naming convention) (java:S115)

• SonarQube 规则: java:S115。

• 规则含义: static final 修饰的常量必须全部大写，单词间用下划线隔开。正则表达式：^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$。

• 目的与意义：可读性。在代码中能一眼区分出常量与变量，避免魔术值满天飞。

• 阿里规范对应：【强制】常量命名应该全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。

• 违规现状：MDC 项目检测到 59 次违规。

• 代码示例:

// 错误示例 (Noncompliant)

public static final int max_stock = 100;

public static final String configName = "config";

// 正确示例 (Compliant)

public static final int MAX_STOCK = 100;

public static final String CONFIG_NAME = "config";

[必须] 方法名应符合规范 ( java:S100)

• SonarQube 规则： java:S100 (Method names should comply with a naming convention) 。

• 规则含义：方法名使用 lowerCamelCase 风格。SonarQube 默认正则为 ^[a-z][a-zA-Z0-9]*$。

• 现状分析：分析报告显示，mdc 项目中存在 22 次 java:S100 违规 。

• 原因：该违规通常源于两种情况：
1. 测试方法命名： 开发人员常在单元测试中使用下划线（如 test_user_login_success）以提高可读性，但这违反了标准 Java 规范。
2. C# 或 C++ 习惯遗留： 使用 PascalCase（如 DoSomething）命名方法。

• 技术影响： Java Bean 规范（JavaBeans Specification）严重依赖命名约定。例如，Spring 框架和 Jackson 序列化库通过反射查找 get/set 前缀的方法。如果方法命名不规范（如 get_User），可能导致属性注入失败或 JSON 序列化异常，直接引发运行时错误。

• 代码示例：

// 错误示例
public class MyClass {

    // Noncompliant: Method name "DoSomething" does not start with a lowercase letter
    public int DoSomething() {
        // ... implementation ...
        return 0;
    }
}

// 正确示例
public class MyClass {

    // Compliant: Method name "doSomething" starts with a lowercase letter (camelCase)
    public int doSomething() {
        // ... implementation ...
        return 0;
    }
}

[必须] 参数名、成员变量、局部变量等应符合规范 ( java:S116, java:S117)

• SonarQube 规则：
• java:S116：字段名称应符合命名约定，要求字段名称遵循指定的正则表达式。默认约定通常为驼峰命名法（camelCase），以小写字母开头。
• java:S117：局部变量名 (Local variable names) 应符合规范。

• 现状分析：mdc 项目有 46 次 字段命名违规（S116）和 29 次 局部变量命名违规（S117）。

• 目的和意义：序列化灾难（Serialization Hazard）。阿里巴巴手册特别指出，布尔属性名为 isSuccess 时，其 getter 方法通常生成为 isSuccess()。部分 RPC 框架或序列化工具（如 RPC 框架反向解析）在推断属性名时，会去除 getter 的 is 前缀，得出属性名为 success，导致无法找到对应的 isSuccess 字段，从而抛出异常或导致数据丢失。SonarQube 的 S116 规则虽然主要检查正则匹配，但结合阿里巴巴手册，应在团队中强制禁止布尔字段的 is 前缀。

• 代码示例：

// 错误示例
public class MyClass {
  private int my_field; // Noncompliant
  protected String another_field; // Noncompliant

  public void setMyField(int new_value) { // This rule is for fields, not parameters (S117)
    this.my_field = new_value;
  }
}

// 正确示例
public class MyClass {
  private int myField; // Compliant
  protected String anotherField; // Compliant

  public void setMyField(int newValue) {
    this.myField = newValue;
  }
}

[必须] 包名应符合规范 (Package names should comply with a naming convention) ( java:S120)

• SonarQube 规则: java:S120。

• 规则含义: 包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。

• 目的与意义: 避免在 Windows/Linux 跨平台部署时因大小写敏感性导致的文件加载错误。

• 阿里规范对应：【强制】包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。

• 代码示例:

// 错误示例

package com.MyCompany.MDC;

// 正确示例

package com.mycompany.mdc;

[推荐] 抽象类与接口命名规范 (Abstract class names / Interface names) (java:S114, java:S118)

• SonarQube 规则 java:S114 (Interface), java:S118 (Abstract)。

• 规则含义: 抽象类建议以 Abstract 或 Base 开头；接口虽无强制前缀，但应体现能力（如 able 结尾）。

• 阿里规范对应：【强制】抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾。

• 调整说明：考虑到 mdc 项目历史遗留代码较多，重命名类涉及大量文件变更，初期作为“推荐”，但对新代码应作为“必须”。

• 代码示例：

// 错误示例
public class MyClass {

    public void doSomething() {
        MyInterface myInterface;
        // ...
    }
}

interface myInterface {
    void performAction();
}

// 正确示例
public class MyClass {

    public void doSomething() {
        MyInterface myInterface;
        // ...
    }
}

interface MyInterface {
    void performAction();
}

3.2 常量定义 (Constant Definition)

[推荐] 字符串字面量不应重复 (String literals should not be duplicated) (java:S1192)

• SonarQube 规则: java:S1192。

• 规则含义: 任意长度超过 5 的字符串字面量，如果在一个文件中重复出现 3 次及以上，应提取为常量。

• 违规现状：mdc 项目中有 337 个此类问题。

• 目的与意义：维护性问题。硬编码的字符串是维护的噩梦，一旦业务逻辑变更（如 API 路径改变），极易漏改导致 Bug。

• 阿里规范对应：【强制】不允许任何魔法值（即未经预先定义的常量）直接出现在代码中。

• 代码示例:

// 错误示例

public void process() {

doStep("CRITICAL_ERROR");

log("CRITICAL_ERROR");

notify("CRITICAL_ERROR"); // 重复3次，若拼写错误极难发现

}

// 正确示例

private static final String ERROR_TYPE = "CRITICAL_ERROR";

public void process() {

doStep(ERROR_TYPE);

log(ERROR_TYPE);

notify(ERROR_TYPE);

}

3.3 面向对象规约 (OOP Rules)

[必须] 避免通过子类类型访问父类静态成员 (Static base class members should not be accessed via derived types) (java:S3252)

• Sonar Key: java:S3252。

• 规则含义: 静态成员属于类本身，不应通过子类名或子类实例访问。

• 目的与意义：混淆视听。这会让阅读者误以为该成员属于子类，掩盖了代码的真实归属。

• 违规现状：这是 mdc 项目中最高频的问题（421 次）。这表明团队对 static 关键字的理解存在普遍偏差。

• 阿里规范对应：【强制】避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成本，直接用类名来访问即可。

• 代码示例:

class Parent { public static int count = 0; }

class Child extends Parent {}

// 错误示例

Child.count = 10; // 极易误导，以为是 Child 的属性

new Child().count = 10; // 更是大忌，甚至产生 NPE 风险（如果对象为 null，虽然静态访问不抛 NPE，但逻辑极其怪异）

// 正确示例

Parent.count = 10;

[必须] 所有的覆写方法必须加 @Override 注解 ("@Override" should be used on overriding and implementing methods) (java:S1161)

• SonarQube 规则：java:S1161。

• 规则含义: 只要是覆盖父类方法或实现接口方法，必须显式标注 @Override。

• 目的与意义：安全性。如果父类方法签名发生变更，而子类未加注解，子类方法会悄无声息地变成一个“新方法”，导致多态失效，产生极难排查的逻辑 Bug。

• 阿里规范对应：【强制】所有的覆写方法，必须加 @Override 注解。

• 代码示例:

// 错误示例

public boolean equals(Object obj) {... } // 如果参数类型写错，变成了重载而非覆盖，导致 Hash 集合行为异常

// 正确示例

@Override
public boolean equals(Object obj) {... } // 编译器会强制检查签名

[必须] 实用类不应有公共构造函数 (Utility classes should not have public constructors) (java:S1118)

• SonarQube 规则: java:S1118。

• 规则含义: 只有静态方法/属性的工具类（如 StringUtils）不应被实例化，必须添加一个显式的私有构造函数。

• 目的与意义：。工具类不仅不需要实例化，实例化甚至可能带来状态污染。mdc 项目中有 149 次违规。

• 阿里规范对应：【推荐】工具类不允许有 public 或 default 构造方法。

• 代码示例:

// 错误示例

public class DateUtils {

public static String format(Date d) {... }

}

// 正确示例

public class DateUtils {

private DateUtils() {

throw new IllegalStateException("Utility class");

}

public static String format(Date d) {... }

}

3.4 集合处理 (Collection Handling)

[必须] 集合转数组必须使用正确类型 (Collection.toArray() should be passed an array of the proper type) (java:S3020)

• SonarQube 规则: java:S3020。

• 规则含义: 使用 list.toArray(new T) 而非 list.toArray()。

• 违规现状：mdc 项目发现了 3 个此类问题。

• 目的与意义：类型安全问题。无参的 toArray() 返回 Object，如果强制转换为 String 会抛出 ClassCastException。这是运行时崩溃的常见原因。

• 阿里规范对应：【强制】使用集合转数组的方法，必须使用集合的 toArray(T array)，传入的是类型完全一致、长度为 0 的空数组。

• 代码示例:

List<String> list = new ArrayList<>();

// 错误示例

String array = (String) list.toArray(); // 运行时抛出 ClassCastException

// 正确示例

String array = list.toArray(new String);

4. 详细规则评估与说明：二、异常日志 (Exceptions & Logs)

4.1 异常处理

[必须] 捕获异常时保留原始异常对象 (java:S1166)

• SonarQube 规则：java:S1166 (Exception handlers should preserve the original exceptions) 。

• 阿里巴巴规约： 【强制】捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之

• 技术分析：异常链丢失当开发者编写如下代码时：

try {... } catch (IOException e) { error("File error"); // 丢失了堆栈信息}

原始的异常堆栈（Stack Trace）被切断。在生产环境中，运维人员只能看到“File error”，而无法定位是权限问题、磁盘已满还是文件不存在。阿里规范要求： 必须在日志中传入异常对象 LOGGER.error("File error", e)，或者将异常包装后重新抛出 throw new RuntimeException(e)，以保留完整的异常链（Caused By）。

• 代码示例：

// 错误示例
try {
    // ... potentially error-prone code ...
} catch (Exception e) { // Noncompliant
    LOGGER.info("An error occurred while processing data.");
    // The exception variable 'e' is neither logged nor rethrown.
}

try {
    // ... potentially error-prone code ...
} catch (Exception e) { // Noncompliant
    // Only the message is logged, the crucial stack trace is lost.
    LOGGER.info("Error details: " + e.getMessage());
}

try {
    // ... potentially error-prone code ...
} catch (Exception e) { // Noncompliant
    // A new RuntimeException is created, but 'e' is not passed to the constructor.
    throw new RuntimeException("A new problem occurred");
}

// 正确示例

try {
    // ... potentially error-prone code ...
} catch (Exception e) { // Compliant
    // The full exception, including the stack trace, is logged.
    LOGGER.error("An error occurred while processing data", e);
}

try {
    // ... potentially error-prone code ...
} catch (Exception e) { // Compliant
    // The original exception 'e' is passed as the cause to the new exception.
    throw new RuntimeException("A new problem occurred", e);
}

int myInteger;
try {
    myInteger = Integer.parseInt(myString);
} catch (NumberFormatException e) { // Compliant by default (typically ignored by the rule)
    // Handled as a non-exceptional outcome
    myInteger = 0;
}

[必须] 不应忽略 InterruptedException ("InterruptedException" and "ThreadDeath" should not be ignored) (java:S2142)

• SonarQube 规则: java:S2142。

• 规则含义: 捕获 InterruptedException 后，必须通过 Thread.currentThread().interrupt() 恢复中断状态，或者重新抛出。

• 违规现状：mdc 项目中有 11 次违规。

• 目的与意义:线程生命周期。忽略中断异常会导致线程无法响应停止指令，造成线程池无法关闭、应用无法优雅停机，甚至导致“僵尸线程”耗尽资源。

• 阿里规范对应：虽然阿里手册未显式列出此条，但这属于 Java 并发编程的基本底线规则。

• 代码示例:

// 错误示例

try {

Thread.sleep(1000);

} catch (InterruptedException e) {

e.printStackTrace(); // 错误：吞掉了中断信号

}

// 正确示例

try {

Thread.sleep(1000);

} catch (InterruptedException e) {

Thread.currentThread().interrupt(); // 恢复中断状态

// 或者 throw new RuntimeException(e);

}

[必须] 避免抛出通用异常 (Generic exceptions should never be thrown) (java:S112)

• SonarQube 规则: java:S112。

• 规则含义: 方法签名中不应抛出 Exception、RuntimeException 或 Throwable。

• 违规现状：mdc 中有 370 次此类问题。

• 目的与意义：抛出通用异常使得调用者无法区分是 SQL 错误、IO 错误还是业务逻辑错误，导致上层无法做针对性的重试或回滚，通常只能粗暴地打印日志。

• 阿里规范对应：【推荐】定义时区分 unchecked / checked 异常...应使用有业务含义的自定义异常。

• 代码示例:

// 错误示例

public void processData() throws Exception {... }

// 正确示例

public void processData() throws IOException, DataFormatException {... }

[必须] 必须关闭资源 (Resources should be closed) (java:S2095)

• SonarQube 规则: java:S2095。

• 规则含义: 实现了 Closeable 接口的对象（如 InputStream, Connection）必须被关闭。

• 违规现状：mdc 项目中有 14 个此类 Blocker 级问题。

• 目的与意义: 未关闭的资源会导致文件句柄耗尽（Too many open files）或数据库连接池枯竭，直接导致系统崩溃 / 服务宕机。
阿里规范对应：【强制】finally 块必须对资源对象、流对象进行关闭，有异常也要做 try-catch。

• 代码示例:

// 错误示例

FileInputStream fis = new FileInputStream("file.txt");

fis.read(); // 如果这里抛异常，close 永远不会执行

fis.close();

// 正确示例 (JDK 1.7+ try-with-resources)

try (FileInputStream fis = new FileInputStream("file.txt")) {

fis.read();

}

4.2 日志规约

[必须] 禁止使用 System.out/err 进行日志记录 (Standard outputs should not be used directly to log anything) (java:S106)

• SonarQube 规则：java:S106。

• 规则含义: 必须使用日志框架（如 SLF4J, Logback）记录日志，而不是 System.out.println 或 e.printStackTrace()。

• 违规现状：mdc 项目中发现了 151 次违规。

• 目的与意义：性能与运维问题。标准输出（Stdout）无法控制日志级别，无法按天轮转文件，且大量 I/O 操作会严重拖慢程序性能。

• 阿里规范对应：【强制】生产环境禁止使用 System.out 或 System.err 输出或使用 e.printStackTrace() 打印异常堆栈。

• 代码示例:

// 错误示例

System.out.println("User login failed: " + e.getMessage());

e.printStackTrace();

// 正确示例

logger.error("User login failed", e);

5. 详细规则评估与说明：四、安全规约 (Security)

[必须] 禁止硬编码凭证 (Credentials should not be hard-coded) (java:S2068)

• SonarQube 规则: java:S2068。

• 规则含义: 代码中不应出现 password, secret, token 等变量赋值为硬编码字符串。

• 违规现状：mdc 项目中发现 1 个 Blocker 级凭证泄露风险。

• 目的与意义: 安全风险。源码一旦泄露（如推送到公共 Git），数据库或服务凭证即刻暴露。

• 阿里规范对应：【强制】配置文件中的密码需要加密。

• 代码示例:

// 错误示例

String password = "admin";

// 正确示例

String password = System.getenv("DB_PASSWORD");

[必须] 依赖库不应使用 "system" 范围 (Dependencies should not have "system" scope) (xml:S3422)

• SonarQube 规则: xml:S3422 (针对 pom.xml)。

• 规则含义: Maven 依赖不应使用 system scope 且指向本地路径。

• 违规现状：mdc 项目中有 3 个此类 Critical 问题。

• 目的与意义: 导致代码不可移植。这导致代码在其他团队用户机器上或 Jenkins 服务器上无法构建，因为它们没有对应的本地 jar 包路径。

• 代码示例（错误代码）:

<dependency>

<scope>system</scope>

<systemPath>C:\Users\Dev\lib\my-lib.jar</systemPath>

</dependency>

• 修正方案：引入私有 maven 仓库存放元 system 类型的依赖库。

6. 详细规则评估与说明：六、集合与并发 (Collections & Concurrency)

[必须] 禁止引用空指针 (Null pointers should not be dereferenced) (java:S2259)

• SonarQube 规则: java:S2259。

• 规则含义: 静态分析检测到某条执行路径可能会导致 NPE。

• 目的与意义: 稳定性。NPE 是 Java 应用最常见的崩溃原因。mdc 项目中有 20 个 Major 级空指针隐患。

• 阿里规范对应：【推荐】防止 NPE，是程序员的基本修养。

• 修正方案：在代码路径保证所有可能的 null 指针在使用前必须做检查。

• 代码示例：

// 错误示例
public void paint(Color color) {
    if (color == null) {
        // ... some other logic or return
    }
    // SonarQube will flag the following line because 'color' has an unchecked nullable state 
    // when the code flow reaches this point if the initial check condition isn't an early exit.
    System.out.println("The color's name is: " + color.toString()); // Noncompliant
}

// 正确示例
import java.util.Objects;

public void paint(Color color) {
    // Check for null and return or handle the case appropriately
    if (color == null) {
        System.out.println("Color is null, cannot paint.");
        return;
    }
    // The code below this point is considered safe by SonarQube due to the explicit null check
    System.out.println("The color's name is: " + color.toString()); // Compliant
}

[必须] 禁止使用 BigDecimal(double) 构造函数 ("BigDecimal(double)" should not be used) (java:S2111)

• SonarQube 规则: java:S2111。

• 规则含义: 避免使用 new BigDecimal(0.1)。

• 目的与意义：精度灾难。double 类型的 0.1 在计算机中无法精确表示，使用该构造函数会得到 0.10000000000000000555...，导致财务计算金额对不上。

• 违规现状：mdc 项目中有 8 次违规。

• 阿里规范对应：【强制】禁止使用构造方法 BigDecimal(double) 的方式把 double 值转化为 BigDecimal 对象。

• 代码示例:

// 错误示例

BigDecimal bd = new BigDecimal(0.1);

// 正确示例

BigDecimal bd = BigDecimal.valueOf(0.1); // 或者 new BigDecimal("0.1")

[必须] 使用 isEmpty() 判断所有集合内部的元素是否为空 (java:S1155)

• SonarQube 规则： java:S1155 (.isEmpty() should be used to test for emptiness) 。

• 阿里巴巴规约： 【强制】判断所有集合内部的元素是否为空，使用 isEmpty() 方法，而不是 size() == 0。

• 性能与时间复杂度分析：虽然在 ArrayList 中 size() 是 O(1) 操作，但在某些并发集合（如 ConcurrentLinkedQueue）中，计算 size() 需要遍历整个链表，时间复杂度为 O(n)。相比之下，isEmpty() 仅需检查头节点是否为空，永远是 O(1) 操作。此外，isEmpty() 具有更好的语义可读性（Readability）。

• 代码示例：

import java.util.List;

// 错误示例
public class S1155Example {
    public void processList(List<String> items) {
        // Noncompliant: Uses .size() == 0
        if (items.size() == 0) {
            System.out.println("List is empty");
        }

        // Noncompliant: Uses .size() > 0
        if (items.size() > 0) {
            System.out.println("List is not empty");
        }
    }
}

// 正确示例
public class S1155Example {
    public void processList(List<String> items) {
        // Compliant: Uses .isEmpty()
        if (items.isEmpty()) {
            System.out.println("List is empty");
        }

        // Compliant: Uses !.isEmpty()
        if (!items.isEmpty()) {
            System.out.println("List is not empty");
        }
    }
}

7. 详细规则评估与说明：代码质量与异味 (Code Smells)

[推荐] 避免重复的条件分支 (S1871)

• SonarQuba 规则： java:S1871 (Duplicate branches) ：同一个条件结构中的两个分支不应该有完全相同的实现方式。

• 违规统计： mdc 项目有 39 次 违规 。

• 目的和意义：深层隐患。 当 if 和 else 分支执行相同的逻辑代码时，通常意味着：
1. 冗余分支： 存在多余的条件判断，应该移除。
2. 复制粘贴错误（Copy-Paste Error）： 这是一个潜在的 Bug。开发者可能意图在 else 分支处理不同逻辑，但复制后忘记修改。

• 阿里巴巴映射： 手册中【推荐】尽量减少重复代码，S1871 是检测逻辑重复的有效手段。

• 代码示例：

// 错误示例
if (a instanceof Dad d) {
    father = d;
} else if (b instanceof Dad d) {
    father = d;
}

// 正确示例
if (a instanceof Dad d || b instanceof Dad d) {
    father = d;
}

[推荐] 合并可折叠的 IF 语句 (S1066)

• SonarQuba 规则： java:S1066 (Mergeable "if" statements should be combined) 。

• 违规现状： mdc 项目有 20 次 违规 。

• 意义和目的：if (conditionA) { if (conditionB) {... }}这种嵌套结构增加了代码的缩进深度，消耗了开发者的“认知栈”空间。根据认知复杂度（Cognitive Complexity）理论，每增加一层嵌套，理解代码所需的脑力成本呈线性甚至指数级上升。

• 改进建议： 应当合并为 if (conditionA && conditionB)。这不仅减少了行数，更使逻辑原子化，便于单元测试覆盖。

• 代码示例：

import java.io.File;

// 错误示例
public class SonarS1066Example {

    public void processFile(File file) {
        if (file != null) {
            // SonarQube flags this nested if statement
            if (file.isFile() || file.isDirectory()) { 
                System.out.println("Processing: " + file.getName());
                // ... further processing ...
            }
        }
    }
}

// 正确示例
public class SonarS1066Example {

    public void processFile(File file) {
        // Conditions merged into a single if statement
        if (file != null && (file.isFile() || file.isDirectory())) {
            System.out.println("Processing: " + file.getName());
            // ... further processing ...
        }
    }
}

[推荐] 避免代码中被注释掉的逻辑 (Sections of code should not be commented out) (java:S125)

• SonarQube 规则: java:S125。

• 规则含义: 检测到连续的代码行被注释。

• 目的与意义：影响代码质量。mdc 项目中有 390+ 处此类问题。这些代码被称为“僵尸代码”，会干扰阅读，且随着重构会迅速失效。应利用 Git 历史记录来保存旧代码，而不是注释在源文件中。

• 阿里规范对应：【参考】谨慎注释掉代码...如果无用，则删除。

[推荐] 认知复杂度不应过高 (Cognitive Complexity of methods should not be too high) (java:S3776)

• SonarQube 规则: java:S3776。

• 规则含义: 方法中的 if, else, for, switch 嵌套和组合过于复杂，超过阈值（默认 15）。

• 违规现状：mdc 有 205 个此类问题。

• 目的与意义：影响代码维护性。这种代码是“大脑杀手”，极难编写单元测试，也是 Bug 的温床。

• 阿里规范对应：【推荐】单个方法的总行数不超过 80 行。

• 代码示例：

// 错误示例
public class ComplexityExample {

    double calculateDiscount(double price, User user) {
        // Complexity +1 (if)
        if (isEligibleForDiscount(user)) {
            // Complexity +2 (nested if)
            if (user.hasMembership()) {
                return price * 0.9;
            } 
            // Complexity +1 (else)
            else if (user.ordersCount() == 1) { 
                return price * 0.95;
            } 
            // Complexity +1 (else)
            else { 
                return price;
            }
        } 
        // Complexity +1 (else)
        else { 
            return price;
        }
        // Total complexity: 6
    }
    
    // Helper methods (imaginary)
    boolean isEligibleForDiscount(User user) { return true; }
    class User {
        boolean hasMembership() { return true; }
        int ordersCount() { return 1; }
    }
}

// 正确示例
public class ComplexityExampleRefactored {

    double calculateDiscount(double price, User user) {
        // Complexity +1 (if)
        if (!isEligibleForDiscount(user)) {
            return price;
        }
        // Complexity +1 (if)
        if (user.hasMembership()) {
            return price * 0.9;
        }
        // Complexity +1 (if)
        if (user.ordersCount() == 1) {
            return price * 0.95;
        }
        return price;
        // Total complexity: 3
    }
    
    // Helper methods (imaginary) - the logic is moved here, 
    // keeping the main method clean.
    boolean isEligibleForDiscount(User user) { return true; }
    class User {
        boolean hasMembership() { return true; }
        int ordersCount() { return 1; }
    }
}

[推荐] 避免字段注入 (Field dependency injection should be avoided) (java:S6813)

• SonarQube 规则： java:S6813。

• 规则含义: 在 Spring 中，避免使用 @Autowired 直接注入字段。

• 目的与意义：Spring 最佳实践。字段注入使得对象在测试时难以实例化（必须启动 Spring 容器或使用反射），且掩盖了依赖关系。推荐使用 构造器注入，这样可以利用 final 关键字确保不可变性，并在编译期检查依赖缺失。

• 违规现状：MDC 项目存在 111 个此问题。

• 代码示例:

// 错误示例

@Service

public class UserService {

@Autowired

private UserRepository repo;

}

// 正确示例

@Service

public class UserService {

private final UserRepository repo;

public UserService(UserRepository repo) { // 构造器注入

this.repo = repo;

}

}

[推荐] 禁止使用 TODO 标签 (Track uses of "TODO" tags) (java:S1135)

• SonarQube 规则：java:S1135。

• 规则含义: 提示代码中遗留的 TODO 或 FIXME。

• 目的与意义：遗忘风险。mdc 中有 146 个 TODO。这通常意味着“永远不做的 TODO”。如果必须留，应配合 Issue 跟踪系统。

• 阿里规范对应：【参考】特殊注释标记，请注明标记人与标记时间。

[推荐] 避免未使用的僵尸变量和代码 (java:S1481, java:S1854, java:S1128, java:S108)

• SonarQube 规则 - mdc 项目违规次数：
• java:S1481 (Unused local variables should be removed) - 56 次。应移除未使用的局部变量。
• java:S1854 (Unused assignments should be removed) - 54 次。应移除未使用的赋值语句。
• java:S1128 (Unused imports should be removed) - 78 次。应移除未使用的导入语句。
• java:S108 (Nested blocks of code should not be left empty) - 63 次。嵌套代码块不应为空。

• 规则描述： 例如，S1854 检测的是“变量赋值后未被读取即被覆盖或销毁”的情况。

int x = calc(); // S1854: 这里的计算结果从未被使用
x = 10;return x;

虽然现代 JIT 编译器（如 HotSpot C2）可能会通过死代码消除（Dead Code Elimination）技术在运行时优化掉这些指令，但它浪费了 CPU 的指令缓存，且严重干扰代码阅读者对业务逻辑的理解。空代码块（S108）同样如此，它可能掩盖了缺失的逻辑（如空的 catch 块吞噬异常）。

• 修复方式：移除未使用的变量、赋值和代码块。

8. 面向未来的规约：JDK 21 与 Spring Boot 3 演进

8.1 拥抱现代化 Java (JDK 21)

[可选] 使用 Diamond 操作符 (The diamond operator "<>" should be used) (java:S2293)

• SonarQube 规则：java:S2293。

• 说明: JDK 1.7 引入的特性。mdc 尚有 48 处未使用。这是向高版本迁移的基础语法糖。

• 代码示例：

// 错误示例

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import org.springframework.http.ResponseEntity;
import org.springframework.http.HttpStatus;

public class S2293Noncompliant {

    public void exampleMethod() {
        // Explicit type declaration on the right-hand side is redundant
        List<String> strings = new ArrayList<String>(); // Noncompliant

        // Even with nested generics
        Map<String, List<Integer>> map = new HashMap<String, List<Integer>>(); // Noncompliant
        
        // In return statements
        // return new ResponseEntity<String>("No content", HttpStatus.OK); // Noncompliant
    }
}

// 正确示例
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import org.springframework.http.ResponseEntity;
import org.springframework.http.HttpStatus;

public class S2293Compliant {

    public void exampleMethod() {
        // Use the diamond operator to infer types
        List<String> strings = new ArrayList<>(); // Compliant

        // Types are inferred
        Map<String, List<Integer>> map = new HashMap<>(); // Compliant

        // In return statements, the type is inferred from the method's return type
        // return new ResponseEntity<>("No content", HttpStatus.OK); // Compliant
    }
}

[可选->推荐] 避免使用 Raw Types (Raw types should not be used) (java:S3740)

• SonarQube 规则：java:S3740。

• 说明: 使用了 List list 而非 List<String> list。在 JDK 21 中，泛型推断更加强大，使用 Raw Types 会导致大量编译警告，并可能在模块化（Jigsaw）下引发问题。

• 违规现状：mdc 有 47 处违规。

• 代码示例：

// 错误示例
import java.util.ArrayList;
import java.util.List;

public class RawTypesExample {

    // Noncompliant: Using List as a raw type
    public void processItems(List items) {
        for (Object item : items) {
            System.out.println(item);
        }
    }

    public static void main(String[] args) {
        List rawList = new ArrayList(); // Non-compliant
        rawList.add("Item 1");
        rawList.add(123); // Can add any type, leading to potential runtime errors

        RawTypesExample example = new RawTypesExample();
        example.processItems(rawList);
    }
}

// 正确示例
import java.util.ArrayList;
import java.util.List;

public class RawTypesExample {

    // Compliant: Using a wildcard for a list whose element type is unknown
    public void processItems(List<?> items) {
        for (Object item : items) {
            System.out.println(item);
        }
    }

    public static void main(String[] args) {
        // Compliant: Using a specific type argument
        List<String> typedList = new ArrayList<>();
        typedList.add("Item 1");
        // typedList.add(123); // This would now cause a compilation error

        RawTypesExample example = new RawTypesExample();
        example.processItems(typedList);
    }
}

[暂不使用->推荐] 使用 var 关键字 (Local-Variable Type Inference) (java:S6212)

• SonarQube 规则：java:S6212。

• 说明：Java 10 引入了局部变量类型推断。它允许你使用 var 关键字声明变量，从而省略变量的预期类型。在很多情况下，例如当赋值语句中变量左右两侧的类型相同时，使用 var 可以生成更简洁的代码。当变量的预期类型与赋值表达式的返回类型相同，且类型很容易被推断出来时（例如，类型已在变量名或初始化器中指定，或者表达式本身就具有自解释性），此规则会报告问题。

• 说明: 当前 JDK 1.8 不支持。但在升级到 JDK 21 后，应立即启用此规则，鼓励在新代码中使用 var 简化类型声明。

• 代码示例：

// 错误示例
import java.util.ArrayList;
import java.util.List;

public class S6212Noncompliant {

    public void exampleMethod() {
        // Type is obvious from the right-hand side
        MyClass myClass = new MyClass(); // Noncompliant

        // Type is obvious from the literal value
        int i = 10; // Noncompliant

        // Type is mentioned in the method name
        MyClass something = MyClass.getMyClass(); // Noncompliant

        // Type is in the variable name
        MyClass anotherMyClass = getMyClass(); // Noncompliant

        // The type is complex and using 'var' would make it clearer
        List<String> items = new ArrayList<>(); // Noncompliant
    }

    private MyClass getMyClass() {
        return new MyClass();
    }
}

class MyClass {
    public static MyClass getMyClass() {
        return new MyClass();
    }
}


public void processData() {
    // Explicit types improve readability
    MyService service = getService(); 
    ResultObject result = Service.calculate(); 
}

// 正确示例
import java.util.ArrayList;
import java.util.List;

public class S6212Compliant {

    public void exampleMethod() {
        // Using 'var'
        var myClass = new MyClass(); // Compliant

        // Using 'var'
        var i = 10; // Compliant

        // Using 'var'
        var something = MyClass.getMyClass(); // Compliant

        // Using 'var'
        var anotherMyClass = getMyClass(); // Compliant

        // Using 'var' makes complex generic types more concise
        var items = new ArrayList<String>(); // Compliant
    }

    private MyClass getMyClass() {
        return new MyClass();
    }
}

class MyClass {
    public static MyClass getMyClass() {
        return new MyClass();
    }
}

8.2 Spring Boot 3 迁移准备

[推荐] 避免使用已废弃的 API (Deprecated code should not be used) (java:S1874)

• SonarQube 规则：java:S1874。

• 特别关注: Spring Boot 3 将底层的 Java EE 标准从 javax.* 迁移到了 jakarta.*。

• 策略: 在阶段二中，必须严格审查所有使用了 javax.servlet.*, javax.persistence.* 等包的代码。SonarQube 会标记这些即将失效的 API 调用。

9. 分阶段实施路线图 (Implementation Roadmap)

第一阶段：净化期（第 1-2 个月）

• 目标： 解决所有 [必须] 级别的 Reliability 与 Security 问题。直接提高代码质量。

• Sonar Profile 配置： 创建 Company-Phase1 Profile，仅激活“必须”规则。

• Jenkins 动作： 设置 Quality Gate，当检测到新代码出现“必须”规则违规时，构建失败。对于存量代码，暂不阻断，但生成报告。

• 重点修复对象：
• java:S2095 (资源未关闭) - 14 个
• java:S2259 (空指针) - 20 个
• java:S2068 (硬编码密码) - 1 个
• xml:S3422 (System scope 依赖) - 3 个

第二阶段：规范期（第 3-6 个月）

• 目标： 偿还技术债务，提升代码可读性。

• Sonar Profile 配置： 升级为 Company-Phase2，加入“推荐”规则。

• Jenkins 动作： 对新代码应用所有“推荐”规则的检查。阻断“必须”违规，警告“推荐”违规。

• 重点治理：
• java:S3252 (静态成员访问) - 批量重构
• java:S1192 (字符串常量提取) - 逐步优化
• java:S106 (System.out 替换为 Logger)

第三阶段：现代化期（6 个月后）

• 目标： 引入单元测试覆盖率，准备 JDK 升级。

• 动作：
• 引入 JaCoCo 插件，设定最低单元测试覆盖率（如 30%）。
• 启用 java:S6813 (字段注入) 等现代化规则，重构遗留的 Spring 代码。
• 开始 JDK 21 升级试点。

10. 结论