第四章：代码质量规则¶

规则概述¶

SonarQube 的规则是代码质量检查的核心，每条规则对应一个特定的代码问题检测逻辑。

规则类型¶

类型	说明	图标
Bug	可能导致程序错误的代码	🐛
Vulnerability	安全漏洞	🔓
Code Smell	代码异味，影响可维护性	💩
Security Hotspot	安全敏感点，需人工审查	⚠️

严重级别¶

级别	说明
BLOCKER	阻断级，必须立即修复
CRITICAL	严重级，应尽快修复
MAJOR	主要级，应修复
MINOR	次要级，建议修复
INFO	信息级，仅供参考

质量配置（Quality Profile）¶

质量配置是一组规则的集合，用于定义项目的代码检查标准。

查看质量配置¶

进入 Quality Profiles 页面
选择语言（如 Java、Python）
查看内置的 "Sonar way" 配置

创建自定义质量配置¶

点击 "Create" 创建新配置
选择继承的父配置（通常继承 "Sonar way"）
命名配置（如 "Company Java Profile"）
自定义规则设置

激活/停用规则¶

# 在质量配置中
# 1. 搜索规则
# 2. 点击规则进入详情
# 3. 激活或停用规则
# 4. 设置严重级别和参数

内置规则示例¶

Python 规则¶

1. 未使用的变量 (python:S1481)¶

# ❌ 不合规
def calculate(x, y):
    unused = 10  # 未使用的变量
    return x + y

# ✅ 合规
def calculate(x, y):
    return x + y

2. 空异常捕获 (python:S1541)¶

# ❌ 不合规
try:
    do_something()
except:  # 捕获所有异常
    pass

# ✅ 合规
try:
    do_something()
except ValueError as e:
    logger.error(f"Value error: {e}")

3. SQL 注入风险 (python:S3649)¶

# ❌ 不合规
query = f"SELECT * FROM users WHERE id = {user_input}"

# ✅ 合规
query = "SELECT * FROM users WHERE id = ?"
cursor.execute(query, (user_input,))

JavaScript/TypeScript 规则¶

1. 相等性检查 (javascript:S1764)¶

// ❌ 不合规
if (a == b) {  // 使用 == 而非 ===
  // ...
}

// ✅ 合规
if (a === b) {  // 使用严格相等
  // ...
}

2. 未使用的依赖 (javascript:S4124)¶

// ❌ 不合规
import { unused, used } from 'module';

// ✅ 合规
import { used } from 'module';

3. 敏感数据暴露 (javascript:S2068)¶

// ❌ 不合规
const password = "hardcoded_password";

// ✅ 合规
const password = process.env.PASSWORD;

Java 规则¶

1. 空异常捕获 (java:S108)¶

// ❌ 不合规
try {
    doSomething();
} catch (Exception e) {
    // 空捕获
}

// ✅ 合规
try {
    doSomething();
} catch (Exception e) {
    logger.error("Error occurred", e);
}

2. 资源未关闭 (java:S2095)¶

// ❌ 不合规
FileInputStream fis = new FileInputStream(file);
// 使用后未关闭

// ✅ 合规
try (FileInputStream fis = new FileInputStream(file)) {
    // 使用资源
}

3. 敏感数据硬编码 (java:S2068)¶

// ❌ 不合规
String password = "admin123";

// ✅ 合规
String password = System.getenv("DB_PASSWORD");

自定义规则¶

使用 API 创建规则¶

# 创建自定义规则
curl -X POST "http://localhost:9000/api/rules/create" \
  -u admin:admin \
  -d "custom_key=my-custom-rule" \
  -d "name=My Custom Rule" \
  -d "markdown_description=This is a custom rule description" \
  -d "severity=MAJOR" \
  -d "type=CODE_SMELL" \
  -d "status=READY"

规则参数配置¶

许多规则支持参数配置：

# 示例：配置函数复杂度阈值
sonar.function.cognitiveComplexity.threshold=15

# 示例：配置文件大小限制
sonar.file.size.limit=1000

规则排除¶

# 在项目配置中排除特定规则
sonar.issue.ignore.multicriteria=e1,e2

# 排除规则1：在特定文件
sonar.issue.ignore.multicriteria.e1.ruleKey=java:S1068
sonar.issue.ignore.multicriteria.e1.resourceKey=**/generated/**

# 排除规则2：特定模式
sonar.issue.ignore.multicriteria.e2.ruleKey=python:S1481
sonar.issue.ignore.multicriteria.e2.resourceKey=**/tests/**

规则标签¶

规则可以使用标签进行分类：

# 常见标签
- security: 安全相关
- performance: 性能相关
- bug: Bug 检测
- code-smell: 代码异味
- confusing: 代码可读性
- conventional: 编码规范
- unused: 未使用代码

按标签搜索规则¶

在 Quality Profiles 中，可以使用标签过滤规则：

# 搜索安全相关规则
tag:security

# 搜索性能相关规则
tag:performance

规则继承¶

质量配置支持继承机制：

Sonar way (内置)
    └── Company Profile (继承)
            └── Team Profile (继承)

继承规则修改¶

可以修改继承规则的严重级别
可以停用继承的规则
不能删除继承的规则

规则更新¶

检查规则更新¶

当 SonarQube 升级时，内置规则可能更新：

进入 Quality Profiles
查看是否有 "Update" 提示
点击更新查看变更
确认更新

处理废弃规则¶

# 查看废弃规则
# Quality Profiles → 选择配置 → Change Parent → 查看废弃规则

# 替换废弃规则
# 通常会有替代规则建议

规则最佳实践¶

1. 从内置配置开始¶

# 推荐流程
1. 使用内置的 "Sonar way" 配置
2. 根据团队反馈逐步调整
3. 添加项目特定的自定义规则

2. 规则分级¶

# 建议的规则分级
BLOCKER:
  - 安全漏洞
  - 必定导致错误的问题

CRITICAL:
  - 高风险代码异味
  - 重要的安全问题

MAJOR:
  - 常见代码异味
  - 可维护性问题

MINOR:
  - 编码规范问题
  - 轻微的代码异味

3. 团队共识¶

# 规则讨论流程
1. 新规则提案
2. 团队评审讨论
3. 确定严重级别
4. 试运行验证
5. 正式启用

规则统计¶

查看规则统计¶

# API 查询
curl -u admin:admin "http://localhost:9000/api/rules/search?languages=java&ps=500"

规则覆盖率分析¶

项目概览 → Measures → Rules
- 激活规则数
- 规则覆盖的语言
- 各类型规则分布

小结¶

本章介绍了 SonarQube 的代码质量规则：

规则类型和严重级别
质量配置管理
内置规则示例
自定义规则创建
规则继承和更新

下一章将介绍质量门禁的配置和使用。