第8章 管理代码与持续集成

为什么"我的电脑能跑"还不能算数

一段代码在自己电脑上跑通了，能不能就算做好了？还不够。换一台没装过这套东西的电脑，它很可能就跑不起来：缺了对应的运行环境，漏掉那次悄悄改过的配置，谁也说不清它当时为什么能跑通。

真正能交出去的代码，要做到换任何人、换任何一台干净的机器，按同样的步骤走一遍，都能得到同样的结果。这就要求每次改动都留下一串清楚的痕迹：改了什么、在什么环境里搭起来、做了哪些检查、最后得到什么。

本章就把"靠人手动记住"升级成"靠流程自动留痕"：每次改动都自动记下来，在干净环境里重新搭起来跑一遍，再把结果存成证据。任何一处改动都能追到源头，也能被另一台干净的机器完整复现。

原书骨架与现代迁移

官方章节围绕版本控制模型、Mercurial工作流、持续集成原则、Buildbot流水线、代码管理证据展开。原书出版于Python 2.5与早期敏捷工具生态，本章保留它解释"为什么"的结构；命令和安全默认按当前Python、标准库与PyPA维护文档迁移，不把EasyInstall、distutils安装命令、旧CI或旧项目平台直接当成新项目默认。

承接前两项，把局部语法或工具放回应用数据流。阅读时沿输入、协议、状态、输出和证据追踪，避免只背API名称。

把"一提交一变更"用命令固化下来，下面两种视角对比同一段提交工作流：

git switch -c feature/parser-timeout
git add src tests
git commit -m "Handle parser timeout"
git show --stat --oneline HEAD

switch -c    新建分支隔离这条变更，不直接写主历史
add/commit   暂存并提交一个完整变更，消息说清改了什么
show --stat  复查本次提交动了哪些文件，确认粒度可单独回滚

机制一：责任与数据流

集中式与分布式系统对历史、离线提交和协作拓扑取舍不同；无论工具如何，提交应是原子提交、可评审，并把构建制品与秘密排除在源码历史之外。 原书用 Mercurial、hgwebdir 和 Apache 展示托管、授权与客户端协作；迁移到 Git 平台时仍要保留受保护分支、身份、审查和最小写权限。 先写出公共行为和失败类型，再选择语法或工具。这样即使实现从原书工具迁到当前生态，调用者仍能依据相同契约判断结果。

提醒我们：抽象不能消除成本，只会改变成本出现的位置。包装、生成器、构建系统、CI或缓存都必须说明资源、顺序和异常传播。

CI 步骤要在干净环境从依赖锁定重建，下面两种视角对比同一段流水线配置：

steps:
  - run: python -m pip install .
  - run: python -m unittest discover -s tests
  - run: python -m build
timeout-minutes: 15

install      从依赖锁定安装，不靠开发机缓存
discover     跑全部测试，失败即终止流水线
build        产出可分发制品，留摘要备查
timeout      防止单步挂死拖垮整条流水线

机制二：失败与边界

版本控制之后，改动进入持续集成：每次变更在干净环境自动构建、测试并报告，失败阻断合并；CI 不能依赖开发机缓存，也不能让外部服务偶发失败被当作成功。 Buildbot 把代码变更触发到 worker 步骤和结果；现代 CI 语法可以不同，但触发、矩阵、超时、日志、制品和取消语义必须明确。 边界实验至少包含正常、空输入、上限附近、依赖失败和重复执行。涉及网络、并发或外部制品时，再加入超时、取消、部分完成与摘要校验。

历史工具不等于无价值。正确迁移是先提取声明式配置、隔离、持续反馈和可回滚发布等不变量，再用维护中的接口重写；错误做法是机械替换命令却保留隐式环境和不可追踪副作用。

把一次构建的关键证据固化为不可变结构，下面两种视角对比同一段证据建模：

from dataclasses import dataclass
 
@dataclass(frozen=True)
class BuildEvidence:
    commit: str
    python: str
    artifact_sha256: str

commit          指向触发本次构建的源码版本
python          记录解释器实现与版本，排除运行时歧义
artifact_sha256 制品内容摘要，证明"发布了什么"

机制三：证据闭环

本节负责收束验收。一次合并应能追到一条证据链：提交、审查、测试运行、环境和制品摘要；只保留绿色徽章无法重放失败或证明发布内容。 保存解释器、依赖锁定、输入、命令、退出状态、关键输出和制品摘要，才能让另一台干净机器重放同一结论。

实战验收清单

1. 在隔离环境运行三段示例，记录解释器实现、版本和依赖来源。
2. 为核心行为增加正常、空输入、失败和重复执行测试，先看到失败再修改实现。
3. 清理缓存和临时文件后重跑，证明结果不依赖工作区残留。
4. 对历史命令写出当前替代路径，并说明保留的架构不变量与不再采用的安全默认。

迁移决策题

设想团队正在维护一个已经运行多年的Python服务：它仍依赖本章对应的历史工具，但业务不能停机。先不要直接重写。第一步列出版本控制模型承担的真实输入和输出，再用Mercurial工作流识别构建或运行时依赖；第二步把持续集成原则放进隔离实验，证明当前行为与失败类型；第三步用Buildbot流水线设计兼容层，让旧入口和新入口在同一组契约测试下运行；最后以代码管理证据保存制品摘要、性能或行为差异与回滚条件。只有新路径在正常、边界和故障输入上都达到既定条件，才逐步切换流量或调用者。这样迁移的是可验证契约，而不是把一个旧命令盲目替换为一个新命令。

常见误区

误区 1

现象 → 一次提交塞了功能、重构和配置改动，出问题想回滚却无法只回滚那一处 原因 → 提交不原子，多个变更耦合在同一个历史节点 修法 → 一提交一变更，写清提交消息，让每次提交能单独评审和回滚

误区 2

现象 → 本地跑测试全绿，CI 一跑就挂 原因 → CI 偷用了开发机的隐式状态（缓存、本地依赖、未提交的文件） 修法 → CI 每次在干净环境从依赖锁定重建，不依赖工作区残留

误区 3

现象 → 合并后线上还是出问题，却无法复现当时构建了什么 原因 → 只留了"通过/不通过"，没存环境、命令、退出状态和制品摘要 修法 → 保存解释器、依赖锁定、命令、退出状态和制品摘要，让干净机器能重放

误区 4

现象 → 把 Mercurial 命令换成 Git、把 Buildbot 换成新 CI，迁移后反而更乱 原因 → 只换了命令名，保留了隐式环境和不可追踪副作用，没提取不变量 修法 → 先提取声明式配置、隔离、持续反馈、可回滚等不变量，再用维护中的接口重写

本章回顾

本章逐项覆盖版本控制模型、Mercurial工作流、持续集成原则、Buildbot流水线、代码管理证据。方法是用可读接口表达责任，用边界测试证明失败语义，再以可重建环境和制品证据完成闭环。

小结

• 提交应原子、可评审，生成制品与秘密排除在源码历史之外
• 迁移到 Git 平台仍要保留受保护分支、审查与最小写权限
• CI 每次变更在干净环境自动构建测试，失败阻断合并
• CI 语义须明确：触发、矩阵、超时、日志、制品和取消
• 一次合并能追到提交、审查、测试运行、环境和制品摘要

练习与验收

名词解释