SonarQube 基础概念与扫描流程

背景与动机#

SonarQube 不是简单的“代码格式检查工具”，它更像是代码质量平台。它把静态代码分析、规则集、质量门禁和趋势报告放到一起，让代码质量能进入 CI/CD 流水线。

如果只把 SonarQube 理解成“扫一下代码”，很容易漏掉重点。真正重要的是：扫描结果能不能被团队理解，能不能变成合并或发布前的质量门禁。

核心原理拆解#

1. SonarQube Server：保存项目、规则和分析结果#

SonarQube Server 是 Web 服务端，负责：

管理项目和权限。
保存扫描结果和历史趋势。
管理 Quality Gate 和 Quality Profile。
展示 Bugs、Vulnerabilities、Code Smells、Coverage、Duplications 等指标。

开发者平时看到的页面、项目报告、问题列表和质量门禁结果，都是由 Server 侧提供。

2. SonarScanner：真正执行代码分析的入口#

SonarScanner 是运行在本地或 CI/CD 主机上的扫描程序。它负责读取项目源码和扫描配置，然后把分析报告发送给 SonarQube Server。

常见 Scanner 有几类：

SonarScanner CLI：通用命令行扫描器。
SonarScanner for Maven：适合 Maven 项目。
SonarScanner for Gradle：适合 Gradle 项目。
SonarScanner for .NET：适合 .NET 项目。
SonarScanner for NPM、Python 等：适合对应生态。

如果项目没有合适的构建工具集成，通常从 SonarScanner CLI 开始。

3. Quality Profile：决定“用哪些规则扫”#

Quality Profile 是规则集合。它决定某种语言扫描时启用哪些规则。

例如 Java 项目会使用 Java 对应的 Quality Profile，JavaScript 项目会使用 JavaScript 对应的 Quality Profile。一个多语言项目可能同时使用多套 Profile。

可以简单理解成：

1
Quality Profile = 扫描规则集

4. Quality Gate：决定“扫完能不能过”#

Quality Gate 是质量门禁。它不决定扫描哪些规则，而是判断扫描结果是否达标。

常见门禁条件包括：

新代码覆盖率是否达标。
新代码重复率是否过高。
是否存在新的严重问题。
安全热点是否需要评审。

可以简单理解成：

1
Quality Gate = 发布或合并前的质量判定

5. 一次扫描从代码到报告的流程#

一次典型扫描流程如下：

1
开发者提交代码
2
        ↓
3
CI/CD 拉取代码
4
        ↓
5
执行构建和测试
6
        ↓
7
运行 SonarScanner
8
        ↓
9
Scanner 分析源码并生成报告
10
        ↓
11
报告发送到 SonarQube Server
12
        ↓
13
Server 计算指标和 Quality Gate
14
        ↓
15
CI/CD 根据门禁结果继续或停止

SonarQube 官方文档中也强调：Scanner 在 CI/CD 主机上执行分析，并把结果发送给 SonarQube Server；Server 再计算 Quality Gate 并生成报告。

最小实践示例#

一个最小的 CLI 扫描通常需要三类信息：

1
sonar.projectKey=my-app
2
sonar.sources=src
3
sonar.host.url=http://sonarqube.example.com:9000

运行扫描时还需要认证 token：

1
export SONAR_TOKEN="your-project-token"
2
sonar-scanner

这里的重点不是命令本身，而是职责分工：

sonar.projectKey：告诉 Server 这是哪个项目。
sonar.sources：告诉 Scanner 扫哪些源码。
sonar.host.url：告诉 Scanner 把结果发到哪个 SonarQube Server。
SONAR_TOKEN：让 Scanner 有权限提交分析结果。

常见陷阱#

1. 把 Scanner 当成 Server#

Scanner 只是执行扫描并提交报告，它本身不保存项目历史，也不提供 Web 报告页面。

2. 以为扫描通过等于代码完全安全#

SonarQube 能发现很多质量和安全问题，但它不是完整安全体系的替代品。依赖漏洞、运行时风险、架构风险仍然需要其他工具和流程配合。

3. 只看整体代码，不看新代码#

老项目历史问题可能很多。更现实的做法通常是先守住“新代码质量”，让新增和修改部分不继续引入问题。

4. Quality Profile 和 Quality Gate 混在一起#

Profile 负责“扫什么规则”，Gate 负责“结果是否达标”。一个是规则集合，一个是判定标准。

一句话总结#

SonarQube 的核心链路是：Scanner 在 CI/CD 主机扫描代码，Server 保存和计算结果，Quality Profile 决定扫描规则，Quality Gate 决定流水线能不能继续。

音乐