Pythonic Design Patterns

一个完整的、教学导向的Python设计模式代码仓库，涵盖17种常用GoF设计模式，每个模式都配备详细注释、实际应用示例和完整文档。

✨ 特色亮点

• 🐍 Pythonic实现: 充分利用Python语言特性（装饰器、元类、上下文管理器、Protocol等）
• 📚 详细文档: 每个模式都有完整的中文文档，包含现实世界类比和UML类图
• 💡 实战导向: 提供真实业务场景示例，而非玩具代码
• 🎯 模式选择指南: 帮助你根据场景选择合适的设计模式
• ⚠️ 反模式警告: 明确指出常见误用和Python特有陷阱
• 🎓 学习路径: 提供从初级到高级的渐进式学习路线
• 🚀 生产级质量: 遵循PEP 8规范，包含完整类型注解

📖 设计模式速查表

创建型模式 (Creational Patterns) - 5个

模式	意图	复杂度	使用频率	文档	示例
单例模式 (Singleton)	保证类只有一个实例并提供全局访问点	⭐⭐	高	📖	💻
工厂方法 (Factory Method)	定义创建对象的接口，由子类决定实例化哪个类	⭐⭐	高	📖	💻
抽象工厂 (Abstract Factory)	提供创建一系列相关对象的接口	⭐⭐⭐	中	📖	💻
建造者 (Builder)	分步骤构建复杂对象	⭐⭐⭐	中	📖	💻
原型 (Prototype)	通过复制现有实例创建新对象	⭐⭐	中	📖	💻

结构型模式 (Structural Patterns) - 6个

模式	意图	复杂度	使用频率	文档	示例
适配器 (Adapter)	使不兼容接口能够协同工作	⭐⭐	高	📖	💻
组合 (Composite)	将对象组合成树形结构	⭐⭐⭐	中	📖	💻
装饰器 (Decorator)	动态添加对象功能	⭐⭐	高	📖	💻
外观 (Facade)	为子系统提供统一接口	⭐	高	📖	💻
代理 (Proxy)	为对象提供代理以控制访问	⭐⭐	中	📖	💻

行为型模式 (Behavioral Patterns) - 8个

模式	意图	复杂度	使用频率	文档	示例
责任链 (Chain of Responsibility)	将请求沿着处理链传递	⭐⭐	中	📖	💻
命令 (Command)	将请求封装为对象	⭐⭐	高	📖	💻
迭代器 (Iterator)	顺序访问集合元素	⭐⭐	高	📖	💻
备忘录 (Memento)	保存和恢复对象状态	⭐⭐	低	📖	💻
观察者 (Observer)	定义对象间的一对多依赖	⭐⭐	高	📖	💻
状态 (State)	根据状态改变对象行为	⭐⭐⭐	中	📖	💻
策略 (Strategy)	定义一系列算法并可互换	⭐⭐	高	📖	💻
模板方法 (Template Method)	定义算法骨架，延迟部分步骤	⭐⭐	中	📖	💻

🚀 快速开始

安装依赖

# 克隆项目
git clone https://github.com/HACK-WU/pythonic-design-patterns.git
cd pythonic-design-patterns

# 使用 uv 安装依赖（推荐）
uv sync

# 或使用 pip
pip install -e .

运行示例

# 运行单个模式示例
python src/creational/singleton/example.py
python src/behavioral/strategy/example.py

# 运行综合示例
python examples/ecommerce_system/ecommerce_system.py

📚 学习路径

🟢 初级阶段 (2-3周)

推荐先学习这些最常用的模式：

1. 单例模式 - 理解对象创建控制
2. 工厂方法 - 掌握对象创建的灵活性
3. 策略模式 - 理解算法封装
4. 观察者模式 - 理解对象间通信
5. 装饰器模式 - 理解动态功能增强

🟡 中级阶段 (3-4周)

深入理解对象组装和职责分离：

6. 建造者模式 - 复杂对象的构建
7. 适配器模式 - 接口兼容
8. 命令模式 - 操作封装与撤销
9. 状态模式 - 状态管理

🔴 高级阶段 (2-3周)

掌握高级抽象和复杂场景：

10. 抽象工厂 - 产品族创建
11. 组合模式 - 树形结构
12. 责任链模式 - 请求处理链
13. 模板方法 - 算法框架

📖 详细学习计划: 学习路径指南

🎯 模式选择指南

不知道该使用哪个模式？查看我们的选择指南：

• 📖 模式选择指南 - 根据问题场景选择合适的模式
• 📖 模式概览 - 所有模式的快速概览
• 📖 最佳实践 - 使用设计模式的最佳实践

快速选择

你想要...	推荐模式
确保全局只有一个实例	单例模式
运行时选择算法	策略模式
一对多通知机制	观察者模式
动态添加功能	装饰器模式
支持撤销/重做	命令模式 + 备忘录模式
处理树形结构	组合模式
接口不兼容	适配器模式
简化复杂系统	外观模式

📂 项目结构

pythonic-design-patterns/
├── src/                      # 源代码
│   ├── creational/          # 创建型模式 (5个)
│   │   ├── singleton/       # 单例模式
│   │   │   ├── singleton.md        # 模式文档
│   │   │   ├── singleton_impl.py   # 核心实现
│   │   │   ├── example.py          # 使用示例
│   │   │   └── __init__.py
│   │   ├── factory/         # 工厂方法模式
│   │   ├── abstract_factory/ # 抽象工厂模式
│   │   ├── builder/         # 建造者模式
│   │   └── prototype/       # 原型模式
│   ├── structural/          # 结构型模式 (5个)
│   │   ├── adapter/         # 适配器模式
│   │   ├── composite/       # 组合模式
│   │   ├── decorator/       # 装饰器模式
│   │   ├── facade/          # 外观模式
│   │   └── proxy/           # 代理模式
│   └── behavioral/          # 行为型模式 (8个)
│       ├── chain_of_responsibility/  # 责任链模式
│       ├── command/         # 命令模式
│       ├── iterator/        # 迭代器模式
│       ├── memento/         # 备忘录模式
│       ├── observer/        # 观察者模式
│       ├── state/           # 状态模式
│       ├── strategy/        # 策略模式
│       └── template_method/ # 模板方法模式
├── examples/                # 综合应用示例
│   └── ecommerce_system/   # 电商系统示例
├── docs/                    # 详细文档
│   ├── learning_path.md    # 学习路径指南
│   ├── pattern_selection_guide.md  # 模式选择指南
│   ├── patterns_overview.md # 模式概览
│   └── best_practices.md   # 最佳实践
├── tests/                   # 测试套件
├── pyproject.toml          # 项目配置(uv兼容)
└── README.md               # 项目说明

💻 代码示例

单例模式

from src.creational.singleton import singleton, ConfigManager

# 方式1: 使用装饰器
@singleton
class Logger:
    def log(self, message: str):
        print(f"LOG: {message}")

logger1 = Logger()
logger2 = Logger()
assert logger1 is logger2  # ✅ 同一个实例

# 方式2: 使用配置管理器
config = ConfigManager()
config.set("app_name", "MyApp")

策略模式

# 策略可以是简单的函数
def alipay_payment(amount: float) -> bool:
    print(f"支付宝支付: ¥{amount}")
    return True

def wechat_payment(amount: float) -> bool:
    print(f"微信支付: ¥{amount}")
    return True

# 使用字典映射策略
strategies = {"alipay": alipay_payment, "wechat": wechat_payment}

# 运行时选择策略
payment = strategies["alipay"]
payment(100.0)  # 输出: 支付宝支付: ¥100.0

观察者模式

class EventEmitter:
    def __init__(self):
        self._listeners = {}
    
    def on(self, event: str, callback):
        self._listeners.setdefault(event, []).append(callback)
    
    def emit(self, event: str, *args):
        for callback in self._listeners.get(event, []):
            callback(*args)

# 使用
emitter = EventEmitter()
emitter.on("user.created", lambda user: print(f"欢迎 {user}!"))
emitter.emit("user.created", "张三")  # 输出: 欢迎 张三!

🤝 贡献指南

欢迎贡献！贡献类型：

• 🐛 Bug修复
• ✨ 新增示例
• 📝 文档改进
• 🎨 代码优化

📝 许可证

本项目采用 MIT License 开源协议。

🙏 致谢

本项目参考了以下资源：

• 《设计模式：可复用面向对象软件的基础》(GoF)
• 《Head First 设计模式》
• Python官方文档
• refactoring.guru - 优秀的模式图解

📬 联系方式

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

⭐ 如果这个项目对你有帮助，欢迎star支持！