3. 企业级代码质量度量指标体系

代码质量治理最怕两件事：一是“凭感觉说代码烂”，二是“指标一大堆却没人看”。企业级度量体系的目标，是把主观判断转化为可采集、可比较、可追踪、可归因的数据，并让这些数据能落到具体的仓库、分支、模块、责任人以及迭代周期上。本节围绕缺陷密度、圈复杂度、重复率、测试覆盖率、技术债务比率五类核心指标，讲清它们的定义、采集口径、阈值设定与联动使用方式。

一、指标不是越多越好，先建立分层结构

企业级指标体系通常分为三层：结果层反映质量后果，如缺陷密度、线上故障率；过程层反映代码本身的健康度，如圈复杂度、重复率、覆盖率；成本层反映未来维护代价，如技术债务比率、债务偿还周期。三层之间是因果关系：过程层恶化会推高结果层缺陷，也会累积成本层债务。因此度量体系不能只看结果，否则问题暴露时已经太晚。

在 GitLab 中，这些指标可以分别来自不同数据源：缺陷密度来自 Issue 与缺陷标签统计；圈复杂度、重复率来自 SonarQube 或 GitLab CI 中的静态扫描作业；覆盖率来自单元测试报告（如 JaCoCo、Cobertura、lcov）；技术债务比率来自 SonarQube 的 Maintainability Rating 与债务时间估算。统一汇总到 GitLab 的 Merge Request、项目看板或外部看板中，才能形成闭环。

二、五类核心指标的定义与采集口径

缺陷密度是最经典的结果指标，公式为：缺陷密度 = 缺陷总数 ÷ 代码千行数（KLOC）。关键在于“缺陷”的口径必须统一：是只统计测试阶段发现的 Bug，还是包含线上故障？建议企业内统一为“经确认的功能缺陷 + 线上故障”，并按严重级别加权。例如某模块 12 KLOC，一个迭代内发现 18 个缺陷，则缺陷密度为 1.5 个/KLOC。行业参考值通常在 0.5～2 之间，但更重要的是自身基线趋势。

圈复杂度衡量函数内独立路径数量，公式为：V(G) = E − N + 2P（E 为边数，N 为节点数，P 为连通分量数）。实践中更常用简化计数：每个 if、for、while、case、&&、|| 各加 1，基础值为 1。例如一个函数包含 3 个 if、1 个 for、2 个 &&，则圈复杂度约为 1+3+1+2=7。建议函数级阈值 ≤ 10，超过 15 必须拆分。GitLab CI 中可让 SonarQube 扫描后通过质量门禁阻断超标 MR。

重复率指重复代码行占总代码行的比例。SonarQube 默认以 10 行以上、且 token 序列相同的代码块判定为重复。企业可设定：整体重复率 ≤ 3%，新增代码重复率 ≤ 1%。重复率高的典型信号是复制粘贴式开发，往往伴随缺陷同步扩散——修了一处漏了另一处。

测试覆盖率常用行覆盖率与分支覆盖率两个口径。行覆盖率 = 已执行行 ÷ 可执行行；分支覆盖率 = 已执行分支 ÷ 总分支。仅看行覆盖率容易失真，例如一个 if 只测了 true 分支，行覆盖可能很高但分支覆盖不足。建议新增代码行覆盖率 ≥ 80%、分支覆盖率 ≥ 70%，存量代码允许逐步提升，但不得下降。

技术债务比率来自 SonarQube：债务比率 = 修复所有代码异味所需时间 ÷ 重写代码所需时间。例如修复需 40 小时、重写需 400 小时，则债务比率为 10%，对应可维护性评级 B。企业可设定：债务比率 ≤ 5% 为 A 级，5%～10% 为 B 级，超过 20% 必须列入专项治理。

三、阈值设定与联动判断

单看一个指标容易误判。例如覆盖率很高但缺陷密度也高，说明测试可能只覆盖了“容易测的代码”，核心分支并未覆盖；圈复杂度低但重复率高，说明代码被拆得很碎却大量复制。因此建议建立联动规则：当圈复杂度超标且覆盖率不足时，优先要求补测试并重构；当重复率上升且缺陷密度同步上升时，优先做抽取公共模块。

四、在 GitLab 中落地追踪

落地时建议把指标嵌入研发流程的三个节点。第一，MR 阶段：通过 .gitlab-ci.yml 调用 SonarQube 扫描，设置质量门禁，覆盖率下降或新增代码圈复杂度超标则阻断合并。第二，迭代阶段：在 GitLab 看板中按模块统计缺陷密度与债务变化，识别高风险模块。第三，版本阶段：发布前汇总五类指标，形成质量报告，作为是否放行的依据。

# .gitlab-ci.yml 片段示例
sonarqube-check:
  stage: test
  script:
    - mvn verify sonar:sonar
      -Dsonar.qualitygate.wait=true
      -Dsonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml
  only:
    - merge_requests

指标体系的最终价值不在于“数字好看”，而在于让团队能回答三个问题：当前质量处于什么水平？问题集中在哪些模块？下一步该优先治理什么？当缺陷密度、圈复杂度、重复率、覆盖率、技术债务比率能够按模块、按迭代持续追踪，并与 MR 门禁和发布决策联动时，代码质量治理才真正从口号变成可执行的工程实践。