SonarQube 使用方式与典型场景

四、使用方式与典型场景

示例一：通用项目用 CLI 扫描。先在服务端创建项目并生成令牌，然后在项目根目录放配置文件：

# sonar-project.properties（放进仓库，注意不要放令牌）
sonar.projectKey=ok-platform-api
sonar.projectName=OK 平台 API
sonar.sources=src
sonar.tests=test
sonar.sourceEncoding=UTF-8
sonar.exclusions=**/generated/**,**/node_modules/**,**/dist/**
sonar.coverage.exclusions=**/*.config.js,**/migrations/**
# Java 项目必填
sonar.java.binaries=target/classes
sonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml

# 安装并执行扫描（令牌从环境变量注入）
export SONAR_TOKEN=你的分析令牌

sonar-scanner \
  -Dsonar.host.url=http://sonar.internal:9000 \
  -Dsonar.token=$SONAR_TOKEN

# 想查看详细日志
sonar-scanner -X

示例二：Maven 项目直接用插件，并让流水线等门禁结果。

# 先跑测试生成 JaCoCo 报告，再执行分析
mvn clean verify sonar:sonar \
  -Dsonar.host.url=http://sonar.internal:9000 \
  -Dsonar.token=$SONAR_TOKEN \
  -Dsonar.qualitygate.wait=true

其中 -Dsonar.qualitygate.wait=true 是关键：加上它，命令会等分析处理完并取回门禁结论，门禁不过则以非零码退出，流水线自然阻断。不加的话命令会在推送完结果后立刻返回成功，门禁形同虚设。

示例三：在流水线里作为质量门禁。

# GitLab CI 片段
sonarqube-check:
  image: maven:3-eclipse-temurin-17
  variables:
    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"
    GIT_DEPTH: "0"        # 需要完整历史，否则新代码范围判定会不准
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script:
    - mvn clean verify sonar:sonar
      -Dsonar.host.url=$SONAR_HOST_URL
      -Dsonar.token=$SONAR_TOKEN
      -Dsonar.qualitygate.wait=true
  allow_failure: false

示例四：只卡新代码的策略切换。门禁条件针对「新代码」而不是「整体」，是存量项目能落地的前提：

# 说明性示例：门禁条件在新代码维度上的常见写法（在服务端界面配置）
# 新代码覆盖率      >= 阈值
# 新代码重复率      <= 阈值
# 新代码新增 Bug    = 0
# 新代码新增漏洞    = 0（或不允许 Blocker/Critical 级）
#
# New Code 的边界有三种定义方式，选一种并全团队统一：
#   1) 相对上一个版本（适合有明确发布节奏的项目）
#   2) 最近 N 天（适合持续部署、每天都在合的项目）
#   3) 指定基线之后（适合存量治理，先划一条线，只要求线后干净）

适合与不适合的场景：SonarQube 适合有一定规模、多人协作、需要「统一标准 + 长期趋势」的代码库；适合把质量指标纳入发布流程的团队；也适合做存量代码治理——先用基线划一条线，再逐步还债。不太适合的场景：一次性脚本、demo 仓库、只有几百行的工具类项目，跑一套平台的开销不划算；另外它不做运行时分析，性能问题、并发缺陷、配置错误这些它看不到，需要和压测、动态扫描、依赖扫描配套使用。