SonarQube Quality Gate 与 Quality Profile

1. Quality Profile：规则集合#

Quality Profile 定义某种语言分析时启用哪些规则。

例如：

• Java 使用 Java 的 Profile。
• JavaScript 使用 JavaScript 的 Profile。
• Go 使用 Go 的 Profile。

一个多语言项目会根据语言分别套用对应 Profile。

SonarQube 提供内置 Profile，常见默认基线是 Sonar way。它适合作为起点，但不一定完全符合每个团队的编码规范。

2. Quality Gate：质量门禁#

Quality Gate 用来回答一个问题：

1
这个项目当前状态是否可以发布或合并？

常见门禁条件：

• 新代码覆盖率不能低于指定阈值。
• 新代码重复率不能超过指定阈值。
• 新代码不能引入严重问题。
• 新代码安全问题必须处理或评审。

Quality Gate 不决定扫描哪些规则，它只根据扫描结果做判定。

3. 为什么更推荐关注新代码#

老项目经常有很多历史问题。如果一开始就要求全量代码全部达标，团队很容易无法推进。

更实用的策略是 Clean as You Code：

• 旧问题先可视化、逐步治理。
• 新增和修改代码必须达标。
• 不让技术债继续扩大。

这也是 SonarQube 质量门禁常围绕 “New Code” 配置的原因。

4. Quality Gate 如何影响流水线#

默认情况下，Scanner 把报告发给 Server 后，Server 异步计算 Quality Gate。

如果希望 CI/CD 等待结果，可以在扫描时设置：

1
sonar-scanner -Dsonar.qualitygate.wait=true

门禁失败时，扫描步骤会失败，流水线可以停止。

这一步是 SonarQube 从“报告工具”变成“质量控制点”的关键。

1. 初期不要把门禁设得过重#

刚接入时可以先守住新代码：

1
新代码无阻断级问题
2
新代码覆盖率达到团队最低线
3
新代码重复率不超过阈值

不要一开始就要求历史代码全部清零，否则容易让团队绕过扫描。

2. Profile 优先从默认规则开始#

建议先使用内置 Profile 观察一段时间，再根据项目实际情况创建自定义 Profile。

适合调整的情况：

• 某些规则和团队规范明显冲突。
• 某些规则在当前语言或框架下误报较多。
• 团队希望增加更严格的安全或可靠性规则。

3. Gate 要和发布策略绑定#

如果 Quality Gate 失败但流水线照常发布，门禁就失去了意义。

更合理的做法是：

• 普通分支：允许失败但发出通知。
• 合并请求或主分支：门禁失败阻断合并或发布。
• 紧急发布：允许人工审批绕过，但要留下记录。

1. 把 Profile 当成 Gate#

Profile 是规则集合，Gate 是结果判定。修改 Profile 可能改变扫描结果，但它不是“通过/失败”的条件本身。

2. 全量历史问题一刀切#

老项目刚接入时，如果要求全部历史问题立即修复，通常会导致接入失败。先控制新代码更现实。

3. 覆盖率门禁没有测试报告支撑#

SonarQube 不会凭空生成覆盖率。覆盖率通常要由测试工具生成报告，再由 Scanner 读取。

4. 只看问题数量，不看严重性和类型#

问题数量多不一定都严重。更应该关注新代码里的严重问题、安全问题、重复率和覆盖率趋势。

5. 规则调整没有记录#

自定义 Profile 修改规则时，最好记录原因。否则后面很难判断一条规则是误关了，还是确实不适合团队。