全书导览

为什么先画一张地图

第一次走进一栋大楼，你会先要一张楼层平面图，再开始挨个开门。这本书覆盖的面很宽，所以我们也先画出整张布局：每一组章节是做什么的，它们之间怎么连起来。有了地图，后面每停一站，你都知道这一站在整本书里的位置。

开门之前，我们先写下预期看到什么——给什么、该出什么、会在哪里坏——然后才去运行。结果和预期不一样，我们先修自己脑子里的模型，而不是急着截一张"跑通了"的图当成结论。

一次在自己机器上跑通，能证明的东西很少。我们要留下足够的痕迹，让别人在一台干净的机器上能把同一个结论重新走一遍。这张地图因此也是一张清单：每一站必须留下什么，才算真正走过。

原书骨架与现代迁移

官方章节围绕语言与API、包与应用、项目生命周期、性能与设计、历史工具迁移展开。原书出版于 Python 2.5 与早期敏捷工具生态，本章保留它解释"为什么"的结构；命令和安全默认按当前 Python、标准库与 PyPA 维护文档迁移，不把 EasyInstall、distutils 安装命令、旧 CI 或旧项目平台直接当成新项目默认。

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

1-4 语言与API -> 5-7 包与应用
       -> 8-11 生命周期 -> 12-14 性能与设计

下面的交互把五条主线点成可点击的节点，每个节点附一个常见失败和修法，先在地图上把全书走一遍。

机制一：责任与数据流

第1至4章从环境、函数级语法、类级机制推进到命名与公共 API。第5至7章把包、Atomisator 应用和 zc.buildout 连接成可分发系统。先写出公共行为和失败类型，再选择语法或工具。这样即使实现从原书工具迁到当前生态，调用者仍能依据相同的公共契约判断结果。

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

python -m venv .venv
python -m unittest discover -s tests
python -m build

机制二：失败与边界

第8至11章覆盖版本控制、迭代生命周期、文档与测试驱动开发。第12至14章先测量瓶颈，再选择算法、并发、缓存和 Python 化模式。一次边界实验至少包含正常、空输入、上限附近、依赖失败和重复执行。涉及网络、并发或外部制品时，再加入超时、取消、部分完成与摘要校验。先看到失败再修改实现，以证明其失败语义。

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

def evidence(stage, **facts):
    print({"stage": stage, **facts})

机制三：证据闭环

以证据闭环负责收束验收。原书基于 Python 2.5 时代生态；保留 why 和架构边界，按当前 Python 与 PyPA 文档替换 how。保存解释器、依赖锁定、输入、命令、退出状态、关键输出和制品摘要，才能让另一台干净机器重放同一结论。

实战验收清单

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

迁移决策题

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

常见误区

误区 1：运行成功等于可维护

一个示例在作者机器上跑通，并不证明它可维护。还要明确解释器与依赖、输入边界、失败路径、可观察结果和重建步骤。把"我这里能跑"当成结论，等于把验证责任转嫁给下一位读者。

误区 2：把历史工具当成新项目默认

原书成书于 Python 2.5 与早期工具生态。EasyInstall、distutils 安装命令、旧 CI 和旧项目平台可以解释历史，但不能直接写进新项目。正确迁移是提取不变量后用维护中的接口重写。

误区 3：机械替换命令却保留隐式环境

只把旧命令换成新命令，却留下隐式环境变量、全局缓存和不可追踪副作用，迁移后只会更难复现。先固定干净环境，再重写命令与配置。

误区 4：抽象消除成本

包装、生成器、构建系统、CI 或缓存都不会消除成本，只会改变它出现的位置。每层抽象都必须说明资源、顺序和异常传播，否则成本会以更难定位的方式回来。

小结

• 全书五条主线：语言 API、包应用、生命周期、性能设计、工具迁移
• 先写公共契约与失败类型，再选语法或工具
• 抽象不消除成本，只改变成本出现的位置
• 边界实验覆盖正常、空输入、上限、依赖失败与重复执行
• 历史工具迁移保留不变量，用维护中接口重写

练习

本章回顾

本章逐项覆盖语言与 API、包与应用、项目生命周期、性能与设计、历史工具迁移。方法是用可读接口表达责任，用边界测试证明失败语义，再以可重建环境和制品证据完成闭环。

名词解释