写在前面

你的团队大概率有 code review，也有单元测试。但 review 是稀缺资源：当一份 PR 里混着空捕获的异常、没释放的流、复制粘贴的三段重复代码时，人的注意力会先被机械性问题耗光，真正值得讨论的设计问题反而没人看。测试则只覆盖你想到要测的路径——静态分析能覆盖你没意识到的风险模式。

SonarQube 就是把“机械性检查”从人身上卸下来交给机器的那类工具：它在接入分析的构建中扫描代码，报出 Bug、代码坏味道与安全漏洞，度量测试覆盖率与重复率，并用质量门禁（Quality Gate）在流水线上把守合并入口。它不替代 review 和测试，而是把这两者从低价值的检查劳动里解放出来。

写这篇文章的另一个动机：SonarQube 这两年变化很大，中文资料普遍停留在旧世界。2024 年 10 月起官方完成了一次整体更名——SonarQube 变成 SonarQube Server、社区版变成 SonarQube Community Build、SonarCloud 变成 SonarQube Cloud、SonarLint 变成 SonarQube for IDE；版本号也从 10.x 换成了年份制（当前 LTA 是 2026.5）；2026 年更是弃用了 Security Hotspot、把内置质量配置文件拆成了三档。网上大量的“SonarQube 教程”讲的其实是一个已经不存在的版本。

本文以 C#/.NET 项目为主线，从接入、到原理、到治理，最后到大多数人不知道的一层——把 SonarQube 的内置 Web API 当数据源来编程调用。面向会使用 dotnet CLI 的 .NET 开发者，不要求预先了解静态分析。

版本口径：本文事实核对自 2026 年 10 月的官方文档（SonarQube Server 2026.5 LTA、Community Build 26.8、SonarScanner for .NET 11.x、SonarAnalyzer.CSharp 10.x）。文中命令与 API 参数均逐条核对官方文档及官方在线实例，但未在本地搭建完整服务器逐条复跑；产品迭代较快，落地时以你所用版本的官方文档为最终依据。

一、SonarQube 全景：产品形态与质量模型

1.1 三种交付形态：Server、Community Build、Cloud

先厘清名字。2024 年 10 月的官方更名后，这个产品家族是这样的：

几点容易踩的认知坑：

• Community Build 不是 SonarQube Server 的一个“版本”，它是一条独立演进的免费产品线：版本号自成体系（YY.M 格式，如 26.8），源码在同一个 GitHub 仓库里持续交付。商业 Server 的版本号则是 年份.发布号.补丁号（如 2026.5），每两个月一发、每年两个 LTA（Long-Term Active，即原来的 LTS）。
• 分支与 PR 分析是免费版和付费版最刚性的分界线。官方功能对比表里 Community Build 一栏写的是 “Only main branch analysis”，PR 分析直接缺位。这意味着“在 PR 上自动标注问题、门禁红了阻止合并”这套体验，免费自托管是拿不到的（应对思路见第六节）。
• 做 C# 分析必须用 SonarScanner for .NET（详见第二节），通用的 SonarScanner CLI 官方明确不支持 C#/VB.NET。

1.2 它到底产出什么：质量模型

SonarQube 的基本工作单元是规则（Rule）——C# 侧由 SonarAnalyzer 提供数百条 Roslyn 分析器规则，每条规则有唯一编号（S 加数字，如 S2094“类不应为空”）。规则命中代码后在服务器上落成问题（Issue）。具体数量会随分析器版本变化，应以对应版本的规则目录为准。

问题怎么分类，取决于实例运行在哪种模式下——这是当前 SonarQube 最容易讲错的地方：

两套严重级别存在官方映射（MINOR↔LOW、MAJOR↔MEDIUM、CRITICAL↔HIGH），Web API 里两套参数族也并存（types/severities 与 impactSoftwareQualities/impactSeverities），所以读旧文档、写新脚本时都不用慌——它们在说同一件事。

三个容易混淆的边界：

• 覆盖率和重复率不是“质量”，而是独立于质量模型的度量指标（measures）。它们不进质量评级，但可以作为质量门禁的条件。
• Security Hotspot 已在 2026.4 起弃用。它是第四类发现——安全敏感代码，需要人工评审后判定是否真的有问题。弃用后，原 Hotspot 规则改为直接报 Vulnerability（或 MQR 下的 security issue），存量 Hotspot 可通过服务器内置的迁移接口转换。中文资料里大篇幅讲 Hotspot 评审流程的内容，对新实例已经过时。
• 技术债以时间为单位：每条 Code Smell 类 issue 带一个“修复成本”（分钟数，继承自规则定义），全项目求和就是技术债总量（指标键沿用 SQALE 时代的历史名称 sqale_index），展示为“天”时按 8 小时/天换算。

1.3 Clean as You Code：只对新代码设防

SonarQube 的核心哲学是只对“新代码”设门禁，不追究存量。所谓新代码（new code），指相对某个基线新增或变更的部分，基线可选四种策略之一：上一版本（默认）、最近 N 天（默认 30 天）、参考分支、某次指定分析。这样门禁问的问题不再是“你的项目有几万个问题”（几乎必然有，问了个死问题），而是“这次提交有没有让事情变得更糟”——一个可以诚实回答、也必须在每次合并前回答的问题。为什么这样设计有效，第七节再展开。

1.4 和 .NET 工具链的分工

C# 开发者容易困惑：我已经有 Roslyn 分析器、.editorconfig、dotnet format 了，还要 SonarQube 干什么？分工其实是这样的：

• SonarAnalyzer.CSharp 本身就是一个 Roslyn 分析器包，可以脱离服务器直接引入项目获得 IDE 内告警。SonarQube 的增量在服务器侧：跨时间的趋势、New Code 判定、质量门禁、规则治理、团队协同处理 issue——这些是纯 IDE 分析给不了的。
• dotnet format 与 .editorconfig 主要管理格式与代码风格（空格、using 顺序），也能运行并修复部分分析器诊断；SonarQube 的重点则是语义问题与团队治理（资源泄漏、空引用模式、并发反模式、安全风险，以及服务端门禁和趋势）。两者职责有交集，但不能互相替代。
• IDE 插件（现名 SonarQube for IDE）通过连接模式（Connected Mode）与服务器同步质量配置文件和“已接受/误报”标记，保证本地看到的和 CI 门禁判定的是同一套规则——这是团队统一体验的关键。

二、接入实战：把一个 C# 项目跑起来

2.1 起一个服务器

快速体验用 Docker 起 Community Build（官方快速上手命令）：

1
2
3
4

docker run -d --name sonarqube \
  -e SONAR_ES_BOOTSTRAP_CHECKS_DISABLE=true \
  -p 9000:9000 \
  sonarqube:latest

浏览器打开 http://localhost:9000，用默认管理员账号（admin/admin，首次登录强制改密）进入。

两点工程提醒：

• 内置的 H2 数据库仅供试用，生产部署要求外接数据库（2026.5 LTA 起支持 PostgreSQL 15–18；另支持 SQL Server 2017–2022 与 Oracle 19c/21c/23ai）。官方对小规模部署（百万行代码以内）的硬件建议是 4GB 内存、2 核、30GB 磁盘。
• 镜像 tag 建议钉住版本（格式为 版本号-community，如 sonarqube:26.8.0.126808-community），不要长期跑 latest——Community Build 与 Server 一样是持续交付节奏，跨版本跳跃升级要按官方迁移链走。

2.2 生成令牌

SonarQube 提供用户令牌、项目分析令牌和全局分析令牌：Web API 与 IDE 连接模式使用用户令牌，权限等同于生成它的用户；扫描器则优先用权限收敛到单个项目的项目分析令牌，只有需要分析多个项目时才考虑全局分析令牌。它们都从账户设置的安全页面生成。令牌即密码，进 CI 的 secret，不要进代码库；生产环境也不要让扫描与报表脚本共用一个高权限用户令牌。

2.3 三步扫描

SonarScanner for .NET 是官方唯一推荐的 C# 分析入口。安装：

1

dotnet tool install --global dotnet-sonarscanner

分析的经典三步（官方示例原样）：

1
2
3
4
5
6
7
8

dotnet sonarscanner begin \
  /k:"my-app" \
  /d:sonar.host.url="http://localhost:9000" \
  /d:sonar.token="<你的令牌>"

dotnet build --no-incremental --disable-build-servers

dotnet sonarscanner end /d:sonar.token="<你的令牌>"

逐个参数拆开看：

两个平台细节：/k: 与 -k: 两种前缀在所有操作系统上等价（这是扫描器自己的约定，与 shell 无关）；扫描器 7.0 起不再要求预装 Java，首次运行会自动下载所需的 JRE（离线环境可禁用该行为）。

跑完 end 步、终端打出 EXECUTION SUCCESS 之后别急着关页面——这只代表报告上传成功，服务器还要排队处理（见 3.4 节），稍等片刻项目页才有数据。

2.4 挂上覆盖率

SonarQube 自己不产生覆盖率，它只认第三方工具的报告。.NET 下官方支持的主路径有两条，属性名都在 begin 步传入：

路径一：dotnet-coverage 工具（微软官方，跨平台，不依赖 Visual Studio）——产物是 VS Code Coverage 同款 XML：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

dotnet tool install --global dotnet-coverage

dotnet sonarscanner begin \
  /k:"my-app" \
  /d:sonar.host.url="http://localhost:9000" \
  /d:sonar.token="<你的令牌>" \
  /d:sonar.cs.vscoveragexml.reportsPaths=coverage.xml

dotnet build --no-incremental

dotnet-coverage collect "dotnet test" -f xml -o "coverage.xml"

dotnet sonarscanner end /d:sonar.token="<你的令牌>"

路径二：coverlet（opencover 格式）：

1
2
3
4
5
6

dotnet sonarscanner begin /k:"my-app" /d:sonar.token="<你的令牌>" \
  /d:sonar.cs.opencover.reportsPaths=coverage.xml
dotnet build --no-incremental
coverlet <测试程序集路径> --target "dotnet" --targetargs "test --no-build" \
  -f=opencover -o="coverage.xml"
dotnet sonarscanner end /d:sonar.token="<你的令牌>"

两个高频坑，先记下来：

• 属性名是 sonar.cs.vscoveragexml.reportsPaths（XML 转换后的报告），不存在 sonar.cs.vscoverage.reportsPaths 这个属性；coverlet 则要选 opencover 输出格式。两条路也都能产出 cobertura 格式，对应属性 sonar.cs.cobertura.reportsPaths。
• 时序必须是 begin → build → 跑测试出报告 → end。报告在 build 之后、end 之前生成才会被上传。

2.5 第一次读结果

项目页上最该看的三块：

• Measures：覆盖率、重复率、技术债、各类问题计数——项目级体检表。
• New Code 视角：切到新代码区间看指标。存量指标丑不奇怪，新代码指标才说明“今天有没有变得更糟”。
• Activity：每次分析的快照历史，也是后面 Web API 要消费的数据的来源。

三、原理剖析：一次分析在管线里发生了什么

用法背下来不难，难的是出问题时知道去哪看。这一节把三步命令拆开，讲清楚每一步在机器层面做了什么。

3.1 begin：往 MSBuild 里装钩子

begin 不是“配置准备”这么轻描淡写——它实际改写了这次构建的行为。官方文档的描述是：挂入构建管线（hook into the build pipeline）、从服务器下载该项目的质量配置文件与设置、为分析准备项目。落到实现上：

• 扫描器通过 MSBuild 的 ImportBefore targets 机制（SonarQube.Integration.ImportBefore.targets 等文件，在开源仓库 src/SonarScanner.MSBuild.Tasks/Targets/ 下可见）把自己注入每个项目的构建过程；
• 它会把项目的 CodeAnalysisRuleSet 更新为与服务器上激活的质量配置文件相匹配的规则集，并关闭 WarningsAsErrors——否则分析器报警会直接变成构建失败，扫描流程就没法收敛。

这也解释了一个常见疑问：我没在项目里引用 SonarAnalyzer 包，为什么规则能跑？ 官方文档原话：SonarScanner for .NET 会在构建期间“动态”（on the fly）添加 SonarAnalyzer.CSharp / SonarAnalyzer.VB，即使项目没有显式引用它们。

begin 步完成后，执行命令的工作目录下会出现一个 .sonarqube 目录，里面的配置文件（如 .sonarqube-project.properties）记录了实际参与分析的项目与文件范围——排除规则没生效时，先看这里。

3.2 build：Roslyn 分析器在工作

build 步执行的是正常构建，但因为 begin 装了钩子，编译器（csc）会在编译每个项目时调用配置好的 Roslyn 分析器。这里有一个值得点破的事实：SonarScanner 对 C# 的“分析”并不神秘，它就是 Roslyn 分析器 API 的规模化应用——你在 IDE 里看到 Sonar 告警和 CI 上看到的同源同规则。

分析器产出两类东西，都以 protobuf 格式落盘到 .sonarqube 目录下：

• 问题数据：每条规则命中的文件、行号、消息——未来要变成服务器上的 issue；
• 语法 token 数据：代码高亮、符号引用、重复检测所需的 token 序列——服务器 UI 的着色、跳转、重复块识别都靠它。

（官方文档没有逐文件描述 .sonarqube/out 的内部布局，以上“protobuf 落盘”的机制层结论来自扫描器与分析器的开源仓库。）

3.3 end：收集与上传

end 步清理 begin 装上的构建钩子，收集 build 期间生成的分析数据，连同覆盖率与测试结果一起打包上传服务器。内部实现上，end 步会调用一个内嵌的通用 SonarScanner 引擎完成上传（较新版本默认按需下载该引擎；也保留有改用外部 SonarScanner CLI 的开关）。令牌在 end 也要传，就是因为这一步要再次访问服务器。

3.4 服务器端：Compute Engine 与“新代码”的判定

报告上传后的处理发生在服务器的 Compute Engine（后台任务队列）里：分析报告排队后由 worker 导入 issue、计算指标、评估质量门禁。从 Enterprise 版起，可以增加 Compute Engine 的 worker 数，并为同一项目启用分支/PR 分析的并行处理；该并行能力默认启用（可关闭），但实际并行仍需要配置多个 worker。未增加 worker 时，同时提交的多份报告仍会逐个处理；无论是否并行，EXECUTION SUCCESS 都只代表报告上传成功，项目页数据要等后台任务完成后才会更新。队列与日志在 Administration > Projects > Background Tasks（项目管理员在 Project Settings > Background Tasks）可见，分析结果诡异时第一个该看的就是这里。

顺带把技术栈说全：SonarQube 服务器本体是一个 Java 应用——Web 服务与 Compute Engine 都跑在 JVM 上（所以 ZIP 安装要求提供 JDK，性能调优调的也是 JVM 参数），搜索与索引依托内嵌的 Elasticsearch；而你项目里实际执行规则的 SonarAnalyzer 是 C# 写的 Roslyn 分析器，扫描器 end 步内嵌的通用引擎则是 Java——第二节“扫描器 7.0 起自动下载 JRE”的现象，至此就说通了。

后台处理里最关键的一步是 issue 对账：本次扫描出的问题与上次快照对比，行没变的沿用旧 issue（保留处理状态），消失的标记为 Fixed。每个新 issue（上次分析中不存在的问题）的日期，在有 blame 数据时一律取该行最后一次提交的日期，而非分析日期——只有拿不到 SCM 数据时才落到分析日期。这保证“新激活一条规则”“升级分析器”这类在旧代码上首次发现问题的场景，不会让三年前的代码突然背上“新问题”的帽子。这也是官方 GitHub Actions 示例里 fetch-depth: 0（禁止浅克隆）的原因：SCM 信息不全，new code 判定就会失真。

3.5 为什么官方示例都用 --no-incremental

官方文档没有一句“必须非增量构建”的强制原文，但所有官方示例清一色 --no-incremental（dotnet）或 /t:Rebuild（MSBuild）。原因不难推断：分析器在编译时随 csc 执行，增量构建会跳过未变更的项目，被跳过的项目不产生分析数据，上传的报告就是不完整的——而 SonarQube 对“上次有、这次没有”的 issue 会按对账规则处理，可能误标 Fixed。为了数据完整，让每次分析都伴随一次完整编译。

四、质量治理：配置文件、门禁与问题生命周期

4.1 Quality Profile：规则集怎么管

Quality Profile 是“某语言激活了哪些规则、各自什么严重级别”的具名集合。2026.5 起每个语言提供三档内置 profile：

团队定制的正确姿势是继承（extend）：以内置 profile 为父创建子 profile，父级变更自动同步，子级可覆盖严重级别与参数——而不是复制一份静态规则集（复制的那一刻起就与上游脱钩，规则库更新全部漏掉）。

4.2 Quality Gate：门禁怎么设

质量门禁是一组作用在新代码（或全量）指标上的条件，全部满足为 OK。内置 “Sonar way” 门禁的官方条件清单：

一个常被忽略的宽容设计：新代码行数不足 20 行时，覆盖率与重复率条件自动忽略（fudge factor）——避免小 PR 因两行代码没法凑出覆盖率而被误杀。PR 分析只应用 new code 条件，不看全量指标。

门禁条件以指标为基础，所以自定义门禁可以从支持门禁条件的指标中选择（全量或 new code，并设置比较符与阈值）；并非每个可查询指标都能用于门禁。经验上克制比激进活得久：把阈值定到团队现达不到的水平，结局通常不是代码变好，而是门禁被摘掉。

4.3 Issue 生命周期：从 Open 到 Fixed

一条 issue 的状态机（当前版本 UI）：

1
2
3
4
5
6

                    下次分析不再检出（服务器自动判定）
   分析检出      ┌─────────────────────────────────────┐
  ──────────▶  Open ────────────────────────────────▶ Fixed ──(默认保留30天)──▶ 被系统清除
                 │
                 ├──▶ False positive   判为误报：不再计入指标，经连接模式同步进 IDE
                 └──▶ Accepted         暂时不修：显式记为已接受的技术债

历史注脚：旧版的 Won't Fix 在 10.4 前后改名为 Accepted，“Resolve as Fixed” / “Confirm” 等动作同批标记弃用；但 Web API 的枚举至今保留旧值（statuses=OPEN,CONFIRMED,REOPENED,RESOLVED,CLOSED，resolutions=FALSE-POSITIVE,WONTFIX,FIXED,REMOVED）。写脚本查数据时用 API 枚举，看 UI 时用新名，两套并存是现实。

处理方式的选择有讲究：

• False positive：分析器确实错了（比如误判了一个安全的模式）。这是项目内对该条分析结果的明确判定，不代表状态会自动反馈给 SonarSource 或修改规则实现。
• Accepted：问题是真的，但现在不修。它是给“技术债台账”记账用的，且连接模式下会在所有成员的 IDE 里同步消音——团队的“接受”应该比个人的“静音”走得更慎重。
• 直接改代码：永远是第一选择。

4.4 抑制告警的几种姿势与边界

排除参数三兄弟，语义不同别混用：

.NET 侧的已知限制：sonar.exclusions 实际是在 end 步过滤上传的 issue，构建期分析器照跑——所以排除一堆大目录不会等比缩短构建时间。项目级还有两个专用 MSBuild 属性可写进 .csproj：<SonarQubeExclude>true</SonarQubeExclude>（整个项目排除）、<SonarQubeTestProject>true|false</SonarQubeTestProject>（强制标记/取消测试项目）。

测试项目的判定值得一提：扫描器按项目特征自动识别（如 SDK 风格项目里 xunit 等 NuGet 包注入的 TestContainer capability）。测试项目默认会被分析（有专门面向测试的规则）、但不计商业版代码行数、不参与重复检测；想整体跳过可用参数 /d:sonar.dotnet.excludeTestProjects=true。C# 分析器默认跳过能按文件名、特殊注释或特性识别出的工具生成代码；如果某类生成文件未被识别，再用 sonar.exclusions 显式排除。

五、进阶：把 SonarQube 当数据源——Web API

到这里为止，SonarQube 是个“界面产品”。但它的每个页面背后都是一套 HTTP API——质量周报、门禁看板、issue 台账导出、与 IM 机器人集成，都从这里长出来。这一节是本文的进阶核心。

5.1 认证与调用姿势

推荐用 Bearer 认证：

1
2

curl -H "Authorization: Bearer <你的令牌>" \
  "http://localhost:9000/api/components/search?qualifiers=TRK"

（Basic 方案也可用：令牌放用户名、密码留空。自托管实例默认强制认证，未带令牌的请求会被拒。）

两个文档入口记牢：每个实例自带交互式 API 文档，路径是 <服务器地址>/web_api（UI 顶栏帮助菜单也有入口）；机器可读的完整定义在 api/webservices/list，参数、枚举、弃用信息一应俱全——写脚本前先查它，比搜博客可靠。

一个对长期维护者重要的承诺：官方弃用政策规定 API 组件先弃用、后删除，弃用期内继续完整支持，通常至少留出 6 个月迁移期（安全问题等特殊情形除外）；服务器还提供弃用日志（api/system/logs?name=deprecation）供自动化巡检。Web API 没有一个适用于所有自托管部署的统一速率上限承诺，反向代理与实例资源仍可能形成约束；端点声明的分页边界则是硬限制，例如 api/issues/search 的 ps 最大 500、默认 100。

5.2 api/issues/search：翻 issue 台账

最常用的端点。核心参数：

一个值得单独点亮的技巧——facets 聚合。不用把 issue 全拉下来自己数，让服务器替你分组统计：

1
2

curl -H "Authorization: Bearer <你的令牌>" \
  "http://localhost:9000/api/issues/search?components=my-app&resolved=false&ps=1&facets=severities,types,rules,directories"

（ps=1 把明细压到最少，聚合返回的仍是全量统计；ps 下限是 1，不能传 0。）返回结构节选（示意值，只保留聚合相关字段）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "total": 42,
  "effortTotal": 640,
  "facets": [
    { "property": "severities", "values": [
      { "val": "MINOR", "count": 28 },
      { "val": "MAJOR", "count": 12 },
      { "val": "CRITICAL", "count": 2 }
    ]}
  ]
}

effortTotal 是这批 issue 的总修复成本（分钟）；如果要做严格口径的“技术债台账”，应只统计 Maintainability / Code Smell 类问题，或者直接查询技术债指标 sqale_index。issue 对象本体字段众多，常用的有 key（全局唯一）、rule（如 csharpsquid:S2094）、severity、component（文件路径键）、line、message、status、effort、creationDate、updateDate。可用聚合维度还有 rules（按规则聚）、directories（按目录聚）、tags、languages 等，具体集合以实例自带 API 文档为准。

5.3 api/measures/component：指标查询

1
2
3
4

curl -H "Authorization: Bearer <你的令牌>" \
  "http://localhost:9000/api/components/search?qualifiers=TRK"  # 先拿项目键
curl -H "Authorization: Bearer <你的令牌>" \
  "http://localhost:9000/api/measures/component?component=my-app&additionalFields=metrics,period&metricKeys=bugs,vulnerabilities,code_smells,coverage,new_coverage,sqale_index,duplicated_lines_density"

常用 metricKeys：bugs / vulnerabilities / code_smells（问题计数）、coverage / duplicated_lines_density（覆盖率/重复率）、sqale_index（技术债分钟数）、reliability_rating 等（质量评级，1.0 即 A）。许多指标有对应的新代码版本，键名通常加 new_ 前缀（如 new_coverage）；是否存在应以指标文档或 api/metrics/search 为准。新代码度量的值内嵌 period 对象，标明所对应的新代码区间。响应示意：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "component": {
    "key": "my-app", "qualifier": "TRK",
    "measures": [
      { "metric": "coverage", "value": "61.2" },
      { "metric": "new_coverage",
        "period": { "index": 1, "value": "88.4" } }
    ]
  },
  "period": { "mode": "PREVIOUS_VERSION", "parameter": "1.2.0", "date": "2026-08-01T00:00:00+0000" }
}

注意这个 measures 响应里的度量 value 是字符串（“61.2” 而非 61.2），客户端解析时先按 string 读取，再按具体指标转换。

5.4 api/qualitygates/project_status：门禁状态

1
2

curl -H "Authorization: Bearer <你的令牌>" \
  "http://localhost:9000/api/qualitygates/project_status?projectKey=my-app"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "projectStatus": {
    "status": "ERROR",
    "conditions": [
      { "status": "ERROR", "metricKey": "new_coverage",
        "comparator": "LT", "errorThreshold": "80" },
      { "status": "OK", "metricKey": "new_violations",
        "comparator": "GT", "errorThreshold": "0", "actualValue": "0" }
    ],
    "ignoredConditions": false,
    "period": { "mode": "PREVIOUS_VERSION" }
  }
}

status 取值 OK / WARN / ERROR / NONE（无门禁）。条件里的 comparator 是 LT/GT——而 webhook payload 里同一概念的字段叫 operator、取值 LESS_THAN/GREATER_THAN，两处命名不同，写校验逻辑时别混。

5.5 组件发现与分支/PR 状态

• api/components/search?qualifiers=TRK&q=关键词：按名称搜项目（TRK 即项目限定符）；取单个组件详情用 api/components/show?component=<键>（响应里带 analysisDate、version、leakPeriodDate 等）。注意 api/navigation/component 已属内部 API（前向兼容无保证），别依赖。
• api/project_branches/list?project=<键> 与 api/project_pull_requests/list?project=<键>（商业版功能）：列出各分支/PR 的 qualityGateStatus 与 analysisDate，做多分支门禁看板就靠它们。

5.6 C# 客户端实战

一个最小但完整的场景：在 api/issues/search 的 10,000 条结果窗口内，拉取项目所有未解决的 Bug/漏洞，按严重级别汇总，输出修复成本分钟数——质量周报的雏形（.NET 6+ 控制台程序，仅用 BCL）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

using System.Net.Http.Headers;
using System.Text.Json;

// 用法：dotnet run -- <项目键>；令牌从环境变量 SONAR_TOKEN 读取
var baseUrl = "http://localhost:9000";
var projectKey = args.Length > 0 ? args[0] : throw new ArgumentException("用法: SonarReport <项目键>");
var token = Environment.GetEnvironmentVariable("SONAR_TOKEN")
    ?? throw new InvalidOperationException("请先设置环境变量 SONAR_TOKEN");

using var http = new HttpClient { BaseAddress = new Uri(baseUrl) };
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", token);

// 翻页拉取全部未解决的 BUG / VULNERABILITY
var issues = new List<JsonElement>();
int page = 1, total, effortTotal = 0;
const int maxSearchWindow = 10_000;
do
{
    var url = $"/api/issues/search?components={projectKey}"
            + $"&types=BUG,VULNERABILITY&resolved=false&ps=500&p={page++}";
    using var doc = JsonDocument.Parse(await http.GetStringAsync(url));
    total = doc.RootElement.GetProperty("total").GetInt32();
    if (total > maxSearchWindow)
    {
        throw new InvalidOperationException(
            $"查询命中 {total} 条，超过 api/issues/search 的 {maxSearchWindow} 条结果窗口；请按创建时间等条件拆分查询。");
    }
    // effortTotal 是整个查询的总修复成本（分钟），每页返回的都是同一个值
    if (doc.RootElement.TryGetProperty("effortTotal", out var effort)
        && effort.ValueKind == JsonValueKind.Number)
    {
        effortTotal = effort.GetInt32();
    }
    // JsonElement 默认借用 JsonDocument 的缓冲区；文档即将释放，必须 Clone
    issues.AddRange(doc.RootElement.GetProperty("issues")
                                   .EnumerateArray()
                                   .Select(issue => issue.Clone()));
} while (issues.Count < total);

Console.WriteLine($"项目 {projectKey} 未解决 Bug/漏洞共 {issues.Count} 条，总修复成本 {effortTotal} 分钟");

foreach (var g in issues.GroupBy(i => i.GetProperty("severity").GetString())
                        .OrderByDescending(g => g.Count()))
{
    Console.WriteLine($"  {g.Key,-8} {g.Count(),4} 条");
}

api/issues/search 只能访问前 10,000 条匹配结果；超出时要按 createdAfter / createdBefore 等互斥区间拆分查询并去重，不能继续把页码加到 21 以上。把示例换成写 CSV、发企业微信/钉钉机器人，或者按 rules 维度 facet 出 Top 规则，就是一套自制的质量运营面板。

5.7 Webhook：从“拉”到“推”

轮询之外，SonarQube 支持在每次分析完成时主动回调你指定的 URL。配置入口两级：全局（Administration > Configuration > Webhooks）与项目级（Project Settings > Webhooks），每级至多 10 个，两级并存都执行。

POST 到你服务器的 payload（官方文档示例字段，值为本文化用的示意值；branch 对象仅在分支/PR 分析时出现）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "serverUrl": "https://sonar.example.com",
  "taskId": "AVh9KBKv0BLmfT5k6sEQ",
  "status": "SUCCESS",
  "analysedAt": "2026-08-22T02:31:22+0000",
  "revision": "c75d9a9b",
  "project": { "key": "my-app", "name": "My App", "url": "https://sonar.example.com/dashboard?id=my-app" },
  "branch": { "name": "main", "type": "BRANCH", "isMain": true },
  "qualityGate": {
    "name": "Sonar way",
    "status": "ERROR",
    "conditions": [
      { "metric": "new_coverage", "operator": "LESS_THAN", "onLeakPeriod": true,
        "status": "ERROR", "value": "61.2", "errorThreshold": "80" }
    ]
  },
  "properties": {}
}

安全上必须做签名校验：配置 webhook 时填一个 secret，SonarQube 会用它对原始请求体计算 HMAC-SHA256，以小写十六进制放在 X-Sonar-Webhook-HMAC-SHA256 头里。C# 验签（.NET 6+；body 是从请求流读取的原始字节）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

using System.Security.Cryptography;
using System.Text;

static bool VerifyWebhook(string secret, byte[] body, string signatureHeader)
{
    byte[] expected;
    try
    {
        expected = Convert.FromHexString(signatureHeader);
    }
    catch (FormatException)
    {
        return false;
    }

    var actual = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), body);
    return CryptographicOperations.FixedTimeEquals(actual, expected);
}

两个实操细节：验签要用原始字节（先验签再反序列化，中间不要重编码字符串）；投递记录可在服务器上回查（api/webhooks/deliveries），排障时不用苦等下次触发。典型玩法：接住 webhook 后调用 5.4 的接口取全量条件详情，门禁红了就往 MR 里发评论、往群里发卡片——免费版没有 PR 装饰，这套自建链路就是平替。

六、工程落地：CI 集成与避坑清单

6.1 GitHub Actions 接入

官方对 .NET 的推荐做法不是通用的 sonarqube-scan-action（那是给 SonarScanner CLI 的），而是手动三步 + 本地工具缓存。下面是按官方文档改编的完整样例（Windows runner 沿用官方示例）。Scanner 11.x 默认从服务器自动配置所需 JRE，所以这里不再单独安装 Java；如果实例关闭了 JRE 自动配置，需按对应服务器版本另行提供受支持的 JRE：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

name: sonar-analysis
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0            # 浅克隆会破坏 SCM 信息，影响 new code 判定
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: 8.0.x
      - name: 缓存 Sonar 数据
        uses: actions/cache@v4
        with:
          path: ~\.sonar\cache
          key: sonar-${{ runner.os }}
      - name: 缓存 SonarScanner for .NET
        id: cache-sonar-scanner
        uses: actions/cache@v4
        with:
          path: .\.sonar\scanner
          key: sonar-scanner-${{ runner.os }}
      - name: 安装 SonarScanner for .NET
        if: steps.cache-sonar-scanner.outputs.cache-hit != 'true'
        run: |
          New-Item -Path .\.sonar\scanner -ItemType Directory
          dotnet tool update dotnet-sonarscanner --tool-path .\.sonar\scanner
      - name: 构建与分析
        run: |
          $ErrorActionPreference = "Stop"
          $PSNativeCommandUseErrorActionPreference = $true
          .\.sonar\scanner\dotnet-sonarscanner begin /k:"my-app" /d:sonar.token="${{ secrets.SONAR_TOKEN }}" /d:sonar.host.url="${{ vars.SONAR_HOST_URL }}" /d:sonar.cs.vscoveragexml.reportsPaths=coverage.xml
          dotnet build --no-incremental
          dotnet tool install --global dotnet-coverage
          dotnet-coverage collect "dotnet test" -f xml -o "coverage.xml"
          .\.sonar\scanner\dotnet-sonarscanner end /d:sonar.token="${{ secrets.SONAR_TOKEN }}"

要点：SONAR_TOKEN 放 secrets、SONAR_HOST_URL 放 variables；scanner 安装到仓库工作区的专用路径并缓存，命中缓存时不再重复下载。$PSNativeCommandUseErrorActionPreference = $true 让任一原生命令返回非零退出码时立即终止该步骤，避免构建失败后仍继续上传分析。

6.2 门禁接入流水线的两种姿势

6.3 Community Build 的分支限制与应对

免费版只有主分支分析，团队协作里这是真实痛点。现实中的三条路：

1. 只分析主分支：接受“主分支质量体检 + 门禁”的定位，PR 级反馈交给 IDE 插件（连接模式同样能在本地看到全部告警）。个人项目与小团队多数够用。
2. 按分支拆项目键：给特性分支临时分配独立项目键（如 my-app-feature-x）各自分析——社区流传的做法，能看分支数据但历史与治理完全割裂，属于自担维护成本的土办法。
3. 升级商业版或转 SonarQube Cloud：分支/PR 分析、PR 装饰是付费功能，按官方定价买。团队规模到了“PR 门禁是刚需”的程度，这笔账通常算得过来。

6.4 避坑清单

最后一张速查表，每条都是真实踩过的坑：

七、结语：把机械的检查交给机器

回头看 SonarQube 的设计，贯穿始终的是一条朴素的原则：机器擅长的事交给机器，人的注意力留给只有人能做的判断。

Clean as You Code 是这条原则在门禁上的体现：不强求多数遗留系统短期完成“存量清零”，而是先要求每次变更不引入新债。它的巧妙在于把一个往往难以一次完成的要求（“把 5 万个问题修完”）换成了一个可执行的工程要求（“这 20 行新代码达标”），让门禁真正立得住——立得住的门禁才有人尊重，尊重门禁的团队才会把质量当成日常。

Web API 则是这条原则在工具链上的延伸：质量数据不该锁在某个产品的界面里。issue、指标、门禁状态都是结构化数据，周报、看板、机器人、门禁编排，你自己的工程体系想要什么就取什么。

静态分析也有它诚实的边界：它查的是已知模式——规则库里沉淀的、前人踩过的坑。它读不懂你的业务逻辑，不知道这段代码该不该存在；架构层面的坏味道、需求理解的正误，仍然是 review 和设计的领地。SonarQube 的价值不是替代这些，而是把人的时间从中捞出来。

如果你正在一个 .NET 团队里推动代码质量建设，一个务实的起点是：Docker 起 Community Build、主分支接 CI、IDE 插件开连接模式、门禁先跑默认 Sonar way。两周后，你对“团队的代码到底长什么样”会有第一份基于数据的答案——剩下的事，从那里开始。

参考资料

• SonarQube 产品命名调整公告（SonarQube 官方社区）
• SonarQube Server 2026.5 LTA 发布公告
• SonarQube Server LTA 发布周期与当前版本
• 功能对比表：Community Build / Cloud / Server
• SonarQube Server 发布节奏与版本方案
• 安装 SonarScanner for .NET（官方文档）
• 使用 SonarScanner for .NET：三步分析与参数（官方文档）
• 令牌类型与使用范围（官方文档）
• Scanner JRE 自动配置（官方文档）
• .NET 测试覆盖率采集（官方文档）
• 覆盖率参数一览（官方文档）
• C# 分析与生成代码识别（官方文档）
• 不能在界面设置的分析参数（官方文档）
• 测试项目的识别与排除（官方文档）
• GitHub Actions 集成（官方文档）
• 后台任务与 Compute Engine（官方文档）
• Compute Engine 性能与并行处理（官方文档）
• 软件质量模型（官方文档）
• 实例模式：MQR 与 Standard Experience（官方文档）
• 内置质量配置文件三档（官方文档）
• 质量门禁与 Sonar way 条件（官方文档）
• New Code 定义（官方文档）
• Issue 处理与抑制（官方文档）
• Web API 使用指南（官方文档）
• Webhook：项目级配置（官方文档）
• Web API 弃用政策（官方文档）
• SonarQube 开源仓库：Java 服务端源码（GitHub）
• 服务器架构与内嵌 Elasticsearch（官方文档）
• SonarScanner for .NET 开源仓库（GitHub）
• SonarAnalyzer for .NET 开源仓库（GitHub）
• SonarQube 在线 Web API 文档（官方实例）