sonarqube

SonarQube / SonarCloud

何时不使用此技能

• JavaScript/TypeScript 代码检查 - 使用 eslint-biome 技能以获得更快的反馈
• 安全扫描 - 使用 owasp-top-10 或 security-scanner MCP
• 测试执行 - 使用 Vitest/Playwright 技能运行测试
• 代码覆盖率生成 - 使用 JaCoCo/Vitest 技能生成覆盖率报告

深入了解：使用 mcp__documentation__fetch_docs，并将 technology 设为 sonarqube，以获取全面的文档。

官方文档

资源	链接
SonarQube 文档	https://docs.sonarsource.com/sonarqube/latest/
SonarCloud 文档	https://docs.sonarsource.com/sonarcloud/
规则仓库	https://rules.sonarsource.com/
API 参考	https://sonarcloud.io/web_api/

---

快速设置

SonarCloud（开源项目推荐）

# 1. Connect repo at sonarcloud.io
# 2. Create sonar-project.properties

# sonar-project.properties
sonar.projectKey=org_project
sonar.organization=your-org
sonar.sources=src
sonar.tests=tests
sonar.javascript.lcov.reportPaths=coverage/lcov.info
sonar.coverage.exclusions=**/*.test.ts,**/*.spec.ts

SonarQube（可自托管）

# docker-compose.yml
services:
  sonarqube:
    image: sonarqube:lts-community
    ports:
      - "9000:9000"
    environment:
      - SONAR_JDBC_URL=jdbc:postgresql://db:5432/sonar
    volumes:
      - sonarqube_data:/opt/sonarqube/data

---

质量门禁

默认质量门禁条件

指标	条件	目标
覆盖率	新代码	≥ 80%
重复行	新代码	≤ 3%
可维护性评级	新代码	A
可靠性评级	新代码	A
安全评级	新代码	A
已审查的安全热点	新代码	100%

自定义质量门禁

# Create via API
curl -X POST "https://sonarcloud.io/api/qualitygates/create" \
  -H "Authorization: Bearer $SONAR_TOKEN" \
  -d "name=Strict"

---

CI/CD 集成

GitHub Actions

# .github/workflows/sonar.yml
name: SonarCloud
on: [push, pull_request]

jobs:
  sonarcloud:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: SonarCloud Scan
        uses: SonarSource/sonarcloud-github-action@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

Maven（Java）

<plugin>
    <groupId>org.sonarsource.scanner.maven</groupId>
    <artifactId>sonar-maven-plugin</artifactId>
    <version>3.10.0.2594</version>
</plugin>

mvn sonar:sonar \
  -Dsonar.projectKey=project \
  -Dsonar.host.url=https://sonarcloud.io \
  -Dsonar.token=$SONAR_TOKEN

---

关键指标

指标	说明	良好值
Bug	可靠性问题	0
漏洞	安全问题	0
代码异味	可维护性问题	尽量减少
覆盖率	测试覆盖率 %	> 80%
重复代码	重复代码 %	< 3%
认知复杂度	代码可理解性	< 15/函数

---

特定语言规则

语言	规则数	链接
JavaScript/TS	422	https://rules.sonarsource.com/javascript/
Java	733	https://rules.sonarsource.com/java/
Python	300+	https://rules.sonarsource.com/python/
C#	400+	https://rules.sonarsource.com/csharp/
Go	100+	https://rules.sonarsource.com/go/

---

排除文件

# sonar-project.properties
sonar.exclusions=**/node_modules/**,**/dist/**,**/*.test.ts
sonar.coverage.exclusions=**/tests/**,**/__mocks__/**
sonar.cpd.exclusions=**/generated/**

---

API 示例

# Get project status
curl "https://sonarcloud.io/api/qualitygates/project_status?projectKey=KEY" \
  -H "Authorization: Bearer $SONAR_TOKEN"

# Get issues
curl "https://sonarcloud.io/api/issues/search?componentKeys=KEY&types=BUG" \
  -H "Authorization: Bearer $SONAR_TOKEN"

# Get metrics
curl "https://sonarcloud.io/api/measures/component?component=KEY&metricKeys=coverage,bugs,vulnerabilities" \
  -H "Authorization: Bearer $SONAR_TOKEN"

---

反模式

反模式	不良原因	正确做法
PR 未设置质量门禁	合并质量差的代码	启用 PR 装饰，并在失败时阻止合并
从覆盖率中排除所有测试	覆盖率数据虚高	仅排除测试工具代码
忽略代码异味	技术债务不断累积	修复问题或添加注释说明理由
不报告覆盖率	无法追踪质量趋势	在 CI 中配置覆盖率报告
使用默认质量门禁	对大多数项目而言过于宽松	创建更严格的自定义门禁
不审查安全热点	可能遗漏漏洞	发布前审查所有安全热点

快速故障排除

问题	可能原因	解决方案
质量门禁意外失败	新代码覆盖率 < 80%	添加测试或调整覆盖率目标
未运行分析	缺少 SONAR_TOKEN	将令牌添加到 CI 密钥中
覆盖率始终为 0%	报告路径错误	检查 sonar.javascript.lcov.reportPaths
重复代码误报	样板代码	添加到 sonar.cpd.exclusions
报告的问题过多	首次扫描旧代码	聚焦“新代码”，逐步修复
PR 装饰不起作用	未集成 GitHub App	配置 SonarCloud GitHub App

---

相关技能

• 质量原则
• GitHub Actions
• JaCoCo