第三章：项目配置¶

创建项目¶

方式一：手动创建¶

登录 SonarQube
点击 "Create Project"
选择 "Manually"
填写项目信息：
Project key: 项目唯一标识（如 my-project）
Display name: 项目显示名称
Branch: 主分支名称（默认 main）

方式二：从代码仓库导入¶

支持 GitHub、GitLab、Bitbucket、Azure DevOps 等：

选择 "From GitHub/GitLab/..."
授权访问代码仓库
选择要导入的仓库
自动创建项目

配置分析¶

创建配置文件¶

在项目根目录创建 sonar-project.properties：

# 项目基本信息
sonar.projectKey=my-project
sonar.projectName=My Project
sonar.projectVersion=1.0

# 源代码路径
sonar.sources=src
sonar.tests=tests

# 排除文件
sonar.exclusions=**/*.test.js,**/node_modules/**,**/dist/**
sonar.test.exclusions=**/*.test.js

# 语言特定配置
sonar.javascript.node.maxspace=4096
sonar.python.version=3.9

# 代码覆盖率
sonar.coverage.exclusions=**/migrations/**,**/tests/**

# 重复代码排除
sonar.cpd.exclusions=**/models/**

多模块项目配置¶

对于多模块项目，可以在根目录配置：

# 根目录配置
sonar.projectKey=multi-module-project
sonar.projectName=Multi Module Project

# 模块配置
sonar.modules=module1,module2,module3

# 模块1
module1.sonar.projectBaseDir=module1
module1.sonar.sources=src

# 模块2
module2.sonar.projectBaseDir=module2
module2.sonar.sources=src

# 模块3
module3.sonar.projectBaseDir=module3
module3.sonar.sources=src

执行分析¶

使用 SonarScanner¶

# 基本命令
sonar-scanner

# 指定配置文件
sonar-scanner -Dproject.settings=sonar-project.properties

# 命令行参数覆盖
sonar-scanner \
  -Dsonar.projectKey=my-project \
  -Dsonar.sources=src \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.token=squ_xxxxxxxxxxxx

使用 Maven¶

# 编译并分析
mvn clean verify sonar:sonar

# 指定参数
mvn sonar:sonar \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.token=squ_xxxxxxxxxxxx

使用 Gradle¶

# 执行分析
./gradlew sonarqube \
  -Dsonar.token=squ_xxxxxxxxxxxx

使用 Docker¶

docker run --rm \
  -v /path/to/project:/usr/src \
  sonarsource/sonar-scanner-cli \
  -Dsonar.projectKey=my-project \
  -Dsonar.sources=. \
  -Dsonar.host.url=http://host.docker.internal:9000 \
  -Dsonar.token=squ_xxxxxxxxxxxx

代码覆盖率配置¶

Python (pytest + coverage)¶

# 安装依赖
pip install pytest coverage

# 运行测试并生成覆盖率报告
coverage run -m pytest
coverage xml -o coverage.xml

# SonarQube 配置
sonar.python.coverage.reportPaths=coverage.xml

JavaScript/TypeScript (Jest)¶

// jest.config.js
module.exports = {
  collectCoverage: true,
  coverageReporters: ['lcov', 'text'],
  coverageDirectory: 'coverage',
};

# sonar-project.properties
sonar.javascript.lcov.reportPaths=coverage/lcov.info

Java (JaCoCo)¶

<!-- pom.xml -->
<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.11</version>
    <executions>
        <execution>
            <goals>
                <goal>prepare-agent</goal>
            </goals>
        </execution>
        <execution>
            <id>report</id>
            <phase>test</phase>
            <goals>
                <goal>report</goal>
            </goals>
        </execution>
    </executions>
</plugin>

# sonar-project.properties
sonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml

分支分析¶

短生命周期分支¶

适用于 PR/MR 分析：

sonar-scanner \
  -Dsonar.branch.name=feature/new-feature \
  -Dsonar.branch.target=main

长生命周期分支¶

适用于发布分支：

sonar-scanner \
  -Dsonar.branch.name=release-1.0 \
  -Dsonar.branch.type=LONG

PR 装饰¶

GitHub¶

sonar-scanner \
  -Dsonar.pullrequest.key=123 \
  -Dsonar.pullrequest.branch=feature/new-feature \
  -Dsonar.pullrequest.base=main \
  -Dsonar.scm.revision=abc123...

GitLab¶

sonar-scanner \
  -Dsonar.pullrequest.key=123 \
  -Dsonar.pullrequest.branch=feature/new-feature \
  -Dsonar.pullrequest.base=main \
  -Dsonar.gitlab.instanceUrl=https://gitlab.com \
  -Dsonar.gitlab.project_id=12345

高级配置¶

排除和包含¶

# 包含特定文件
sonar.inclusions=**/*.java,**/*.py

# 排除特定文件
sonar.exclusions=**/generated/**,**/vendor/**

# 测试文件排除
sonar.test.exclusions=**/*.test.js,**/*.spec.ts

# 覆盖率排除
sonar.coverage.exclusions=**/config/**,**/dto/**

# 重复代码排除
sonar.cpd.exclusions=**/models/**,**/entities/**

源代码编码¶

sonar.sourceEncoding=UTF-8

分析范围¶

# 只分析新代码
sonar.scm.revision=HEAD
sonar.newCode.referenceBranch=main

# 分析特定时间范围的代码
sonar.scm.revision=abc123

外部问题导入¶

# 导入外部问题报告
sonar.externalIssuesReportPaths=issues.json

// issues.json 示例
{
  "issues": [
    {
      "engineId": "ESLint",
      "ruleId": "no-unused-vars",
      "primaryLocation": {
        "message": "'x' is defined but never used.",
        "filePath": "src/index.js",
        "textRange": {
          "startLine": 10,
          "startColumn": 4
        }
      },
      "severity": "MAJOR",
      "type": "CODE_SMELL"
    }
  ]
}

项目权限管理¶

设置权限¶

进入项目 → Project Settings → Permissions
配置权限：
Administer: 项目管理权限
Execute Analysis: 执行分析权限
Browse: 查看项目权限

权限模板¶

# 创建权限模板
# Administration → Configuration → Permission Templates

Webhook 配置¶

配置 Webhook 接收分析完成通知：

# 项目设置 → Webhooks
# 添加 Webhook URL
http://your-server/webhook/sonarqube

Webhook 载荷示例：

{
  "status": "SUCCESS",
  "analysedAt": "2024-01-15T10:30:00+0000",
  "project": {
    "key": "my-project",
    "name": "My Project"
  },
  "qualityGate": {
    "status": "OK",
    "conditions": [
      {
        "metric": "new_bugs",
        "operator": "GREATER_THAN",
        "value": "0",
        "status": "OK"
      }
    ]
  }
}

小结¶

本章介绍了项目配置的主要内容：

项目创建方式
分析配置文件编写
不同语言的覆盖率配置
分支分析和 PR 装饰
高级配置选项

下一章将介绍代码质量规则的配置和自定义。