第7章 使用 zc.buildout 管理环境

为什么先要可重建

一个示例在作者机器上跑通了，能否证明它可维护？不能。同一份代码换一台干净机器可能就装不上、起不来，因为环境本身没被记录成可重放的输入。zc.buildout 想解决的就是这件事：把"我的环境"写成一份配置，让别人照着配置搭出一样的零件。

这章不教你把新项目搭在 buildout 上。原书出版于 Python 2.5 与早期工具生态，buildout 今天已不是新项目的默认选择。但它的思路——把环境拆成声明式部件、由配置驱动生成、能在干净机器上重放——仍然值钱。我们读它，是为了提取这些不变量，再用今天维护中的工具重写。

先做个预测：给定一段继承多层的 buildout 配置，你能不能指出最终解析后它实际从哪里装了什么？把答案写下，读完本章再回来对照。

zc.buildout 的哲学与配置结构

官方章节围绕 zc.buildout 哲学、配置结构与命令、recipe 机制、Atomisator 环境、发布与分发展开。原书出版于 Python 2.5 与早期敏捷工具生态，本章保留它解释"为什么"的结构；命令和安全默认按当前 Python、标准库与 PyPA 维护文档迁移，不把 EasyInstall、distutils 安装命令、旧 CI 或旧项目平台直接当成新项目默认。

buildout 把一个环境拆成一个个称为 声明式 part 的部件，每个 part 对应一个由 recipe 生成的产物。[buildout] 节定义 parts、下载源和版本，其他节配置具体 recipe；配置继承会增强复用，也会隐藏来源，验收时要输出最终解析配置。先写出公共行为和失败类型，再选择语法或工具——即使实现从原书工具迁到当前生态，调用者仍能依据相同契约判断结果。

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

[buildout]
parts = app
versions = versions
 
[app]
recipe = zc.recipe.egg
eggs = atomisator

[buildout]      总装节 —— 声明要哪些 part、版本从哪来
parts = app     part 列表 —— 每项对应一个由 recipe 生成的产物
[app]           part 节 —— 声明这个部件用哪个 recipe、装哪些 egg
recipe = ...    recipe —— 把这段配置翻译成实际安装的执行单元
eggs = ...      输入 —— 指定要装入隔离环境的包

下面这张交互图把本章四个核心概念串成一条流水线。点击节点查看说明，打开"注入常见故障"可看到每个环节的典型失败模式。

承接概念图，下面逐项展开：recipe 如何把配置变成产物、又为什么必须幂等，以及失败边界在哪里。

recipe 机制与失败边界

recipe 把配置转换为文件、脚本或服务定义，必须声明输入并实现称为 幂等更新 与卸载；任意网络下载会破坏可复现和供应链审计。先写出公共行为和失败类型，再选择语法或工具——这样即使实现从原书工具迁到当前生态，调用者仍能依据相同契约判断结果。

案例把应用包、数据库和入口脚本装配成一套环境；现代迁移可用锁定依赖、容器或部署清单重建，但仍需保持组件边界。边界实验至少包含正常、空输入、上限附近、依赖失败和重复执行。涉及网络、并发或外部制品时，再加入超时、取消、部分完成与摘要校验。

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

现代迁移与证据闭环

把"我的环境"从 buildout 配置迁到今天的工具，不变量是同一组：声明式配置、隔离环境、持续反馈、可回滚发布。pyproject 声明运行依赖与开发依赖的边界，lock 锁定精确版本，容器或部署清单负责整体重放——形式变了，"能在干净机器上重放出同一环境"这件事没变。

[project]
name = "atomisator"
dependencies = ["sqlalchemy>=2"]
 
[dependency-groups]
test = ["pytest"]

[project]            运行依赖 —— 应用对外公开要装什么
name                 包名 —— 安装与入口解析的身份
dependencies         版本下限 —— 声明能跑的最低要求，不是锁死
[dependency-groups]  开发依赖 —— 与运行依赖分开，不进生产制品
test = ["pytest"]    分组 —— 可按场景安装，避免污染默认环境

锁定之后还要校验供应链。--require-hashes 按摘要安装防偷换，pip check 发现已装包之间的冲突，入口检查确认配置与启动条件齐全：

python -m pip install --require-hashes -r requirements.lock
python -m pip check
python -m atomisator --check-config

--require-hashes     摘要校验 —— 每个包按哈希安装，防偷换
requirements.lock    锁定文件 —— 记录精确版本，可复现安装
pip check            一致性 —— 发现已装包之间的依赖冲突
--check-config       入口检查 —— 验证配置、依赖锁与启动条件齐全

证据闭环负责收束验收。发布配置把开发依赖与生产依赖分开，并从版本化输入构建；秘密不进入配置模板，制品摘要和回滚版本必须可查。保存解释器、依赖锁定、输入、命令、退出状态、关键输出和制品摘要，才能让另一台干净机器重放出同一结论。这就是 可重建性：凭记录的输入与证据，换台干净机器照样搭出一样的环境——它是 buildout 哲学在今天依然值钱的那条主线。

实战验收清单

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

迁移决策题

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

常见误区

误区 1

现象 → 新项目直接套用 buildout，装环境时踩到旧依赖与无人维护的 recipe 原因 → 把历史工具当新项目默认，没有迁移到 pip + pyproject 修法 → 新项目用 pyproject 声明依赖、venv 隔离、lock 锁定；buildout 留给历史项目渐进迁移

误区 2

现象 → 改了一处配置，产物却来自别处，排查不知道源头 原因 → 多层配置继承覆盖了来源，没有输出最终解析结果 修法 → 验收时输出 buildout annotate 或等价的最终解析配置，让每个 part 的来源可追

误区 3

现象 → 重复运行 buildout 报错或留下多余文件，越跑越乱 原因 → recipe 不幂等，没声明输入也没实现干净的更新与卸载 修法 → recipe 声明输入、实现幂等更新与卸载，重复执行结果一致

误区 4

现象 → 迁移到新工具后环境更乱，部署仍起不来 原因 → 机械替换命令却保留了隐式环境与不可追踪副作用 修法 → 先提取声明式配置、隔离、持续反馈与可回滚发布等不变量，再用维护中的接口重写

本章回顾

本章逐项覆盖zc.buildout哲学、配置结构与命令、recipe机制、Atomisator环境、发布与分发。方法是用可读接口表达责任，用边界测试证明失败语义，再以可重建环境和制品证据完成闭环。

小结

• buildout 把环境拆成声明式 part，recipe 负责生成结果
• 配置继承增强复用也会隐藏来源，验收要输出最终解析配置
• recipe 必须声明输入、实现幂等更新与卸载
• 现代迁移用锁定依赖、容器或部署清单重建环境
• 开发依赖与生产依赖分开，秘密不进配置模板

练习与验收

名词解释