📚 课程目录第4章代码质量门禁

4、代码质量门禁：静态代码扫描规则、代码覆盖率阈值、代码规范检查、代码审查通过率

代码质量门禁是发布流程的第一道防线，其核心目标是在代码合入主干之前，自动拦截低质量、高风险变更。本章围绕四项关键指标，定义门禁规则、阈值设定与检查流程。

4.1 静态代码扫描规则

静态代码扫描（SAST）在编译前分析源码，识别安全漏洞、代码坏味与逻辑缺陷。门禁规则需覆盖以下维度：

扫描维度	典型规则示例	阻断等级
安全漏洞	SQL注入、XSS、硬编码密钥、路径遍历	Critical / Blocker
代码坏味	过长方法、过深嵌套、重复代码、未使用变量	Major / Minor
合规检查	许可证冲突、敏感数据日志、加密算法强度	Critical / Major
可靠性	空指针解引用、资源未关闭、线程安全问题	Blocker / Critical

  门禁策略： 任何 Blocker 级别问题直接阻断合并；Critical 级别问题超过 3 个则阻断；Major 级别问题超过 20 个触发人工复审。

4.2 代码覆盖率阈值

覆盖率门禁确保新增代码有足够的测试保护。推荐采用分层阈值策略，避免单一数字游戏。

覆盖类型	新增代码阈值	全量代码阈值	说明
行覆盖	≥ 85%	≥ 70%	核心业务模块要求更高
分支覆盖	≥ 75%	≥ 60%	条件分支必须覆盖 true/false
方法覆盖	≥ 90%	≥ 80%	新增方法必须被调用

避坑提示： 覆盖率门禁应基于 diff 增量计算，而非全量。全量覆盖率容易被历史低质量代码拉低，失去门禁意义。建议使用 diff-cover 或类似工具做增量覆盖报告。

4.3 代码规范检查

代码规范检查（Lint）保证代码风格一致、可读性强，降低维护成本。门禁规则包含：

格式规范： 缩进、换行、命名风格（PascalCase / camelCase / snake_case）
导入规范： 未使用导入、通配符导入、循环依赖
注释规范： 公共 API 必须包含 JSDoc / Docstring，禁止注释掉的代码
复杂度规范： 圈复杂度 ≤ 15，方法行数 ≤ 80

最佳实践： 将 Lint 规则集成到 IDE 保存动作和 pre-commit hook 中，在提交前自动修复格式问题，减少 CI 阶段的阻断率。

4.4 代码审查通过率

代码审查（Code Review）是人工质量门禁的最后一道关卡。通过率指标用于衡量审查效率与质量。

指标名称	计算公式	目标值
首次通过率	一次审查通过的 PR 数 / 总 PR 数	≥ 70%
平均审查轮次	总审查轮次 / 总 PR 数	≤ 2.5 轮
审查响应时间	从 PR 创建到首次审查的时间	≤ 4 小时
审查参与率	实际审查人数 / 应审查人数	≥ 80%

4.5 门禁规则配置示例

以下为 SonarQube + GitLab CI 的典型门禁配置片段：

# .gitlab-ci.yml 质量门禁阶段
quality-gate:
  stage: quality
  script:
    - sonar-scanner -Dsonar.qualitygate.wait=true
    - |
      # 增量覆盖率检查
      diff-cover coverage.xml --compare-branch=main \
        --fail-under=85
    - |
      # Lint 检查
      eslint src/ --max-warnings=20
  only:
    - merge_requests

  关键配置说明：
  sonar.qualitygate.wait=true — 等待 SonarQube 门禁结果，阻断 CI 流水线
diff-cover --fail-under=85 — 增量覆盖率低于 85% 则任务失败
eslint --max-warnings=20 — 警告数超过 20 则阻断

4.6 门禁规则与发布流程的衔接

代码质量门禁不是孤立检查点，而是发布流程的准入条件。建议将门禁结果写入发布工单，作为后续容量压测和上线审批的前置依赖。

门禁阶段	输出产物	下游依赖
静态扫描	扫描报告 + 门禁通过/阻断标记	触发覆盖率检查
覆盖率检查	增量覆盖率报告	触发规范检查
规范检查	Lint 报告 + 自动修复补丁	触发代码审查
代码审查	审查通过标记 + 审查评论	允许合并到发布分支

工程化建议： 将门禁结果通过 Webhook 推送到发布协调系统（如 Jira / 自研发布平台），实现质量门禁与发布流程的自动化联动，避免人工传递状态。