Code Quality Tools

代码质量工具

本页面介绍 FastQTools 项目中使用的代码质量工具，包括安装、使用和输出解读。

---

工具概览

类别	工具	用途	运行时机
内存检查	AddressSanitizer	内存错误检测	每次 PR
内存检查	MemorySanitizer	未初始化内存	手动
线程检查	ThreadSanitizer	数据竞争检测	手动
未定义行为	UBSan	UB 检测	手动
深度分析	Valgrind	内存泄漏、缓存分析	每周
静态分析	clang-tidy	代码质量	每次 PR
静态分析	Cppcheck	额外检查	每次 PR
头文件分析	IWYU	头文件依赖检查	手动
覆盖率	lcov	测试覆盖率	每次 PR
安全测试	libFuzzer	模糊测试	手动

---

Sanitizers

Sanitizers 是编译器内置功能，无需额外安装。确保使用 GCC 15 或 Clang 21。

使用

# AddressSanitizer — 内存错误（泄漏/溢出/UAF）
./scripts/core/build --sanitizer asan --dev
./scripts/core/test -b build/clang-debug

# ThreadSanitizer — 数据竞争
./scripts/core/build --sanitizer tsan --dev
./scripts/core/test -b build/clang-debug

# UndefinedBehaviorSanitizer — 未定义行为
./scripts/core/build --sanitizer ubsan --dev
./scripts/core/test -b build/clang-debug

# MemorySanitizer — 未初始化内存（仅 Clang）
./scripts/core/build --sanitizer msan --dev -c clang
./scripts/core/test -b build/clang-debug

注意: TSan 与 ASan 不能同时启用。

配置选项

环境变量配置文件位于 config/sanitizers/：

export ASAN_OPTIONS="detect_leaks=1:halt_on_error=0:print_stats=1"
export TSAN_OPTIONS="halt_on_error=0:second_deadlock_stack=1"
export UBSAN_OPTIONS="print_stacktrace=1:halt_on_error=0"

输出解读

ASan 错误类型:

类型	说明
heap-buffer-overflow	堆缓冲区溢出
stack-buffer-overflow	栈缓冲区溢出
use-after-free	释放后使用
double-free	重复释放
memory leak	内存泄漏

TSan 输出: 显示两个线程对同一内存地址的冲突访问，附带完整调用栈。

---

Valgrind

安装

sudo apt-get install valgrind   # Ubuntu/Debian

使用

# 使用 Valgrind 运行测试
./scripts/core/test -b build/clang-debug --valgrind

# 手动 Memcheck
./scripts/tools/valgrind-memcheck

# 缓存性能分析
./scripts/tools/valgrind-cachegrind

泄漏报告解读

级别	说明	处理
definitely lost	确定泄漏	必须修复
indirectly lost	间接泄漏	随 definitely lost 一起修复
possibly lost	可能泄漏	需要检查
still reachable	程序结束时仍可访问	通常是全局对象，可忽略

已知的第三方库误报在 config/valgrind/suppressions.supp 中配置。

---

静态分析

clang-tidy

./scripts/core/lint tidy        # 运行检查
./scripts/core/lint tidy-fix    # 自动修复

配置文件: .clang-tidy

Cppcheck

sudo apt-get install cppcheck
./scripts/core/lint cppcheck

配置文件: config/cppcheck/cppcheck.cfg

Include-What-You-Use

sudo apt-get install iwyu
./scripts/core/lint iwyu

映射文件: config/iwyu/mappings.imp

运行所有检查

./scripts/core/lint all

---

代码覆盖率

安装

sudo apt-get install lcov       # 必需
pip install gcovr               # 可选：XML 报告

使用

# 完整流程
./scripts/core/build --coverage --dev
./scripts/core/test -b build/clang-debug
./scripts/tools/coverage-report

# XML 报告（CI 用）
./scripts/tools/coverage-report --xml

# 检查阈值
./scripts/tools/coverage-report --check-threshold

输出

• HTML 报告: coverage_report/html/index.html
• XML 报告: coverage_report/coverage.xml

阈值配置

config/coverage/thresholds.json：

{
  "line_coverage": { "minimum": 70, "target": 80 },
  "function_coverage": { "minimum": 80, "target": 90 }
}

---

模糊测试

需要 Clang 编译器和 libFuzzer（Clang 内置）。

使用

# 构建并运行
./scripts/tools/run-fuzzer --build

# 运行特定 fuzzer
./scripts/tools/run-fuzzer parser -t 300

# 并行运行
./scripts/tools/run-fuzzer -j 4 -t 3600

语料库

种子文件位于 tools/fuzz/corpus/。

崩溃处理

1. 崩溃输入保存在 build/fuzz/fuzz_artifacts/
2. 重现: ./fuzzers/fastq_parser_fuzzer crash-xxx
3. 修复后将崩溃输入添加到语料库作为回归测试

---

FAQ

Q: ASan 报告第三方库泄漏？

A: 检查是否在抑制文件 config/sanitizers/ 中配置，或添加新的抑制规则。

Q: TSan 误报？

A: 使用 __tsan_acquire / __tsan_release 注解，或添加抑制规则。

Q: Valgrind 太慢？

A: Valgrind 通常慢 10–50×，日常开发用 ASan 更快，Valgrind 适合定期深度检查。

Q: 覆盖率报告 0%？

A: 确保：(1) --coverage 构建 (2) 运行了测试 (3) 测试执行了被测代码

Q: Fuzzer 没发现问题？

A: 增加 -t 运行时间、添加更多种子文件、增加 -l 输入长度限制。

---

参考链接

• AddressSanitizer
• ThreadSanitizer
• Valgrind Manual
• clang-tidy
• libFuzzer

---

相关页面

• Testing Strategy — 测试策略
• Build and CI — 构建与 CI 配置
• Performance Benchmarks — 性能基准测试