implementation-design-patterns-python

Python 设计模式最佳实践（Refactoring Guru）

为 Python（3.10+）惯用现代写法中的 22 种四人帮设计模式提供实现参考，内容整理自 refactoring.guru。3 个类别中的 22 个模式文件均介绍了意图、问题、解决方案、适用场景（包括何时使用和何时不使用）、带输出的可运行 Python 示例、实现步骤、优缺点，以及与相关模式的关系。

这是 TypeScript 设计模式技能的 Python 优先配套内容。在 Python 中，大多数 GoF 模式都可以简化为一种语言特性：函数、生成器、数据类、functools.singledispatch 或 match 语句。每个条目都以这种惯用写法开篇，只有在身份、存储状态、运行时注册或多态分派确实有用时，才保留基于类的 GoF 结构。

这些模式是用于结构性决策的词汇表，而非规定。只有在适用条件符合时才使用模式；每个条目都包含 何时不使用一节，以避免过度设计——在 Python 中，这才是使用这份目录时更常见的问题。

何时应用

• 构造函数已增长到 10 个或更多参数（伸缩构造函数异味），或者子类的存在只是为了固化参数组合
• 方法根据 kind/type/mode/status 分支来选择算法或行为——随着每个变体增加，match 或 if/elif 分支也越来越长
• 集成方法名称与代码不匹配的第三方 API、库或旧式类
• 为树形领域建模（文件系统、AST、UI 树、组织结构图），其中叶节点和分支必须以统一方式处理
• 在运行时添加横切行为（日志记录、缓存、访问控制、压缩），而不使用子类
• 根据配置、用户输入或环境在运行时选择算法或行为变体
• 实现撤销/重做、历史快照、事务回滚，或操作的排队/调度
• 协调许多对象，而它们之间直接相互引用已变得错综复杂——由一个中介来协调通信
• 在发生变化时通知多个订阅者——事件系统、响应式数据流
• 审查那些隐含了模式的代码（庞大的 if isinstance(...)、并行类层次结构、复制粘贴的算法骨架）——明确使用模式，或将其简化为 Python 惯用写法

规则类别

#	类别	影响	模式数	适用场景
1	创建型	高	5	对象构造并不简单、因配置而异，或可能导致与具体类紧耦合
2	结构型	高	7	将类/对象组合成更大的结构，同时保持各部分可相互替换
3	行为型	高	10	分配职责并定义对象在运行时如何协作

使用方法

1. 识别模式。 阅读下方的 快速参考，找出意图与问题相符的模式。大多数符合模式的问题都与其中列出的描述相似。
2. 阅读模式参考。 打开 references/{category}-{pattern}.md。确认意图，然后在采用前阅读 适用场景和何时不使用。
3. 优先采用惯用写法。 每个“正确”示例都会先展示 Pythonic 写法。除非你需要 替代方案部分中的基于类的结构，否则请采用这种写法。
4. 适配你的领域。 示例使用小型且贴近实际的领域（传输方式、路线规划器、文档树）。合并前，请将名称改为符合你领域的术语。
5. 查看相关模式。 每个条目最后都有 相关模式，列出值得为同一问题考虑的相近模式。

快速参考

1. 创建型模式（对象实例化）

• creational-factory-method — 通过注册表／分发字典解析具体类。“我想通过配置／字符串键选择类，而不想写一长串 if/elif。” — 高
• creational-abstract-factory — 创建必须相互匹配的相关对象系列。“切换一个标志就必须替换一整套相互配合的对象（按钮 + 复选框）。” — 中高
• creational-builder — 分步构建复杂对象；在 Python 中，优先考虑仅限关键字参数的数据类。“我的构造函数有 10 个以上参数，或者我需要分阶段组装对象。” — 高
• creational-prototype — 使用 copy.deepcopy / dataclasses.replace 克隆对象。“我需要一个与这个对象相似、但有一个值不同的对象。” — 中
• creational-singleton — 通过模块全局变量或 functools.cache 共享唯一实例。“我需要且只需要一个配置／注册表／池，同时还要便于测试。” — 中

2. 结构型模式（组合）

• structural-adapter — 包装一个类，使其接口符合调用方的预期。“这个库的方法名和我的不一致，而且我无法修改它。” — 高
• structural-bridge — 通过组合 + Protocol 将抽象与实现分离。“有两个彼此独立的维度，子类数量正在激增。” — 中
• structural-composite — 通过共享的 Protocol + 递归，以统一方式处理叶节点和树。“我有一棵树，想用同一个接口处理项目和组。” — 高
• structural-decorator — 叠加包装器（或使用 @decorator），在运行时添加行为。“我想按任意顺序叠加日志记录 + 缓存 + 压缩。” — 高
• structural-facade — 在复杂子系统之上提供单个函数／模块。“我只想用 convert(file, fmt)，不想处理编解码器／比特率那一堆复杂操作。” — 高
• structural-flyweight — 通过缓存工厂 + __slots__ 共享不可变状态。“有数百万个对象，但只有少数几种不同的负载——内存不够用了。” — 低中
• structural-proxy — 通过 __getattr__ / cached_property 代理对象，以控制访问。“我需要延迟加载／身份验证／缓存，但不想动真正的对象。” — 中高

3. 行为模式（协作）

• behavioral-chain-of-responsibility — 按顺序将请求传递给一系列处理器。 “我想调整身份验证、验证和授权检查组成的处理流水线。” — MEDIUM-HIGH
• behavioral-command — 将请求封装为可调用对象或闭包，并可选择支持撤销。 “我需要撤销/重做、排队，或在多个 UI 界面中共享同一操作。” — HIGH
• behavioral-iterator — 通过 __iter__/生成器遍历，而不暴露内部实现。 “我希望 for x in my_structure 能直接运行。” — HIGH
• behavioral-mediator — 通过一个中心协调组件间的交互。 “我的小部件彼此引用，导致没有任何东西可以复用。” — MEDIUM
• behavioral-memento — 通过冻结的数据类快照/恢复状态。 “我需要撤销/回滚，但不想暴露私有字段。” — LOW-MEDIUM
• behavioral-observer — 状态变化时通知订阅者回调（通常使用 property setter）。 “一个值变化时，许多对象都必须做出响应——例如事件、响应式 UI。” — CRITICAL
• behavioral-state — 委托给多态状态对象（或枚举加分发逻辑）。 “我的类是一个状态机，每个方法里都有 if status ==。” — MEDIUM-HIGH
• behavioral-strategy — 将算法作为 Callable 传入，并在运行时切换。 “我想在不使用条件语句的情况下选择多种算法（排序/路由/支付）。” — HIGH
• behavioral-template-method — 在 ABC 中固定算法骨架，由子类重写各个步骤。 “多个类共享一种算法，但其中有几个步骤各不相同。” — MEDIUM
• behavioral-visitor — 通过 functools.singledispatch / match 添加操作。 “我需要对 AST 执行 5 种操作，但不想修改节点类。” — LOW-MEDIUM

如何在相似模式之间做出选择

有些模式形态相似，但解决的问题不同。阅读每种模式的 相关模式 部分，然后参考以下区别：

• 适配器 vs. 外观 vs. 代理 vs. 装饰器——这四种模式都会包装一个目标。适配器 会更改接口。外观 会简化子系统。代理 保留接口并控制访问权限和生命周期。装饰器 保留接口并递归地添加行为。
• 策略 vs. 状态——两者都会将工作委托给一个可替换的对象。策略 的各个变体是由调用方选择的独立函数。状态 对象彼此了解，并会在上下文中触发转换。
• 策略 vs. 模板方法——两者都会改变算法的部分内容。策略 使用组合——在运行时替换 Callable。模板方法 使用继承——在定义时固定 ABC 骨架。
• 工厂方法 vs. 抽象工厂 vs. 生成器——工厂方法 用于确定一个产品（注册表/@classmethod）。抽象工厂 返回一组相匹配的产品。生成器 用于组装一个复杂产品（仅限关键字参数的数据类，或用于分阶段构建的流式生成器）。
• 组合 vs. 装饰器——两者都会递归地包装子项。组合 会聚合子项的结果。装饰器 会添加一项职责并传递结果。
• 责任链 vs. 命令 vs. 中介者 vs. 观察者——它们都会连接发送方和接收方。责任链 会将请求沿处理程序列表传递（也可以提前停止）。命令 会将请求变为一等可调用对象。中介者 会集中管理多对多通信。观察者 会建立一对多的发布者到订阅者通知机制。
• 访问者：singledispatch vs. match vs. 方法——如果要在不修改类的情况下，为一组封闭类型添加操作，请使用 functools.singledispatch；如果希望将所有情况放在一个完备的函数中，请使用 match；如果只有一种操作且类型集合较小，请使用普通方法。

参考资料

1. Refactoring Guru — 设计模式目录
2. Refactoring Guru — Python 示例
3. Refactoring Guru — 创建型模式
4. Refactoring Guru — 结构型模式
5. Refactoring Guru — 行为型模式