5.6 SonarQube 质量雷达：扫描与门禁

5.6 SonarQube 质量雷达：扫描与门禁

本节摘要：SonarQube 通过 sonar-maven-plugin 在构建期采集代码指标、静态缺陷与测试覆盖率，质量门禁规则把不达标的构建拦在合并之前。本节覆盖插件接入、与 JaCoCo 的覆盖率联动、门禁配置的分寸拿捏，以及它与依赖作战（漏扫、重复依赖）的协同位。

质量问题的发现时机决定修复成本

同一类缺陷的三种命运：code review 里被发现，修复成本一刻钟；合并进主干后被 Sonar 扫出，修复成本半天（上下文已断）；线上事故后回溯发现扫描器早就报过，成本以事故计。质量雷达的价值就是把发现时机整体前移——它不是又一道审批，是全天候值班的瞭望哨。

接入 Maven 只需在流水线加一个目标（参数由 CI 注入，不进 POM 可避免本地构建依赖扫描服务）：

mvn sonar:sonar \
  -Dsonar.host.url=扫描服务地址 \
  -Dsonar.login=流水线凭证 \
  -Dsonar.projectKey=risk-engine \
  -Dsonar.sources=src/main/java
# 输出关键行：
# INFO: 分析中...
# INFO: 质量门禁状态 之前 通过 之后 通过
# INFO: 任务总耗时 58 秒
​

输出里"之前"与"之后"两个状态词值得专门看一眼：它们分别是合并前的门禁状态与本轮扫描后的状态，两者都绿才说明这次变更没有把质量画像变差。有的团队只盯"之后"，放走了"从 A 降到 B"的渐进劣化——门禁没破但趋势在滑坡，等破线时欠账已经不小。

覆盖率联动：JaCoCo 的代理注入

覆盖率是门禁的核心指标，采集靠 JaCoCo 与 surefire 的配合——第 5.3 节埋的 argLine 伏笔在这里收线：

<plugin>
  <groupId>org.jacoco</groupId>
  <artifactId>jacoco-maven-plugin</artifactId>
  <version>0.8.10</version>
  <executions>
    <execution>
      <id>prepare-agent</id>
      <!-- 在测试前把覆盖率代理注入 argLine -->
      <goals>
        <goal>prepare-agent</goal>
      </goals>
    </execution>
    <execution>
      <id>report</id>
      <phase>test</phase>
      <!-- 测试后产出覆盖率报告供 sonar 采集 -->
      <goals>
        <goal>report</goal>
      </goals>
    </execution>
  </executions>
</plugin>
​

prepare-agent 的机制是把代理参数写进属性再由 surefire 的 argLine 引用——这正是 5.3 节强调 argLine 要留 @{argLine} 占位符的原因：硬写字面量会把代理注入顶掉，覆盖率静默归零，而"覆盖率 0"的报告比没有报告更有误导性。

门禁的分寸：拦该拦的

门禁规则决定"什么情况拒绝合并"。配置的分寸是门禁制度的生死线——拦太松形同虚设，拦太狠团队会想办法绕过（删测试、加豁免、直接停用门禁）。risk-engine 的门禁四条线，供参考：

设计哲学是增量考核：历史欠账不追（追不动），但每一次提交必须比现状更好或至少不变差。这与 enforcer 门禁（第 3.3 节）的思路一致——制度的目的不是审判过去，是锁住下限。

门禁规则的配置落在扫描服务的质量配置里，几个关键开关的含义要吃透：新代码的定义（按分支比对还是按发布标记，决定"新增覆盖率"的分母）；阻断级问题的分级（哪些规则算 blocker，直接影响拦截力度）；重复代码的统计口径（跨模块是否计入）。这三处配置决定了门禁是"严而有理"还是"严而无理"，上线前团队要过一遍并留下决策记录。

门禁拦截的实际形态长这样：

[INFO] 质量门禁状态：失败
[ERROR] 新增代码覆盖率 62.5% 低于阈值 80%
[ERROR] 存在 2 个阻断级问题 空指针风险与资源未关闭
[INFO] 详细报告：扫描服务地址（合并请求的内联注释同步标注）
// 处置路径：点开报告定位到行 修复后重新推送 门禁自动重评
​

被门禁拦下的修复路径必须顺畅——报告链接直达问题行、IDE 里有对应插件高亮，否则开发者会在挫败中寻找绕过手段。门禁的体验设计与阈值设计同等重要，这是很多团队失败的原因：阈值定了，导航没做，两周后门禁被投票停用。

⚠️ 常见坑一：把覆盖率门禁设成全局一刀切的百分比（比如"全项目必须 60%"）。老模块历史欠账到不了线，团队只有两条路：集体加班补测试（怨恨积累），或者给关键路径加凑数测试（指标好看、价值为零）。增量考核绕开了这两条死路。

⚠️ 常见坑二：扫描与构建串行部署，全量扫描把流水线拖回十分钟时代。处置是分层：提交触发的增量扫描只扫变更文件（秒级），夜间全量扫描出趋势报告，两者各司其职。

与依赖作战的协同位

Sonar 的视野不止代码风格。它的依赖维度扫描与第 3.5 节的漏扫工具互补：漏扫插件对着漏洞库逐坐标比对，Sonar 则把"依赖里的已知漏洞"作为质量画像的一部分呈现，配合 5.5 节的可复现构建，"扫的包就是上的包"这条链路闭合。作战室的定期例会因此有了固定议程：雷达面板扫一遍新增告警、依赖漏洞趋势、覆盖率漂移——质量观测与依赖观测在同一个面板上完成。

💡 关键直觉：门禁上线的前两周必然有阵痛期（存量问题拦住合并），正确姿势是先以"报告模式"跑两周让团队看清欠账，再切换"拦截模式"，同时把门禁阈值写进团队 wiki 的"为什么"而不是只写"是什么"——被理解的标准才会被遵守，被强制执行的标准只会被绕过。

战报小结

• 接入轻量：流水线加 sonar:sonar 目标，凭证由 CI 注入，本地构建不依赖扫描服务；
• 覆盖率靠 JaCoCo 代理注入：prepare-agent 写 argLine，surefire 留占位符，机制互相咬合；
• 门禁的分寸是生死线：增量考核（新代码覆盖率、新增重复、阻断级问题）不追历史账；
• 扫描分层：提交增量秒级扫，夜间全量出趋势，别让质量扫描拖垮反馈半径；
• 与依赖观测同面板：依赖漏洞、覆盖率漂移、新增告警在雷达上合成一份战况图。

第 5 章收官，流水线全面进入稳态。下一章转向交付形态与未来战场：Spring 深度协同、容器镜像、Kotlin 混编、GraalVM 原生编译，最后展望模块化与云原生的演进。