📚 课程目录第1章课程导入与治理体系总览

1. 课程导入与治理体系总览

在多数研发团队里，“代码质量”最初往往被理解为一次代码评审、一次静态扫描，或者某位资深工程师的个人习惯。但当团队规模扩大到几十人、上百人，仓库数量从几个增长到几百个，分支策略、合并请求（Merge Request，MR）、流水线、制品与发布彼此交织时，代码质量就不再是个人行为，而是一套需要被设计、被度量、被持续执行的治理体系。本课程要解决的，正是如何以 GitLab 为承载平台，把零散的质量动作组织成可落地、可审计、可演进的企业级治理能力。

一、企业代码质量治理的核心目标

企业代码质量治理不是追求“零缺陷”这种无法验证的口号，而是围绕四个可度量的目标展开：一致性、可追溯性、风险前置与持续改进。

一致性指不同团队、不同仓库遵循同一套质量基线。例如统一要求所有 MR 必须通过单元测试、静态扫描和至少一名评审人，避免“A 项目很严、B 项目裸奔”。可追溯性指每一次代码变更都能回答三个问题：谁改的、为什么改、经过了哪些质量门禁。GitLab 的提交历史、MR 讨论、流水线记录和制品版本天然构成这条证据链。风险前置是把缺陷发现点从生产环境前移到编码和评审阶段，缺陷发现得越晚，修复成本越高，业界经验通常认为生产阶段修复成本是编码阶段的数十倍。持续改进则要求治理指标本身被观测，例如 MR 平均评审时长、流水线失败率、缺陷逃逸率，用数据驱动规则调整，而不是一次性制定规则后长期不变。

治理的反面不是“没有规则”，而是“规则只写在文档里、不进入流水线”。凡是不能自动阻断或自动记录的规则，在规模化团队中几乎必然失效。

二、GitLab 在治理体系中的定位

GitLab 的价值在于它把代码托管、评审、CI/CD、制品、安全扫描和度量放在同一个数据模型下。这意味着质量治理不需要在多个系统之间拼接数据：一次 MR 触发的流水线，其扫描结果、测试覆盖率、审批记录都挂在同一个 MR 对象上，可以直接作为合并门禁的判断依据。

从治理视角看，GitLab 提供四层可编程的控制面：仓库层（分支保护、推送规则、CODEOWNERS）、评审层（MR 审批规则、合并检查）、流水线层（.gitlab-ci.yml 中的作业与规则）、平台层（群组级策略、合规框架、审计事件）。治理体系就是在这四层上逐级施加约束，越靠前的层成本越低、越靠后的层覆盖越广。

三、课程整体学习路径

本课程共 30 章，按“认知—建设—深化—运营”的节奏推进，而不是把功能点平铺罗列。

第一阶段（第 1～6 章）建立认知与基线。从治理目标与 GitLab 定位出发，梳理分支模型、MR 流程、提交规范，形成最小可用的质量基线。这一阶段的关键产出是一份团队可执行的分支与评审约定。

第二阶段（第 7～16 章）建设自动化门禁。围绕 CI/CD 展开：流水线结构设计、单元测试与覆盖率采集、静态代码扫描、依赖漏洞与密钥检测、制品与版本管理。重点不是“会写 yml”，而是理解每个作业在什么条件下阻断合并、失败后如何定位。

第三阶段（第 17～24 章）深化治理能力。进入多项目、多团队的规模化场景：群组级策略、合规框架、CODEOWNERS 与审批矩阵、质量度量看板、缺陷逃逸分析。这一阶段回答“如何让一百个仓库遵守同一套规则”。

第四阶段（第 25～30 章）运营与演进。把治理当作持续运营的产品：指标观测、规则调优、例外管理、治理复盘，最终形成可自我迭代的质量治理闭环。

四、实战项目说明

课程贯穿一个实战项目：为一个名为 payment-service 的示例服务建立完整治理链路。该项目初始状态是“能跑但无门禁”——主干可直接推送、无测试、无扫描。随着章节推进，我们逐步为它加上分支保护、MR 审批、单元测试与覆盖率门禁、静态扫描、依赖检测，并最终接入群组级策略与度量看板。

示例中会使用一组明确标注为教学假设的参数，例如：覆盖率门禁设为行覆盖率不低于 70%、新增代码覆盖率不低于 80%；静态扫描阻断级别设为 high 及以上；MR 至少需要 1 名 CODEOWNERS 审批且所有讨论已解决。这些数值是示例基线，实际团队应根据自身风险承受度调整，而不是照搬。

# 示例：payment-service 的合并门禁判断逻辑（教学假设）
merge_allowed =
    分支保护已启用
    AND MR 审批数 >= 1（含 CODEOWNERS）
    AND 所有讨论已解决
    AND 流水线 test 作业通过
    AND 行覆盖率 >= 70%
    AND 新增代码覆盖率 >= 80%
    AND 静态扫描无 high/critical 问题
    AND 依赖扫描无已知高危漏洞

判断结果如何观察？在 GitLab MR 页面中，门禁状态集中体现在合并按钮区域：满足条件时按钮可点击，不满足时按钮置灰并给出未通过项。流水线失败时，点击失败作业可查看日志定位具体原因，例如覆盖率未达标会输出实际值与阈值对比。这套“规则—执行—反馈—修正”的循环，正是后续每一章都会反复实践的基本单元。

学习本课程时，建议同步在自己的 GitLab 项目中操作：每学完一个治理点，就把它真正加到流水线或仓库设置里，并故意制造一次失败，观察门禁如何阻断、日志如何提示。只有亲手触发过失败，才算真正理解治理规则。

最后需要明确：治理体系的目标不是增加流程负担，而是让高质量成为默认路径。当规则被自动化承载、被数据观测、被团队共同维护时，代码质量才从“靠人盯”转变为“靠体系跑”。接下来的章节，我们将从最基础的分支与评审约定开始，一步步把这条链路搭起来。