# SonarQube 质量门禁配置指南

## 一、概述

本文档描述风七六本地生活服务平台的 SonarQube 质量门禁配置，用于确保代码质量符合大厂标准。

## 二、质量门禁阈值设置

### 2.1 推荐阈值（SonarQube 服务器端配置）

| 指标                                | 阈值    | 说明             |
|-----------------------------------|-------|----------------|
| **代码覆盖率 (Coverage)**              | ≥ 80% | 核心业务代码的单元测试覆盖率 |
| **重复代码率 (Duplications)**          | ≤ 5%  | 代码重复比例         |
| **代码异味 (Code Smells)**            | ≤ 100 | 代码质量问题数量       |
| **安全漏洞 (Vulnerabilities)**        | 0     | 安全漏洞必须为零       |
| **Bugs**                          | 0     | 代码缺陷必须为零       |
| **技术债务比率 (Technical Debt Ratio)** | ≤ 5%  | 技术债务占比         |

### 2.2 SonarQube 服务器端配置步骤

1. **登录 SonarQube**：访问 `http://8.140.221.49:9000`
2. **创建 Quality Gate**：
  - 进入 **Quality Gates** → **Create**
  - 命名：`FZX-Quality-Gate`
  - 添加以下条件：
    - `Coverage` → `is less than` → `80` → `Error`
    - `Duplications (%)` → `is greater than` → `5` → `Error`
    - `Code Smells` → `is greater than` → `100` → `Warning`
    - `Vulnerabilities` → `is greater than` → `0` → `Error`
    - `Bugs` → `is greater than` → `0` → `Error`
3. **关联项目**：将 Quality Gate 应用到 `fzx-platform-dev` 项目

## 三、项目配置文件

### 3.1 Maven Pom.xml 配置

```xml
<plugin>
    <groupId>org.sonarsource.scanner.maven</groupId>
    <artifactId>sonar-maven-plugin</artifactId>
    <version>4.0.0.4121</version>
    <configuration>
        <sonar.java.coveragePlugin>jacoco</sonar.java.coveragePlugin>
        <sonar.jacoco.reportPaths>**/target/jacoco.exec</sonar.jacoco.reportPaths>
        <sonar.sourceEncoding>UTF-8</sonar.sourceEncoding>
        <sonar.java.disableExternalRulesDownload>true</sonar.java.disableExternalRulesDownload>
        <sonar.qualitygate.wait>true</sonar.qualitygate.wait>
    </configuration>
</plugin>
```

### 3.2 JaCoCo 配置

```xml
<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.11</version>
    <executions>
        <execution>
            <id>jacoco-initialize</id>
            <goals>
                <goal>prepare-agent</goal>
            </goals>
            <configuration>
                <destFile>${project.build.directory}/jacoco.exec</destFile>
            </configuration>
        </execution>
        <execution>
            <id>jacoco-report</id>
            <phase>test</phase>
            <goals>
                <goal>report</goal>
            </goals>
        </execution>
    </executions>
</plugin>
```

### 3.3 sonar-project.properties（可选）

```properties
sonar.projectKey=fzx-platform
sonar.projectName=风七六本地生活服务平台
sonar.projectVersion=1.1.0
sonar.sources=services/*/src/main/java
sonar.tests=services/*/src/test/java
sonar.java.source=21
sonar.java.target=21
sonar.java.coveragePlugin=jacoco
sonar.jacoco.reportPaths=**/target/jacoco.exec
sonar.sourceEncoding=UTF-8
sonar.exclusions=**/entity/**,**/dto/**,**/mapper/**
```

## 四、Jenkins 集成配置

### 4.1 SonarQube 服务器配置

在 Jenkins 全局配置中添加 SonarQube 服务器：

| 配置项                             | 值                          |
|---------------------------------|----------------------------|
| **Name**                        | `Fzx-Sonar`                |
| **Server URL**                  | `http://8.140.221.49:9000` |
| **Server authentication token** | 在 SonarQube 生成的 token      |

### 4.2 Jenkins Pipeline 配置

```groovy
stage('SonarQube质量门禁') {
    when { expression { params.ENABLE_SONAR } }
    steps {
        timeout(time: 30, unit: 'MINUTES') {
            withSonarQubeEnv('Fzx-Sonar') {
                mvnExecute("sonar:sonar \
                    -Dsonar.projectKey=${params.SONAR_PROJECT_KEY} \
                    -Dsonar.host.url=${SONAR_HOST} \
                    -Dsonar.projectName=风七六本地生活服务平台 \
                    -Dsonar.projectVersion=${env.CURRENT_VERSION} \
                    -Dsonar.java.coveragePlugin=jacoco \
                    -Dsonar.jacoco.reportPaths=**/target/jacoco.exec \
                    -Dsonar.qualitygate.wait=true")
                waitForQualityGate abortPipeline: true
            }
        }
    }
}
```

## 五、质量门禁执行流程

```
┌─────────────────────────────────────────────────────────────┐
│                   Jenkins 构建流程                          │
├─────────────────────────────────────────────────────────────┤
│  1. 代码检出                                               │
│      ↓                                                     │
│  2. 依赖安装 (mvn install)                                  │
│      ↓                                                     │
│  3. 代码质量检查 (PMD/Checkstyle)                           │
│      ↓                                                     │
│  4. 依赖漏洞扫描 (Dependency-Check)                         │
│      ↓                                                     │
│  5. 编译构建                                               │
│      ↓                                                     │
│  6. 单元测试 (生成 JaCoCo 覆盖率报告)                        │
│      ↓                                                     │
│  7. SonarQube 质量门禁                                      │
│      │                                                     │
│      ├─→ 上传代码到 SonarQube                              │
│      ├─→ 执行静态代码分析                                   │
│      ├─→ 计算代码覆盖率                                     │
│      ├─→ 评估 Quality Gate 条件                             │
│      │                                                     │
│      ├─→ 通过 ──→ 继续后续步骤                              │
│      │                                                     │
│      └─→ 失败 ──→ 终止构建，发送通知                         │
│      ↓                                                     │
│  8. 打包发布                                               │
└─────────────────────────────────────────────────────────────┘
```

## 六、质量门禁失败处理流程

### 6.1 失败通知

当质量门禁失败时，系统会自动：

1. 终止流水线执行
2. 输出失败原因到构建日志
3. 发送钉钉通知（如果配置了 Webhook）
4. 提供 SonarQube Dashboard 链接

### 6.2 问题修复步骤

1. **查看报告**：访问 SonarQube Dashboard 查看详细报告
2. **定位问题**：根据报告中的问题列表定位具体问题
3. **修复代码**：
  - **Coverage < 80%**: 增加单元测试覆盖
  - **Duplications > 5%**: 抽取公共代码，消除重复
  - **Code Smells > 100**: 修复代码异味（命名、复杂度等）
  - **Vulnerabilities > 0**: 修复安全漏洞
  - **Bugs > 0**: 修复代码缺陷
4. **重新提交**：修复后重新提交代码触发构建

## 七、常见问题与解决方案

### 7.1 覆盖率为 0%

**原因**：JaCoCo 代理未正确配置或覆盖率报告路径不正确

**解决方案**：

```xml
<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>jacoco-initialize</id>
            <goals>
                <goal>prepare-agent</goal>
            </goals>
            <configuration>
                <destFile>${project.build.directory}/jacoco.exec</destFile>
            </configuration>
        </execution>
    </executions>
</plugin>
```

### 7.2 SonarQube 连接失败

**原因**：网络不通或服务器配置错误

**解决方案**：

1. 检查 SonarQube 服务器状态
2. 验证 Jenkins 中 SonarQube 服务器配置
3. 确保 token 有效且具有项目访问权限

### 7.3 质量门禁超时

**原因**：代码量较大，分析时间超过 30 分钟

**解决方案**：

```groovy
timeout(time: 60, unit: 'MINUTES') {
    withSonarQubeEnv('Fzx-Sonar') {
        // SonarQube 分析
    }
}
```

## 八、配置验证

运行以下命令验证配置是否正确：

```bash
# 运行单元测试并生成覆盖率报告
mvn test

# 执行 SonarQube 分析（需要 Jenkins 环境变量）
mvn sonar:sonar \
    -Dsonar.projectKey=fzx-platform-dev \
    -Dsonar.host.url=http://8.140.221.49:9000 \
    -Dsonar.login=<your-token>
```

## 九、参考文档

1. [SonarQube Documentation](https://docs.sonarqube.org/latest/)
2. [JaCoCo Documentation](https://www.jacoco.org/jacoco/trunk/doc/)
3. [Jenkins SonarQube Plugin](https://plugins.jenkins.io/sonarqube/)

---

**文档版本**: v1.0
**创建日期**: 2026-06-08
**适用项目**: 风七六本地生活服务平台