Java 代码质量：SonarQube 静态扫描配置

2.2 SonarQube Server 安装与配置

1. 下载 SonarQube：访问 SonarQube 官网，选择'Community Edition'（社区版，免费开源，满足中小企业需求），下载后解压到本地路径（如 D:\sonarqube-10.6）；
2. 配置数据库连接：进入解压目录下的 conf 文件夹，编辑 sonar.properties 文件，添加以下配置（注释掉原有默认配置）：

# 数据库类型
sonar.jdbc.driverClassName=org.postgresql.Driver

# 数据库连接 URL（localhost:5432 为默认端口，sonarqube 为数据库名）
sonar.jdbc.url=jdbc:postgresql://localhost:5432/sonarqube

# 数据库用户名
sonar.jdbc.username=postgres

# 数据库密码（替换为你的实际密码）
sonar.jdbc.password=123456

# 初始化数据库（首次启动时执行，启动成功后可注释）
sonar.jdbc.maxActive=60
sonar.jdbc.maxIdle=5
sonar.jdbc.minIdle=2

3. 启动 SonarQube 服务：进入解压目录下的 bin\\windows-x86-64 文件夹，双击 StartSonar.bat 启动服务；
4. 验证服务启动：打开浏览器访问 http://localhost:9000，默认用户名/密码：admin/admin，首次登录需修改密码（如改为 Admin@123），能正常进入 Web 界面即启动成功。

2.3 SonarScanner 安装与配置

SonarScanner 是执行代码扫描的客户端工具，我们选择与 Maven 集成（Java 项目最常用方式），步骤如下：

1. 下载 SonarScanner：访问 SonarScanner 官网，下载后解压到本地路径（如 D:\sonar-scanner-5.0.1.3006）；
2. 配置环境变量： 新建系统变量 SONAR_SCANNER_HOME，值为解压路径（D:\sonar-scanner-5.0.1.3006）；
3. 编辑系统变量 Path，添加 %SONAR_SCANNER_HOME%\\bin；
4. 验证安装：打开命令提示符（CMD），输入 sonar-scanner -v，输出版本信息即正常；
5. 配置 Maven 集成：编辑 Maven 安装目录下的 conf\\settings.xml 文件，在 <profiles> 标签内添加 SonarQube 配置（后续可通过 Maven 命令直接执行扫描）：

<profile>
  <id>sonar</id>
  <activation>
    <activeByDefault>true</activeByDefault>
  </activation>
  <properties>
    <sonar.host.url>http://localhost:9000</sonar.host.url>
    <sonar.login></sonar.login>
  </properties>
</profile>

三、核心配置（项目级扫描配置）

环境搭建完成后，需在 Java 项目中配置扫描规则、范围等信息，本节以一个 Spring Boot 项目为例，讲解完整配置流程。

3.1 生成 SonarQube 用户令牌

为了让客户端（SonarScanner）能正常上报数据到服务端，需创建用户令牌（替代用户名密码，更安全）：

1. 登录 SonarQube Web 界面（http://localhost:9000）；
2. 点击右上角头像 → My Account → Security；
3. 输入令牌名称（如 java-project-token），选择过期时间（如 No expiration），点击 Generate；
4. 复制生成的令牌（如 sqp_1234567890abcdef），妥善保存（仅显示一次）；
5. 更新 Maven 配置：将复制的令牌填入 settings.xml 中的 <sonar.login> 标签内（如 <sonar.login>sqp_1234567890abcdef</sonar.login>）。

3.2 项目内创建 SonarQube 配置文件

在 Spring Boot 项目的根目录下，创建 sonar-project.properties 文件（核心配置文件，定义扫描规则、范围等），完整配置如下（含注释说明）：

# 项目唯一标识（SonarQube 中不可重复，建议用 groupId:artifactId）
sonar.projectKey=com.example:java-sonar-demo
# 项目名称（SonarQube 界面显示）
sonar.projectName=Java SonarQube Demo
# 项目版本
sonar.projectVersion=1.0.0
# 源代码编码格式
sonar.sourceEncoding=UTF-8
# 源代码目录（相对路径）
sonar.sources=src/main/java
# 测试代码目录（相对路径）
sonar.tests=src/test/java
# 测试代码编译后目录（Maven 默认路径）
sonar.test.inclusions=**/*Test.java
# 排除扫描的目录（如生成的代码、配置类等，可根据需求调整）
sonar.exclusions=src/main/java/com/example/demo/generated/**/*,src/main/java/com/example/demo/config/**/*
# Java 编译器版本（与项目一致，如 17）
sonar.java.source=17
sonar.java.target=17
# 代码覆盖率报告路径（后续集成 JaCoCo 生成，暂配置）
sonar.jacoco.reportPaths=target/jacoco.exec
# 禁用某些规则（示例：禁用'方法名必须以动词开头'的规则，规则 ID 可在 SonarQube 界面查询）
sonar.issue.ignore.multicriteria=e1
sonar.issue.ignore.multicriteria.e1.ruleKey=squid:S00100
sonar.issue.ignore.multicriteria.e1.resourceKey=**/*.java

四、示例代码演示与扫描验证

为了直观感受 SonarQube 的扫描效果，我们编写一段包含'代码异味、潜在 Bug、安全漏洞'的 Java 代码，执行扫描后查看问题并修复。

4.1 编写有问题的示例代码

在 Spring Boot 项目中创建 com.example.demo.service.UserService 类，代码如下（含多处故意留下的问题）：

package com.example.demo.service;

import com.example.demo.entity.User;
import com.example.demo.mapper.UserMapper;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import java.util.List;

@Service
public class UserService {
    @Autowired
    private UserMapper userMapper;

    // 问题 1：方法名以名词开头（违反 SonarQube 命名规范，代码异味）
    public List<User> userList() {
        // 问题 2：未使用的局部变量（代码异味）
        String temp = "unused";
        return userMapper.selectAll();
    }

    // 问题 3：方法过长（代码异味，建议拆分）
    public User getUserById(Integer id) {
        if (id == null) {
            // 问题 4：空指针异常风险（潜在 Bug，未处理 null 情况）
            return null;
        }
        User user = userMapper.selectById(id);
        // 问题 5：硬编码敏感信息（安全漏洞，数据库密码直接写入代码）
        String dbPassword = "root123456";
        if (user != null) {
            // 问题 6：重复代码（与下方逻辑重复）
            System.out.println("用户存在：" + user.getName());
            if (user.getAge() > 18) {
                user.setAdult(true);
            } else {
                user.setAdult(false);
            }
        } else {
            System.out.println("用户不存在：" + id);
            // 问题 6：重复代码（与上方输出逻辑重复）
            User emptyUser = new User();
            if (emptyUser.getAge() > 18) {
                emptyUser.setAdult(true);
            } else {
                emptyUser.setAdult(false);
            }
            return emptyUser;
        }
        return user;
    }

    // 问题 7：未使用的私有方法（代码异味）
    private void unusedMethod() {
        System.out.println("该方法未被调用");
    }
}

4.2 执行代码扫描

打开命令提示符（CMD），进入项目根目录，执行以下 Maven 命令（集成 SonarScanner 后无需额外配置路径）：

mvn clean verify sonar:sonar

命令说明：

• clean：清理项目编译生成的文件；
• verify：编译项目并执行测试；
• sonar:sonar：执行 SonarQube 扫描并上报结果到服务端。

等待命令执行完成，输出'BUILD SUCCESS'即扫描成功。

4.3 查看扫描结果与问题分析

打开 SonarQube Web 界面（http://localhost:9000），在项目列表中找到'Java SonarQube Demo'项目，进入后可查看详细扫描结果：

4.3.1 概览信息

界面会显示项目的核心质量指标：

• 代码覆盖率：若未配置 JaCoCo，覆盖率可能为 0（后续拓展部分讲解）；
• 问题总数：包含 Bug、漏洞、代码异味的数量；
• 重复率：示例中存在重复代码，重复率会显示异常；
• 复杂度：过长方法会导致复杂度升高。

4.3.2 详细问题列表

点击左侧'Issues'菜单，可查看所有扫描出的问题，按严重程度分类：

1. 安全漏洞（Critical）：硬编码敏感信息（dbPassword = 'root123456'），SonarQube 会标记为高风险，提示'敏感信息不应硬编码到代码中'；
2. 潜在 Bug（Major）：空指针异常风险（id 为 null 时返回 null，调用方可能未处理）；
3. 代码异味（Minor）：方法名命名不规范、未使用变量、未使用方法、重复代码、方法过长等。

点击每个问题，可查看具体位置、问题描述和修复建议，例如点击'硬编码敏感信息'问题，会提示'将敏感信息移至配置文件（如 application.yml），通过@Value 注解注入'。

4.4 问题修复与重新扫描

根据 SonarQube 的修复建议，修改 UserService 类代码，修复所有问题：

package com.example.demo.service;

import com.example.demo.entity.User;
import com.example.demo.mapper.UserMapper;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
import java.util.List;

@Service
public class UserService {
    @Autowired
    private UserMapper userMapper;

    // 修复：从配置文件注入数据库密码（解决硬编码漏洞）
    @Value("${spring.datasource.password}")
    private String dbPassword;

    // 修复：方法名改为动词开头（符合命名规范）
    public List<User> listUsers() {
        // 修复：删除未使用的局部变量
        return userMapper.selectAll();
    }

    // 修复：拆分过长方法，提取公共逻辑（降低复杂度）
    public User getUserById(Integer id) {
        // 修复：处理 id 为 null 的情况（避免空指针风险）
        if (id == null) {
            throw new IllegalArgumentException("用户 ID 不能为空");
        }
        User user = userMapper.selectById(id);
        if (user != null) {
            System.out.println("用户存在：" + user.getName());
        } else {
            System.out.println("用户不存在：" + id);
            user = new User();
        }
        // 修复：提取公共逻辑到私有方法（解决重复代码）
        setAdultStatus(user);
        return user;
    }

    // 修复：有用的私有方法（替代原未使用的方法）
    private void setAdultStatus(User user) {
        user.setAdult(user.getAge() > 18);
    }
}

修复完成后，重新执行扫描命令 mvn clean verify sonar:sonar，再次查看 SonarQube 界面，会发现所有问题已消失，项目质量指标显著提升。

五、进阶拓展（提升扫描实用性）

基础配置完成后，我们可以通过以下拓展配置，进一步提升 SonarQube 的实用性，适配企业级开发需求。

5.1 集成 JaCoCo 实现代码覆盖率统计

代码覆盖率是衡量测试质量的重要指标，SonarQube 可集成 JaCoCo（Java 代码覆盖率工具），自动统计测试覆盖率。配置步骤如下：

1. 在项目的 pom.xml 文件中，添加 JaCoCo 插件依赖：

<plugins>
    <plugin>
        <groupId>org.jacoco</groupId>
        <artifactId>jacoco-maven-plugin</artifactId>
        <version>0.8.11</version>
    </plugin>
</plugins>

2. 编写测试代码：在 src/test/java/com/example/demo/service 目录下创建 UserServiceTest 类，编写单元测试：

package com.example.demo.service;

import com.example.demo.entity.User;
import com.example.demo.mapper.UserMapper;
import org.junit.jupiter.api.Test;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.springframework.boot.test.context.SpringBootTest;
import java.util.Arrays;
import java.util.List;
import static org.junit.jupiter.api.Assertions.*;
import static org.mockito.Mockito.when;

@SpringBootTest
public class UserServiceTest {

    @Mock
    private UserMapper userMapper;

    @InjectMocks
    private UserService userService;

    @Test
    public void testListUsers() {
        User user = new User();
        user.setId(1);
        user.setName("张三");
        when(userMapper.selectAll()).thenReturn(Arrays.asList(user));
        List<User> userList = userService.listUsers();
        assertNotNull(userList);
        assertEquals(1, userList.size());
    }

    @Test
    public void testGetUserById() {
        // 测试 id 不为 null 的情况
        User user = new User();
        user.setId(1);
        user.setName("张三");
        user.setAge(20);
        when(userMapper.selectById(1)).thenReturn(user);
        User result = userService.getUserById(1);
        assertNotNull(result);
        assertTrue(result.isAdult());

        // 测试 id 为 null 的情况
        assertThrows(IllegalArgumentException.class, () -> userService.getUserById(null));
    }
}

3. 重新执行扫描命令：mvn clean verify sonar:sonar，此时 SonarQube 界面会显示代码覆盖率（示例中可达 80% 以上）。

5.2 自定义扫描规则

SonarQube 默认提供了大量扫描规则，但不同团队可能有个性化需求（如允许某些命名规范、禁用某些严格规则），可通过以下步骤自定义规则：

1. 登录 SonarQube Web 界面，点击左侧'Quality Profiles'菜单；
2. 在搜索框中输入'java'，找到默认的 Java 质量配置文件，点击'Copy'创建副本（避免修改默认配置）；
3. 给副本命名（如'Java 自定义规则'），点击'Create'；
4. 进入自定义规则配置页面，可通过'Activate'（激活规则）、'Deactivate'（禁用规则）调整规则集（如禁用'方法参数数量不超过 7 个'的规则）；
5. 将自定义规则集设置为默认：点击规则集名称右侧的'Set as Default'；
6. 项目级关联：若需指定项目使用特定规则集，进入项目 → 项目设置 → Quality Profile → 选择自定义规则集 → 点击'Associate'。

5.3 集成 CI/CD 流水线（Jenkins 示例）

在企业级开发中，通常需要将 SonarQube 扫描集成到 CI/CD 流水线（如 Jenkins），实现代码提交/合并时自动扫描，不满足质量标准则阻断流水线。以 Jenkins 为例，配置步骤如下：

1. 安装 Jenkins 插件：登录 Jenkins → 系统管理 → 插件管理 → 搜索'SonarQube Scanner' → 安装并重启 Jenkins；
2. 配置 SonarQube 服务器：Jenkins → 系统管理 → 系统 → 找到'SonarQube servers' → 点击'Add SonarQube'，输入名称（如 SonarQube-Local），服务器 URL（http://localhost:9000），添加凭据（选择'Secret text'，输入之前创建的用户令牌），点击'Save'；
3. 创建 Jenkins 任务：新建自由风格项目 → 配置源码管理（关联 Git 仓库，输入项目地址和凭据）；
4. 添加构建步骤：选择'Invoke top-level Maven targets'，在'Goals'中输入'clean verify sonar:sonar'；
5. 添加构建后操作：选择'SonarQube Quality Gates'（需安装对应插件），实现'不满足质量标准则构建失败'（如漏洞数量>0 时阻断流水线）；
6. 保存配置后，点击'Build Now'执行流水线，Jenkins 会自动拉取代码、编译、执行 SonarQube 扫描，扫描结果不满足质量标准则构建失败。

六、常见问题排查

在配置和使用过程中，可能会遇到一些问题，以下是常见问题及解决方案：

1. 扫描失败，提示'Failed to connect to SonarQube server'： 检查 SonarQube 服务是否正常启动（访问 http://localhost:9000 验证）； 检查 settings.xml 或 sonar-project.properties 中的 sonar.host.url 是否正确； 检查网络是否通畅，是否有防火墙拦截 9000 端口。
2. 扫描成功但未显示代码覆盖率： 检查是否添加了 JaCoCo 插件依赖； 检查 sonar-project.properties 中 sonar.jacoco.reportPaths 路径是否正确（需与 JaCoCo 生成的 exec 文件路径一致）； 确认执行了 verify 阶段（生成覆盖率报告的关键）。
3. 扫描结果中存在误报问题： 若确认是误报，可在 SonarQube 界面点击问题 → 选择'Mark as False Positive'（标记为误报）； 若多个项目存在相同误报，可考虑禁用该规则（通过自定义质量配置文件）。

七、总结

本文从环境搭建、核心配置、示例演示、问题修复到进阶拓展，完整讲解了 SonarQube 在 Java 项目中的静态扫描配置流程。通过 SonarQube，我们能提前发现代码中的 Bug、漏洞和异味，量化代码质量指标，结合 JaCoCo 和 CI/CD 集成，可实现代码质量的全流程自动化管控。

需要注意的是，SonarQube 只是代码质量管控的工具，核心还是团队要建立统一的代码规范和质量意识。建议在项目初期就配置好 SonarQube 扫描，定期复盘质量指标，持续优化代码质量。后续可进一步探索 SonarQube 的高级功能（如多语言扫描、自定义报告生成、第三方工具集成等），提升团队开发效率和项目质量。