第五章：质量门禁¶

什么是质量门禁？¶

质量门禁（Quality Gate）是一组条件，用于判断代码是否达到质量标准。当代码分析完成后，SonarQube 会根据质量门禁条件给出通过或失败的结果。

质量门禁状态¶

状态	说明
✅ Passed	代码质量达标
❌ Failed	代码质量未达标
⚠️ Warning	警告状态（自定义配置）

内置质量门禁¶

SonarQube 提供内置的 "Sonar way" 质量门禁：

# Sonar way 质量门禁条件
条件:
  - 新代码 Bug 数 = 0
  - 新代码漏洞数 = 0
  - 新代码安全热点数 = 0
  - 新代码覆盖率 >= 80%
  - 新代码重复率 <= 3%

创建自定义质量门禁¶

方式一：Web 界面¶

进入 Quality Gates 页面
点击 "Create"
命名质量门禁（如 "Company Gate"）
添加条件
设置为默认

方式二：API 创建¶

# 创建质量门禁
curl -X POST "http://localhost:9000/api/qualitygates/create" \
  -u admin:admin \
  -d "name=Company Gate"

# 添加条件
curl -X POST "http://localhost:9000/api/qualitygates/create_condition" \
  -u admin:admin \
  -d "gateName=Company Gate" \
  -d "metric=new_bugs" \
  -d "operator=EQUALS" \
  -d "error=0"

质量门禁条件¶

可用度量指标¶

指标	说明	类型
new_bugs	新代码 Bug 数	数值
new_vulnerabilities	新代码漏洞数	数值
new_security_hotspots	新代码安全热点数	数值
new_code_smells	新代码异味数	数值
new_coverage	新代码覆盖率	百分比
new_duplicated_lines_density	新代码重复率	百分比
new_sqale_debt_ratio	新代码技术债务比率	百分比
reliability_rating	可靠性评级	评级
security_rating	安全性评级	评级
sqale_rating	可维护性评级	评级

操作符¶

操作符	说明	适用类型
EQUALS	等于	数值
NOT_EQUALS	不等于	数值
GREATER_THAN	大于	数值、百分比
LESS_THAN	小于	数值、百分比
GREATER_THAN_OR_EQUAL	大于等于	数值、百分比
LESS_THAN_OR_EQUAL	小于等于	数值、百分比

评级标准¶

评级使用 A-E 字母：

A: 优秀
B: 良好
C: 一般
D: 较差
E: 很差

常见质量门禁配置¶

严格型配置¶

# 严格型质量门禁
name: Strict Gate
conditions:
  - metric: new_bugs
    operator: EQUALS
    error: "0"

  - metric: new_vulnerabilities
    operator: EQUALS
    error: "0"

  - metric: new_security_hotspots
    operator: EQUALS
    error: "0"

  - metric: new_code_smells
    operator: EQUALS
    error: "0"

  - metric: new_coverage
    operator: LESS_THAN
    error: "90"

  - metric: new_duplicated_lines_density
    operator: GREATER_THAN
    error: "1"

宽松型配置¶

# 宽松型质量门禁
name: Relaxed Gate
conditions:
  - metric: new_bugs
    operator: LESS_THAN_OR_EQUAL
    error: "5"

  - metric: new_vulnerabilities
    operator: EQUALS
    error: "0"

  - metric: new_coverage
    operator: LESS_THAN
    error: "50"

安全优先配置¶

# 安全优先质量门禁
name: Security First Gate
conditions:
  - metric: new_vulnerabilities
    operator: EQUALS
    error: "0"

  - metric: new_security_hotspots
    operator: EQUALS
    error: "0"

  - metric: security_rating
    operator: GREATER_THAN
    error: "A"

项目关联质量门禁¶

设置项目质量门禁¶

进入项目设置
选择 Quality Gate
选择要使用的质量门禁

API 设置¶

curl -X POST "http://localhost:9000/api/qualitygates/select" \
  -u admin:admin \
  -d "projectKey=my-project" \
  -d "gateName=Company Gate"

新代码定义¶

质量门禁主要针对"新代码"，需要定义什么是新代码。

新代码周期类型¶

类型	说明
Previous version	与上一版本比较
Number of days	最近 N 天的代码
Specific analysis	与指定分析比较
Reference branch	与参考分支比较

配置新代码周期¶

# 项目设置 → New Code
# 选择新代码定义方式

# 方式一：最近14天
type: NUMBER_OF_DAYS
value: 14

# 方式二：参考分支
type: REFERENCE_BRANCH
value: main

API 配置¶

curl -X POST "http://localhost:9000/api/new_code_periods/set" \
  -u admin:admin \
  -d "project=my-project" \
  -d "type=NUMBER_OF_DAYS" \
  -d "value=14"

质量门禁结果获取¶

Web 界面查看¶

项目概览 → Quality Gate
- 显示通过/失败状态
- 显示各项条件结果
- 显示问题详情

API 获取¶

# 获取质量门禁状态
curl -u admin:admin \
  "http://localhost:9000/api/qualitygates/project_status?projectKey=my-project"

响应示例：

{
  "projectStatus": {
    "status": "ERROR",
    "conditions": [
      {
        "status": "ERROR",
        "metricKey": "new_bugs",
        "comparator": "GT",
        "errorThreshold": "0",
        "actualValue": "3"
      },
      {
        "status": "OK",
        "metricKey": "new_coverage",
        "comparator": "LT",
        "errorThreshold": "80",
        "actualValue": "85"
      }
    ]
  }
}

CI/CD 中使用¶

# 等待质量门禁结果
sonar-scanner

# 使用 sonar-quality-gate 插件
# Maven
mvn sonar:sonar sonar-quality-gate:check

# 或使用 API 轮询
curl -u admin:admin \
  "http://localhost:9000/api/qualitygates/project_status?projectKey=my-project&pullRequest=123"

质量门禁通知¶

邮件通知¶

# sonar.properties
sonar.email.from=noreply@example.com
sonar.email.prefix=[SonarQube]

Webhook 通知¶

// Webhook 载荷
{
  "qualityGate": {
    "name": "Sonar way",
    "status": "ERROR",
    "conditions": [
      {
        "value": "3",
        "errorThreshold": "0",
        "status": "ERROR",
        "metric": "new_bugs",
        "comparator": "GT"
      }
    ]
  }
}

质量门禁最佳实践¶

1. 渐进式引入¶

# 推荐引入流程
阶段一：使用宽松配置，收集数据
阶段二：逐步收紧条件
阶段三：达到目标配置

2. 团队协商¶

# 质量门禁制定流程
1. 收集团队意见
2. 确定关键指标
3. 设定合理阈值
4. 试运行验证
5. 正式启用

3. 定期审查¶

# 审查周期
- 每月审查质量门禁效果
- 根据项目情况调整
- 记录调整原因

4. 分项目配置¶

# 不同类型项目使用不同配置
核心系统: 严格型
一般系统: 标准型
原型项目: 宽松型

常见问题¶

1. 质量门禁一直失败¶

# 检查问题
1. 查看具体失败条件
2. 分析问题类型
3. 修复问题或调整阈值

2. 新代码定义不准确¶

# 调整新代码周期
1. 检查当前新代码定义
2. 选择合适的定义方式
3. 重新分析项目

3. CI/CD 中获取状态失败¶

# 确保
1. 分析已完成
2. 有足够权限
3. 正确的项目 Key

小结¶

本章介绍了质量门禁的配置和使用：

质量门禁概念和状态
创建自定义质量门禁
质量门禁条件和操作符
新代码定义
CI/CD 集成

下一章将介绍 CI/CD 流水线集成。