Java 代码质量：SonarQube、Checkstyle 与 SpotBugs 工程化实践

# SonarQube 质量门禁示例
conditions:
  - metric: new_coverage
    operator: LT
    threshold: "80"
  - metric: new_duplicated_lines_density
    operator: GT
    threshold: "3"
  - metric: new_violations
    operator: GT
    threshold: "0"
    severity: BLOCKER
  - metric: new_security_hotspots_reviewed
    operator: LT
    threshold: "100"

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-checkstyle-plugin</artifactId>
            <version>3.3.1</version>
            <configuration>
                <configLocation>checkstyle.xml</configLocation>
                <encoding>UTF-8</encoding>
                <consoleOutput>true</consoleOutput>
                <failsOnError>true</failsOnError>
                <linkXRef>false</linkXRef>
            </configuration>
            <executions>
                <execution>
                    <id>validate</id>
                    <phase>validate</phase>
                    <goals><goal>check</goal></goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

<!-- checkstyle.xml -->
<!DOCTYPE module PUBLIC
    "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
    "https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
    <property name="charset" value="UTF-8"/>
    <property name="severity" value="error"/>
    
    <!-- 文件检查 -->
    <module name="NewlineAtEndOfFile"/>
    <module name="FileLength">
        <property name="max" value="500"/>
    </module>
    
    <module name="TreeWalker">
        <!-- 命名规范 -->
        <module name="PackageName">
            <property name="format" value="^[a-z]+(\.[a-z][a-z0-9]*)*$"/>
        </module>
        <module name="TypeName">
            <property name="format" value="^[A-Z][a-zA-Z0-9]*$"/>
        </module>
        <module name="MethodName">
            <property name="format" value="^[a-z][a-zA-Z0-9]*$"/>
        </module>
        <module name="ConstantName">
            <property name="format" value="^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$"/>
        </module>
        
        <!-- 代码格式 -->
        <module name="Indentation">
            <property name="basicOffset" value="4"/>
            <property name="braceAdjustment" value="0"/>
        </module>
        <module name="LineLength">
            <property name="max" value="120"/>
        </module>
        
        <!-- 导入检查 -->
        <module name="AvoidStarImport"/>
        <module name="UnusedImports"/>
        <module name="RedundantImport"/>
        
        <!-- Javadoc -->
        <module name="JavadocMethod">
            <property name="scope" value="public"/>
        </module>
        
        <!-- 代码结构 -->
        <module name="NeedBraces"/>
        <module name="LeftCurly"/>
        <module name="RightCurly"/>
        <module name="EmptyBlock"/>
        
        <!-- 复杂度 -->
        <module name="CyclomaticComplexity">
            <property name="max" value="10"/>
        </module>
        
        <!-- 编码实践 -->
        <module name="MagicNumber">
            <property name="ignoreNumbers" value="-1, 0, 1, 2"/>
        </module>
        <module name="EmptyStatement"/>
        <module name="EqualsHashCode"/>
        <module name="IllegalThrows"/>
    </module>
</module>

// 单行忽略
// checkstyle:off MagicNumber
if (status == 404) { }
// checkstyle:on MagicNumber

// 整个方法忽略
// @checkstyle:off
public void legacyMethod() { ... }
// @checkstyle:on

<plugin>
    <groupId>com.github.spotbugs</groupId>
    <artifactId>spotbugs-maven-plugin</artifactId>
    <version>4.8.3.1</version>
    <configuration>
        <effort>Max</effort>
        <threshold>Medium</threshold>
        <xmlOutput>true</xmlOutput>
        <excludeFilterFile>spotbugs-exclude.xml</excludeFilterFile>
    </configuration>
    <executions>
        <execution>
            <goals><goal>check</goal></goals>
        </execution>
    </executions>
</plugin>

public class BugPatterns {
    
    // ❌ NP_NULL_ON_SOME_PATH: 可能的空指针
    public String getName(User user) {
        return user.getProfile().getName();  // user/profile 可能为 null
    }
    
    // ✅ 修复
    public String getNameSafe(User user) {
        if (user == null || user.getProfile() == null) {
            return null;
        }
        return user.getProfile().getName();
    }
    
    // ❌ OS_OPEN_STREAM: 资源未关闭
    public String readFile(String path) throws IOException {
        FileInputStream fis = new FileInputStream(path);  // 未关闭！
        return new String(fis.readAllBytes());
    }
    
    // ✅ 修复
    public String readFileSafe(String path) throws IOException {
        try (FileInputStream fis = new FileInputStream(path)) {
            return new String(fis.readAllBytes());
        }
    }
    
    // ❌ EQ_COMPARING_CLASS_NAMES: 错误的 equals
    public boolean isSameType(Object a, Object b) {
        return a.getClass().getName().equals(b.getClass().getName());  // 应直接比较 Class 对象
    }
    
    // ✅ 修复
    public boolean isSameTypeSafe(Object a, Object b) {
        return a.getClass() == b.getClass();
    }
    
    // ❌ JLM_JSR166_UTILCONCURRENT_MONITORENTER: 错误地 synchronized ConcurrentHashMap
    public void badSync() {
        Map<String, String> map = new ConcurrentHashMap<>();
        synchronized (map) {  // ConcurrentHashMap 无需外部同步
            map.put("key", "value");
        }
    }
}

# docker-compose.yml
version: '3'
services:
  sonarqube:
    image: sonarqube:community
    ports:
      - "9000:9000"
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: sonar
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions
  
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: sonar
      POSTGRES_PASSWORD: sonar
      POSTGRES_DB: sonar
    volumes:
      - postgres_data:/var/lib/postgresql/data

<properties>
    <sonar.host.url>http://localhost:9000</sonar.host.url>
    <sonar.login>${SONAR_TOKEN}</sonar.login>
    <sonar.projectKey>myapp-backend</sonar.projectKey>
    <sonar.coverage.jacoco.xmlReportPaths>${project.build.directory}/jacoco-report/jacoco.xml</sonar.coverage.jacoco.xmlReportPaths>
</properties>

<plugin>
    <groupId>org.sonarsource.scanner.maven</groupId>
    <artifactId>sonar-maven-plugin</artifactId>
    <version>3.10.0.2594</version>
</plugin>

# 执行分析
mvn clean verify sonar:sonar

# 带覆盖率分析
mvn clean test jacoco:report sonar:sonar

# 分支分析
mvn sonar:sonar \
  -Dsonar.branch.name=feature/payment-gateway \
  -Dsonar.branch.target=main

# Pull Request 分析（GitHub/GitLab 集成）
mvn sonar:sonar \
  -Dsonar.pullrequest.key=42 \
  -Dsonar.pullrequest.branch=feature/login \
  -Dsonar.pullrequest.base=main

<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.11</version>
    <executions>
        <execution>
            <id>prepare-agent</id>
            <goals><goal>prepare-agent</goal></goals>
        </execution>
        <execution>
            <id>report</id>
            <phase>test</phase>
            <goals><goal>report</goal></goals>
        </execution>
        <execution>
            <id>check</id>
            <goals><goal>check</goal></goals>
            <configuration>
                <rules>
                    <rule>
                        <element>PACKAGE</element>
                        <limits>
                            <limit>
                                <counter>LINE</counter>
                                <value>COVEREDRATIO</value>
                                <minimum>0.80</minimum>
                            </limit>
                            <limit>
                                <counter>BRANCH</counter>
                                <value>COVEREDRATIO</value>
                                <minimum>0.70</minimum>
                            </limit>
                        </limits>
                    </rule>
                </rules>
            </configuration>
        </execution>
    </executions>
</plugin>

<configuration>
    <excludes>
        <exclude>**/config/**</exclude>
        <exclude>**/entity/**</exclude>
        <exclude>**/dto/**</exclude>
        <exclude>**/*Application.java</exclude>
    </excludes>
</configuration>

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'perf', 'security']],
    'scope-empty': [2, 'never'],
    'subject-full-stop': [2, 'never', '.'],
    'header-max-length': [2, 'always', 72]
  }
};

# .github/workflows/quality.yml
name: Code Quality

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # SonarQube 需要完整历史
      
      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
      
      - name: Cache Maven
        uses: actions/cache@v4
        with:
          path: ~/.m2
          key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
      
      - name: Run Tests with Coverage
        run: mvn clean test jacoco:report
      
      - name: Run Checkstyle
        run: mvn checkstyle:check
      
      - name: Run SpotBugs
        run: mvn spotbugs:check
      
      - name: SonarQube Analysis
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        run: mvn sonar:sonar -Dsonar.login=$SONAR_TOKEN
      
      - name: Upload Coverage
        uses: codecov/codecov-action@v4
        with:
          file: target/site/jacoco/jacoco.xml

# .gitlab-ci.yml
stages:
  - build
  - test
  - quality

variables:
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

cache:
  paths:
    - .m2/repository

build:
  stage: build
  script:
    - mvn compile -DskipTests

test:
  stage: test
  script:
    - mvn test jacoco:report
  artifacts:
    reports:
      junit: target/surefire-reports/TEST-*.xml
    paths:
      - target/site/jacoco/

code_quality:
  stage: quality
  script:
    - mvn checkstyle:checkstyle spotbugs:spotbugs
    - mvn sonar:sonar -Dsonar.qualitygate.wait=true
  allow_failure: false

## PR Review Checklist

### 功能正确性
- [ ] 业务逻辑正确，边界条件处理完善
- [ ] 异常处理完整，错误信息清晰
- [ ] 并发安全（共享变量、竞态条件）

### 代码质量
- [ ] 命名清晰有意义（类/方法/变量）
- [ ] 方法长度 < 50 行，圈复杂度 < 10
- [ ] 无重复代码（DRY 原则）
- [ ] 适当的注释（为什么而非做什么）

### 性能与安全
- [ ] 无 N+1 查询问题
- [ ] 敏感数据不打印到日志
- [ ] SQL 参数化，防注入
- [ ] 资源正确释放（try-with-resources）

### 测试
- [ ] 单元测试覆盖核心逻辑
- [ ] 边界条件和异常路径有测试
- [ ] 测试名称描述行为（given_when_then）

# SonarQube 技术债务指标解读
技术债务比率 = (修复所有 Code Smell 所需时间 / 总代码量) × 100%

健康阈值：
  绿色  < 5%   — 债务可控，新功能开发不受影响
  黄色  5-10%  — 需安排专项重构迭代
  红色  > 10%  — 严重阻碍，必须停止新功能投入偿还

修复优先级计算：
  优先级 = 严重性权重 × 重复出现次数 × 影响文件数
  例：Critical (权重10) × 出现50次 × 影响5文件 = 2500 分

# .pre-commit-config.yaml 示例
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
  - repo: local
    hooks:
      - id: checkstyle
        name: Checkstyle
        entry: mvn checkstyle:check
        language: system
        pass_filenames: false
        stages: [pre-commit]