6.1 版本控制：行车记录与编组台账

6.1 版本控制：行车记录与编组台账

机务段从地基逛起。版本控制常被初学者理解成"存代码的网盘"，这是把它看小了——它是全项目的行车记录仪（谁在何时改了什么、为什么改）、多线并行的编组系统（几个特性同时开工互不干扰）、以及出事后唯一可靠的回退凭据。本节讲它的三重角色、提交纪律，以及两种编组策略的选择题。

行车记录本的三重角色

**第一重：变更台账。**每次提交都是一条带作者、时间、说明的记录，配上标签与分支，任何版本任何时点都可复原。出事故时，"昨晚改了什么"这个问题靠台账三分钟回答，靠回忆三天也答不清。云梯上线夜那次缓存键冲突，正是靠提交记录十分钟锁定嫌疑变更——没有台账，那次回滚之后团队要在黑暗里再撞一次。

**第二重：编组系统。**多人同时开发，分支让各人各挂各的车厢，合并（merge）是挂接动作。分支策略后面单讲，先记一条铁律：分支是暂时的编组状态，不是永久的档案柜——挂出去越久，合并时撞得越狠。

**第三重：协作接口。**提交请求（合并请求）是代码走查（第 3.3 节）的物理载体：改动、上下文、评审意见、流水线结果聚合在一处。走查文化的落地，一半靠这里。

日常操作在命令行的样子，值得亲手敲一遍建立手感：

git 会话 · 云梯开发一日
  git pull --rebase          # 出工先同步，减少分叉
  git checkout -b fix-share-precision
                             # 修分摊精度，开短命分支
  ... 改代码、补单元测试 ...
  git add 计费分摊模块
  git commit -m "修复满减叠加的分摊尾差：改用逐仓累计法
                 （复核 REQ-ACC-014 验收标准 A2）"
                             # 说明写"为什么"，不只写"改了什么"
  git push -u origin fix-share-precision
  ... 发起合并请求，走查通过后合入主干 ...

提交说明三规范：
  1）一句主题行说清改动的目的；
  2）正文交代背景或关联的需求编号；
  3）一次提交只干一件事——混装的车厢查事故最费劲。
​

两种编组策略：主干直达与短分支

分支怎么开，业内收敛成两种流派，选择取决于集成能力：

• 短分支流派：主干保持随时可发布，每人每天从主干开小分支，改动控制在数日内合并回来。分支越多越短越好，配合强制走查与流水线门禁；
• 主干直达流派：不开功能分支，人人直接提交主干，未完成的功能用"特性开关"隐藏。集成频率最高，但要求自动化测试托底、开关有清理机制。

图 6-1：两种编组策略的时间线对比

选错流派的标志症状：合并请求常年挂着数百行改动、合并冲突动辄半天、"发布分支"与主干漂移到需要专人缝合。这些都指向同一个病根——分支寿命过长。

顺带一提：机务段的驾驶室

开发者天天住的集成开发环境（IDE）也归机务段管，但它的定位是驾驶室而非发动机：代码补全、重构助手、调试器、插件化的静态检查，都在替人省机械劳动。值得记住的一条原则：IDE 能自动做的（格式化、导入整理）就别写进团队规范让人肉执行，规范里只留机器做不了的判断。

版本号：给每班车编号

提交历史之上，发布版本需要一个可沟通的编号体系。语义化版本是行业通行的方案：版本号三段式——主版本号、次版本号、修订号，分别对应"不兼容的接口变更""向后兼容的新功能""缺陷修复"。它的价值在于让依赖方"看号识变"：见到主版本号跳动，就知道升级要做适配评估；见到只是修订号变化，可以放心自动升级。云梯的制品库因此规定：流水线产出的每个制品必须带语义化版本与提交哈希，"latest"这种模糊标签禁止进入生产——版本可沟通，回滚才有精确目标，"回到上一个好的版本"才不会变成猜谜。

回滚的两种手法：倒车与掉头

版本控制给了回滚两种姿势，选错会自找麻烦。**revert（掉头）**是新增一笔提交抵消错误变更，历史完整保留，适合已推送到共享分支的错误；**reset（倒车）**是抹掉历史重新来过，只适合尚未分享的本地提交。原则一句话：凡是别人可能已经拉取过的历史，永远用掉头不用倒车——倒车会让协作者的本地历史与你分叉，冲突层层叠叠。云梯的事故响应手册把这条写死：生产回滚一律走 revert 或重新部署上一个制品，禁止任何改写历史分支的操作。历史的价值恰恰在于它不可篡改——行车记录仪要是能剪辑，就不再是记录仪了。

从一次事故看台账的价值

台账的价值用一次真实事故讲最清楚。云梯某次发布后发现对账金额偶发差一分钱，无规律、难复现。排查第一动作是按发布版本锁定变更区间——该版本包含九笔提交，其中三笔触碰过金额计算路径；逐笔复查后十分钟锁定嫌疑：一笔"顺手重构"把四舍五入的调用位置从汇总后挪到了汇总前。若没有版本与提交记录，这次排查的起点只能是"通读全部计费代码"。这次事故后团队新增一条规矩：触碰金额计算的提交，说明文字必须注明影响范围——台账不只是被动记录，主动写好台账，是给未来的自己留救援绳。

两个高频疑问

问：合并冲突太频繁，是不是流程有问题？ 先定位冲突的层次。技术层——多人常改同一文件的同一段，多半是模块边界没画好（回看第 3.2 节按变化原因切分）；节奏层——分支寿命过长导致基线漂移，用缩短分支寿命解决；语义层——文件不冲突但逻辑冲突（两个分支各加了一个含义相反的配置），这类最危险，靠小步合入与自动化测试兜底。三种层次三种药，一味怪"流程太麻烦"通常治不了任何一种。

问：二进制文件、配置、数据库脚本要不要进版本控制？ 都要，但方式分家。二进制制品走制品库并在提交记录里存哈希引用；环境配置走代码化（基础设施即代码），敏感密钥进保管系统只存引用；数据库迁移脚本必须入库且只增不改——已执行过的脚本被修改，等于篡改了数据库的历史。原则统一：版本控制管一切"影响系统状态的东西"，不管的是废纸。

本节要点回顾

• 版本控制三重角色：变更台账、编组系统、协作接口；事故定位与回退全靠它。
• 提交说明三规范：主题行讲目的、正文讲背景、一次提交一件事。
• 编组两流派：短分支靠频繁合并与门禁，主干直达靠全自动测试与特性开关。
• 选择判据是集成验证的速度与可信度，测试慢就别学主干直达。
• 分支寿命与合并痛苦成正比，长命分支是合并大爆炸的温床。
• IDE 是驾驶室：机器能代劳的规范，别消耗人的纪律。

地基夯实，下一节在地基上修流水线——让集成从期末考试变成每日打卡。