Python设计模式实战：从经典套路到多Agent架构的思维迁移

设计模式（Python）——聊聊那些被高估和低估的套路

先说明，我写这篇不是在给你背 GoF 那本经典书里的类图，而是想聊聊“设计模式”这四个字放在 Python 语境下，到底该怎么理解、怎么用、怎么应付大作业和面试。

最近和几个朋友在搞多 agent 应用，聊到一个很有意思的观点：现代多 agent 设计里的“主从模式”，其实本质上就是把 subagent 当作一种另类的 tool 来调用。这个思路一出来，我突然觉得设计模式这个概念从来没有过时，它只是换了一副面孔继续存在于我们的架构里。无论是传统的 23 种 GoF 模式，还是现在 AI agent 的工具调用，背后都是同一套工程思维：把可复用的经验沉淀成结构，用稳定的结构对抗复杂度。

这篇文章我会从几个角度展开：为什么在 Python 里要重新理解设计模式、哪些模式最值得掌握、传统模式和 agent 场景之间的映射关系、以及大作业和面试怎么脱颖而出。全程用我自己踩过的坑和实测过的代码说话，不绕弯子。

1. 为什么我劝你在 Python 里重新理解设计模式

1.1 设计模式的本质是“场景经验的压缩包”

很多人一开始学设计模式就背类图，这是最大的误区。设计模式不是什么高深的数学定理，它更像是一个“场景经验的压缩包”。打个比方，你在生活中遇到了“出门要带钥匙、手机、钱包”这件事，总结出一个习惯叫“出门三件套”。下次再出门不用重新想，直接按这个套路来。设计模式就是工程界的“三件套”：当某个问题场景反复出现，前人把解决方案、推导过程、注意事项打包在一起，起个名字，比如“观察者模式”“策略模式”，大家一听到名字就懂你在说什么。

所以在 Python 里学设计模式，第一步不是背 UML，而是建立“场景—方案”的联想。看到“运行时需要切换算法”，想到策略模式；看到“一个对象状态变化要通知一堆依赖者”，想到观察者模式；看到“创建对象的过程需要别处统一管理”，想到工厂模式。这样学，面试时你能聊出花来，写代码时也知道该往哪个方向走。

我见过太多人把设计模式当成“代码规范”来批判，说“这么简单的功能还要套一层，不是浪费吗”。这种批评有一定道理，但更多是对模式的误解。模式不是为了炫技，而是为了应对“变化”和“复杂”。如果一段代码从头到尾只写一次、永远不会变、没有任何协作者，那确实不需要模式。但现实项目里，需求会变、团队会换、接口会迭代，模式的价值就体现在这里。

1.2 Python 让很多模式“隐形”了

Python 这门语言有一个特点：很多在 Java/C++ 里必须用模式解决的问题，在 Python 里被语言特性直接解决了。这不是说模式没用了，而是说有些模式的“实现成本”被降到极低，甚至看起来像消失了一样。

举个最典型的例子：策略模式。在 Java 里你通常要定义一个策略接口、写多个实现类、再用一个上下文类来持有策略对象。而在 Python 里，函数是一等公民，直接在调用处传一个函数就行。你看不出“策略模式”的影子，但它确实在起作用。

再比如迭代器模式。Java 里要写 Iterator 接口、hasNext()、next() 方法，Python 里只需实现 __iter__ 和 __next__，更多时候直接用 for 循环加生成器就完事了。命令模式在 Python 里可以用函数对象或 functools.partial 轻量替代；单例模式直接用模块天然实现；外观模式往往就是一个 __init__.py 里导出的公共函数。

我把经典模式在 Python 里的“形态变化”整理成一个表格，你看看就明白了：

所以我的结论是：在 Python 里学设计模式，重点不是逐字复刻类图，而是理解每个模式解决的核心冲突，然后用 Python 的方式给出最简洁的落地。你要是一板一眼地把 Java 的工厂类搬到 Python，代码会比原来更啰嗦，这反而违背了模式最初的目的。

2. Python 里最值得先掌握的 6 种模式

2.1 策略模式：从 if/elif 到选择器

策略模式是我最推荐 Python 初学者先掌握的模式，因为它的日常使用频率太高了。最常见的坏味道，就是业务代码里堆了一长串 if/elif 来根据条件执行不同算法。

举个例子，假设你写一个订单折扣系统，打折规则有好几种：新人折扣、满减、会员折扣、节日折扣。新手写法是一大坨逻辑堆在主函数里，时间一长谁也改不动。策略模式的思路很简单：把每种折扣规则封装成独立策略，然后在运行时选择。

Python 里最常见的轻量实现，直接用字典做注册表：

python复制from typing import Callable, Dict

def discount_newbie(price: float) -> float:
    return price * 0.9

def discount_full_reduction(price: float) -> float:
    return price - 50 if price >= 500 else price

def discount_vip(price: float) -> float:
    return price * 0.75

# 注册表：把策略名映射到实现函数
discount_strategies: Dict[str, Callable[[float], float]] = {
    "newbie": discount_newbie,
    "full_reduction": discount_full_reduction,
    "vip": discount_vip,
}

def apply_discount(price: float, strategy_name: str) -> float:
    strategy = discount_strategies.get(strategy_name)
    if strategy is None:
        raise ValueError(f"unknown strategy: {strategy_name}")
    return strategy(price)

以后加新策略，只需要新增一个函数、在字典里注册一行，主流程完全不用动。这就是策略模式在 Python 里最自然的形态。我实际工作中已经很少为策略模式单独建类了，除非策略本身足够复杂、需要维护内部状态，那种情况下才考虑类封装。

这套“注册表 + 函数”的组合在 agent 场景里也经常用到。比如给 LLM 定义不同的处理工具，配置一个 name 到 handler 的映射，主调度逻辑只需查表调用，完全符合开闭原则。

2.2 观察者模式：事件与解耦

观察者模式解决的核心问题是“一对多通知”。当被观察对象发生变化时，自动通知所有关注它的观察者，而不需要自己逐个调用。这种模式在 GUI 事件、消息系统、监控告警、状态同步里都大量出现。

Python 里不需要像 Java 那样老老实实写 Observer 接口和 Subject 类，一个简单的自定义事件类就够了：

python复制from typing import Callable, Dict, List

class EventEmitter:
    def __init__(self):
        self._listeners: Dict[str, List[Callable]] = {}

    def on(self, event_name: str, handler: Callable):
        self._listeners.setdefault(event_name, []).append(handler)

    def emit(self, event_name: str, *args, **kwargs):
        for handler in self._listeners.get(event_name, []):
            handler(*args, **kwargs)

# 使用示例
emitter = EventEmitter()

def on_task_finished(task_id: str, result: str):
    print(f"[通知] 任务 {task_id} 完成，结果：{result}")

emitter.on("task_finished", on_task_finished)

# 业务逻辑里只需要负责执行并发布事件
emitter.emit("task_finished", "abc123", "success")

在 agent 场景里，这种事件机制可以承担消息总线角色。比如主 agent 完成一个子任务后，emit 一个事件，多个下游调度模块各取所需：有人负责记录日志，有人负责触发下一步规划，有人负责更新状态面板。观察者和后来基于回调的“发布订阅”本质上是一回事，核心价值就是解耦：发布方不关心谁在听，订阅方不关心谁在说。

我在这块踩过的一个坑是：回调里发生异常会直接打断主流程。所以在事件系统里，我通常会给每个 handler 包一层 try/except，并且做超时控制，避免一个观察者崩了连累整个发布方。

2.3 工厂模式：创建对象的“装配车间”

工厂模式属于创建型模式，核心是把“创建对象”的逻辑从使用方抽离出来。为什么需要它？因为当对象创建过程变复杂时，到处写构造函数的代码会蔓延到业务各处，一旦创建逻辑变化，所有调用点都要跟着改。

Python 里我用的最多的是“类方法工厂”和“字典注册表工厂”两种形态。先看类方法工厂，适合一个类有多种创建方式：

python复制class Config:
    def __init__(self, host: str, port: int, timeout: int = 30):
        self.host = host
        self.port = port
        self.timeout = timeout

    @classmethod
    def from_dict(cls, data: dict) -> "Config":
        return cls(
            host=data.get("host", "localhost"),
            port=data.get("port", 8080),
            timeout=data.get("timeout", 30),
        )

    @classmethod
    def from_env(cls, env) -> "Config":
        return cls(
            host=env.get("APP_HOST", "localhost"),
            port=int(env.get("APP_PORT", 8080)),
        )

这种写法让外部不需要关心 Config 怎么解析字典、怎么读环境变量，只调用 Config.from_dict(data) 或 Config.from_env(os.environ) 就完成创建。

再看字典注册表工厂，适合运行时根据类型名创建不同子类：

python复制class Tool:
    def run(self, *args, **kwargs):
        raise NotImplementedError

class SearchTool(Tool):
    def run(self, query: str):
        return f"search result for {query}"

class CalculatorTool(Tool):
    def run(self, expression: str):
        return f"calculated: {eval(expression)}"  # 示例就别学 eval 了

tool_registry: dict[str, type[Tool]] = {
    "search": SearchTool,
    "calculator": CalculatorTool,
}

def create_tool(tool_name: str) -> Tool:
    tool_cls = tool_registry.get(tool_name)
    if tool_cls is None:
        raise ValueError(f"unsupported tool: {tool_name}")
    return tool_cls()

抽象工厂模式（创建一组相关对象）在 Python 里出现的频率要低很多，因为 Python 的动态特性让“一组相关对象”在多数场景下就是一个字典或 dataclass 就够了。我个人建议：简单场景用类方法，复杂场景用注册表，不要为了“规范”而硬套抽象工厂。

2.4 单例与模块级共享状态：Python 的特殊解法

单例模式恐怕是 23 种模式里在 Python 社区争议最大的一个。Java/C++ 里单例是为解决“全局唯一实例”的问题而生的，而 Python 的模块在导入时天然只有一个实例。所以最简单的 Python 单例，就是直接在模块里创建一个对象：

python复制# db.py
class Database:
    def __init__(self):
        self.connected = True

db = Database()  # 全局唯一实例

其他模块直接 from db import db，拿到的永远是同一个对象。这比写 __new__ 重写和元类简单多了，还不会踩到线程同步的坑。

如果你真的需要确保类无法被二次实例化，可以重写 __new__：

python复制class Database:
    _instance = None

    def __new__(cls, *args, **kwargs):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

    def __init__(self, host="localhost"):
        self.host = host

db1 = Database()
db2 = Database()
print(db1 is db2)  # True

但这里有一个很隐蔽的坑：__new__ 保证了实例唯一，可 __init__ 会在每次调用 Database() 时重新执行一遍。也就是说，虽然你拿到的是同一个对象，但它的属性会被重复初始化。如果你不想这样，就得额外加锁。

我在实际项目里的态度很明确：非必要不用单例。因为全局唯一的对象通常意味着全局状态，全局状态在测试、并发、多实例部署里都是麻烦的源头。与其追求“唯一”，不如把依赖对象显式传给需要它的模块，也就是依赖注入的思路。

2.5 装饰器模式与 Python 装饰器：同名不同物

GoF 里的装饰器模式，目的是在不修改原对象的情况下动态扩展职责。Java 里的典型例子是 BufferedInputStream 包装 FileInputStream，一层层叠加能力。Python 里有一个同名但形态完全不同的东西：装饰器语法 @decorator。两者名字一样，但一个是结构型模式，一个是语言语法。初学者经常搞混，这个我说一下就好，不必太纠结，重点是理解职责叠加这件事。

在 Python 里，函数装饰器是叠加职责最自然的工具。如果你想给函数增加日志、缓存、权限校验或重试逻辑，不需要侵入函数内部，直接写一个装饰器包一层：

python复制import functools
import time

def retry(max_retries: int = 3, delay: float = 1.0):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(max_retries):
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    if attempt == max_retries - 1:
                        raise
                    time.sleep(delay)
            return None
        return wrapper
    return decorator

@retry(max_retries=3, delay=0.5)
def call_external_api(url: str):
    # 模拟不稳定接口
    raise ConnectionError("timeout")

这段代码的作用是给 call_external_api 增加重试能力，而函数本体完全不知道重试的存在。这就叫“不修改原对象地扩展职责”，和装饰器模式的核心思想一致，只不过 Python 用语法把这个过程包装得极其顺滑。

如果装饰的能力需要在多个类之间复用，可以考虑类装饰器：

python复制def log_call(cls):
    original_init = cls.__init__
    def new_init(self, *args, **kwargs):
        print(f"[创建实例] {cls.__name__}")
        original_init(self, *args, **kwargs)
    cls.__init__ = new_init
    return cls

@log_call
class Service:
    def __init__(self, name: str):
        self.name = name

这类技巧在实现插件系统、动态增强类能力的时候非常实用。不过要注意，装饰器叠加太多层会把调用栈搞得很深，排查问题的时候比较痛苦，所以一个装饰器只做一件事，组合使用时注意顺序。

2.6 适配器模式：接口不一致时的“转接头”

适配器模式解决的是“接口不匹配”问题，就像你用手机转接头连接不同接口的设备一样，外面看不出变化，但内部完成了规格转换。在实际项目中，最常见的场景是接外部 SDK：别人给的接口不符合你的业务层预期，你不想改业务层，也不想改别人的库，那就写个适配器。

假设项目里内置了一套上传接口：

python复制class Uploader:
    def upload(self, path: str) -> str:
        return f"uploaded: {path}"

现在要对接一个第三方云存储 SDK，它提供的接口叫 put_file，参数也完全不同。第三方库我们动不了，业务层也不想动，于是写一个适配器：

python复制class CloudStorageSDK:
    def put_file(self, local_path: str, bucket: str, key: str) -> bool:
        # 第三方 SDK 的原始实现
        print(f"云存储上传: {local_path} -> {bucket}/{key}")
        return True

class CloudStorageAdapter(Uploader):
    def __init__(self, sdk: CloudStorageSDK, bucket: str):
        self._sdk = sdk
        self._bucket = bucket

    def upload(self, path: str) -> str:
        key = path.split("/")[-1]
        ok = self._sdk.put_file(local_path=path, bucket=self._bucket, key=key)
        return f"upload ok: {key}" if ok else "upload failed"

业务层拿到 CloudStorageAdapter 就像拿到一个普通 Uploader，该怎么用还是怎么用，底下的差异被适配器吞掉了。这种模式在切换第三方依赖时是救命稻草：新接入一个 SDK，你只需要写一个新的适配器，所有上层代码一行不改。

Python 里还有一个特别常见的适配器场景：把同步函数包装成异步接口，或者反过来。比如旧模块是 requests.get 同步调用，新系统是 async/await 异步链路，用 asyncio.to_thread 包一层，就完成了一次“同步转异步”的适配。

3. 当设计模式遇到 AI Agent：主从模式与“工具化”思想

3.1 从“主从模式”到“把 subagent 当作一种 tool”

最近 AI agent 工程化非常火，热词里有一句话特别点醒我：“最新的多 agent 设计里主从模式，其实本质上将 subagent 视作另类的 tool 进行调用。”这句话看起来是在讲 agent，但仔细一想，这背后正是设计模式在新时代的演化。

传统的“主从模式”在软件架构里是一种常见的控制结构：一个主控节点负责任务拆分、调度、汇总，多个从节点负责具体执行。对应到 GoF 模式里，它和“组合模式”“外观模式”“命令模式”都有亲缘关系。而在 agent 场景里，主从模式的形成更为自然：主 agent 负责理解用户意图、规划任务，subagent 负责执行具体领域任务，比如搜索资料、写代码、查数据库。主 agent 不需要关心 subagent 内部怎么实现，只需要知道它接受什么输入、返回什么结果——这不就是一个 tool 吗？

一旦把 subagent 当成 tool，主 agent 的调度逻辑就变得极其简洁。它可以把 subagent 和普通的函数工具一样注册进自己的工具列表，在规划时统一选择调用。这种抽象带来的好处非常多：工具调度框架可以复用、切换子 agent 实现不需要改主逻辑、测试时可以用 mock 工具替换真实 agent。

我自己的体会是，这个观点把 agent 开发从“玄学”拉回了“软件工程”。很多团队在设计多 agent 系统时，一上来就纠结每个 agent 的性格、提示词、记忆，但忽略了这些 agent 之间的调用关系其实就是一个经典的“策略选择 + 组合执行”问题。用设计模式的思维去架构 agent 系统，比给每个 agent 写一万字的 prompt 重要得多。

3.2 一个可运行的 Agent 调度示例

为了说明“subagent 就是 tool”这个思想，我写一个很小的示例。先定义 Tool 抽象基类，再实现两个具体的 subagent 工具，主 agent 通过注册表调用它们。

python复制from typing import Dict, Any

class BaseAgentTool:
    name: str = "base"

    def execute(self, input_text: str) -> str:
        raise NotImplementedError


class SearchAgent(BaseAgentTool):
    name = "search"

    def execute(self, input_text: str) -> str:
        # 模拟搜索子智能体
        return f"[搜索agent] 针对 '{input_text}' 找到 3 条结果"


class CodeWriterAgent(BaseAgentTool):
    name = "code_writer"

    def execute(self, input_text: str) -> str:
        # 模拟代码生成子智能体
        return f"[代码agent] 已生成功能代码: def solve(): pass"


class MainAgent:
    def __init__(self):
        # 关键点：subagent 注册为工具
        self.tools: Dict[str, BaseAgentTool] = {
            tool.name: tool
            for tool in [SearchAgent(), CodeWriterAgent()]
        }

    def run(self, task: str, tool_name: str) -> str:
        tool = self.tools.get(tool_name)
        if tool is None:
            return f"未知工具: {tool_name}"
        return tool.execute(task)


if __name__ == "__main__":
    main_agent = MainAgent()
    print(main_agent.run("python装饰器怎么用", "search"))
    print(main_agent.run("写一个快排函数", "code_writer"))

这段代码的结构不复杂，但思想是核心：主 agent 不直接依赖具体的 SearchAgent 或 CodeWriterAgent，而是依赖“工具注册表 + 统一 execute 接口”。以后加一个新 subagent，只需要新建一个类并注册到 tools 字典里，主 agent 完全不用改。这其实就是“策略模式 + 工厂模式 + 组合模式”在 agent 场景的组合应用。

我再补一层，如果把“是否要调用 subagent”这个决策交给 LLM 来做，那么主 agent 只需要把工具列表传给 LLM，让它返回一个结构化调用结果，再按照结果路由到对应工具执行。这个流程，就是 OpenAI function calling 的基本思路，也是主从模式在 agent 里最典型的落地形态。

这里我还想多说一点：把 subagent 当 tool 和直接调函数工具，本质上没有区别，唯一的差别是 subagent 的执行逻辑更重、可能涉及多轮推理、上下文窗口更大、成本更高。所以工程上要设计好“工具挑选”的策略，避免主 agent 什么事都派 subagent，导致延迟和费用爆炸。

3.3 Agent 场景下模式选择的经验之谈

在实际做 agent 项目时，我总结了一套简单的选型判断逻辑，分享给你参考：

第一，如果子任务之间是独立的、可以并行的，优先采用“主从 + 并行工具”的模式。主 agent 发起多个工具调用，等待结果汇总。这种情况下，可以结合 asyncio.gather 并发执行多个 subagent，但要注意并发数和超时控制。

第二，如果子任务之间有严格先后依赖，例如先搜索再写报告，那么“主从 + 管线模式”更合适。这个在传统设计模式里叫“责任链模式”或“管道模式”，每个 agent 处理完把结果传给下一个 agent，形成一条流水线。

第三，如果同一个 agent 需要根据输入的不同执行不同分支逻辑，那就用策略模式。在它的提示词里把所有分支规则描述清楚，让模型自己选择，这其实也是一种策略选择，只不过决策者是 LLM 而不是代码。

第四，用有限状态机控制 agent 的流程，避免无限循环。我在多 agent 调试中遇到最多的问题就是 agent 反复尝试、互相调用，导致陷入死循环甚至费用爆炸。一个简单的状态枚举（如 INIT → PLANNING → EXECUTING → REVIEW → DONE）加超时终止，就能省下大量 API 费用。

这个时代的设计模式，不再是画几个类图就能交差的“八股文”，而是理解“如何拆解复杂度、如何组织依赖、如何优雅地应对变化”的思维框架。学设计模式跟做 agent 开发并不矛盾，反而是地基和塔尖的关系。

4. 大作业/考试怎么拉开差距：选题与答辩的细节

4.1 设计模式大作业的选题套路

热搜词里有“设计模式大作业”“设计模式期末”，我猜不少人是学生身份，最后要交一个大作业或者应付考试。如果只是把所有 23 种模式各写一遍 demo，那是最低分的做法，因为老师一眼就看穿你没有工程思维。真正拿高分的作业，一定是用一条业务主线串起多个模式，让每个模式都“有用武之地”。

选题别太老套，什么“咖啡店点单系统”“图形绘制系统”已经被写烂了。我建议选一个时代感强一点的主题，例如“一个支持插件扩展的智能客服机器人”或“一个多 agent 任务调度系统”。这类题目自带业务复杂度，方便引出策略、观察者、工厂、适配器、装饰器等模式。然后以“一主三从”的布局来讲：选 1 个核心创建型模式（比如工厂模式）作为系统入口，2 个结构型模式（比如适配器、外观）解决集成问题，3 个行为型模式（比如策略、观察者、命令）体现业务逻辑的灵活变化。不需要 23 种全上，能讲透 6 种已足够拿高分。

我有一个推荐的组合示例，你可以直接参考：

• 业务主线：开发一个“智能客服路由系统”
• 策略模式：根据用户意图选择客服分派策略
• 工厂模式：根据配置创建不同渠道的客服客户端
• 观察者模式：会话状态变化时通知多个子系统（工单系统、数据分析、监控）
• 适配器模式：对接不同的 IM 平台，统一消息发送接口
• 外观模式：提供一个简单的 CustomerServiceFacade，让调用方只面对一个入口
• 单例模式（可选）：统一配置管理，但要说明为什么用模块级单例以及潜在风险

这样的作业结构清晰，有实际的业务价值，老师答辩时也容易问出深度问题，你反而有机会展示自己的思考。

4.2 类图、时序图与讲解的黄金比例

大作业的呈现形式，除了代码之外，一般还要求画类图和时序图。我的经验是：不要用工具自动生成一堆密密麻麻的图，那是给评委添堵。你只需要画核心类的简化图，把每个类的职责一句话标出来，并且标注清楚哪些类之间是组合、聚合、继承关系。

时序图同理，只需画一条最核心的调用链，比如“用户输入 → 外观层 → 工厂创建客户端 → 策略路由 → 观察者通知”。把这条链画清楚，比你画十张复杂的图更能讲明白你的设计。我在答辩时的讲法遵循“黄金比例”：30% 时间讲业务背景，40% 讲核心设计思路，30% 讲代码实现和踩坑。很多同学把 80% 时间都耗在“这个类是什么、那个方法干什么”上，老师听着听着就走神了。你反过来，重点讲“为什么这么设计，如果需求变化了会怎样”，反而能让老师眼前一亮，觉得你真懂了。

答辩时最容易被问到的问题无非这几个：为什么用工厂模式？这里用单例会不会有问题？如果新增一个渠道你要改哪些代码？这些问题的答案，其实在你动手设计的过程中就应该想清楚。我建议你提前写一份“设计决策说明”，把每个模式选择的动机和替代方案记录下来，答辩时信手拈来，比现场组织语言要稳得多。

5. 我踩过的坑和排查技巧

5.1 模式滥用与“为了模式而模式”

这是初学阶段最容易犯的毛病。有一段时间我拿到一个需求就想套模式，写一个简单的下载功能，硬是定义了 Downloader 接口、HttpDownloader、FtpDownloader、DownloaderFactory、DownloadFacade，结果代码量翻了三倍，同事看代码时一脸茫然。后来我反思了一下，模式滥用的问题在于：你把“可复用”当成目标，但忽略了“当前复杂度”。

一个很实用的判断标准是：如果这套抽象在未来三个月内几乎不可能出现第二个实现，那就不要急着上“接口 + 工厂 + 策略”全家桶。等第二个需求真正出现时，再重构也不迟，这就是“三次法则”——同一个代码结构出现三次重复，才考虑抽象。在这之前，写简单的函数够了。记住，设计模式是拿来“解除”复杂度的，不是拿来“制造”复杂度的。

在 Python 里还有一个特殊情况：动态语言的灵活性让很多模式变得“可选”。一个函数参数就能解决的事情，没必要造一个类层次结构。我自己的原则是：优先写直白代码，当直白代码开始出现明显的重复和分支膨胀时，再考虑用模式整理。这样做，代码的长期可维护性反而更好。

5.2 单例状态污染与测试难题

我在做支付系统时踩过一个典型的单例坑：配置模块用了一个全局单例 Config，里面存了商户号、密钥等信息。第一轮测试跑得很顺，但第二轮测试开始，数据却还是第一轮的旧值，排查了半天才发现是单例对象在测试进程里被共享，状态没有重置。从那以后我对全局单例就特别警惕，尤其在测试场景里。

解决方案不外乎三种。第一，用依赖注入：把配置对象作为参数传给每个需要它的函数或类，测试时传入自定义对象，互不干扰。第二，用上下文管理器：把关键状态放在 with 块里，进入时重设，退出时恢复，保证测试隔离。第三，用工厂函数创建独立实例，只有明确需要共享的地方才用模块级共享。这三个思路里，依赖注入最推荐，因为它不仅解决了测试问题，还让依赖关系一目了然。类似地，多 agent 系统里如果每个 agent 是全局单例，它们各自的会话状态也容易串，一定要留意无状态设计，把上下文显式传递给每个调用。

5.3 Python 具体实现中的几个“暗坑”

第一个坑是 __new__ 和 __init__ 的执行顺序。前面说过，重写 __new__ 做单例时，__init__ 依然会重复执行，导致“同一对象但属性被重置”的怪象。解决办法不仅是在 __new__ 里判断实例是否存在，还要在 __init__ 里加一个初始化标记，例如 if not hasattr(self, '_initialized')。如果使用 __new__ 还是 __init__ 搞不清执行顺序，建议单步调试一遍，比背文档有效。

第二个坑是装饰器导致函数元信息丢失。如果你自己写装饰器却不加 functools.wraps(func)，调试时你会看到函数名变成 wrapper，签名也丢了，非常难受。很多第三方工具在做自动签名解析、文档生成、异常链路追踪时会受影响。规范做法是在自定义装饰器内部加上 @functools.wraps(func)，一行代码解决，别懒。

第三个坑是循环导入。设计模式拆分成多个文件时，容易因为工厂注册表引用子类、子类又引用基类而导致循环导入。我常用的解决办法有几种：把注册表单独放一个文件，延迟导入（在函数内部 import），或者干脆用字符串作为模块路径，让工厂在调用时才动态导入。在 agent 工程中，工具注册表和 agent 定义之间也常有循环依赖，我会把工具注册表设计成“只存储工厂函数或 import 路径”的轻量结构，而不是直接持有具体类的引用。

第四个坑是 super() 在多继承下的 MRO 问题。Python 的方法解析顺序（MRO）并不简单，尤其在多个 mixin 类协作时很容易出现“谁调用了谁”的困惑。如果你在使用组合模式或者装饰类，建议把每个类的 super() 调用都写清楚，尽早排除 MRO 问题，比在大型代码里返工要轻松得多。

6. 结一些个人体会（收尾）

说了这么多，其实回到最初那个观点：设计模式在 Python 里，不应该是“背起来的框架”，而应该是“理解之后的自动反应”。我自己的学习路径，先是用 Java 的视角学了一遍 23 种模式，然后又用 Python 重构了一遍，最后才在真实项目里体会到了它们的价值。如果你想快速入门，建议不要买一堆理论书啃，而是找一份自己以前写过的、带有重复逻辑的项目代码，尝试用模式去重构它。每重构一个地方，就在笔记里记录“场景是什么、怎么改、效果如何”。

我一直保留着一个习惯：在代码仓库里建一个 docs/design-decisions.md，每做一个结构性决策就记一条，包括当时的约束条件、可选的几种方案、为什么选这个方案。这比写完代码就忘要强得多，也是面试时最稀缺的资产——你说得出“为什么”，这就是工程经验的沉淀。

另外，在多 agent 项目里，我现在每设计一个 agent 结构之前，都会先问自己三个问题：这个 agent 和外部模块的接口边界是否清晰？它能不能被当作一个普通的 tool 被统一调度？如果未来要换掉它的实现，需要改动多少上下游代码？这三个问题，本质上就是设计模式里的开闭原则、接口隔离原则和依赖倒置原则。你以为你在做 agent，其实你还是在做软件工程。

所以，不管你是为了应付期末大作业，还是想在代码里体会到“结构之美”，我都建议你从今天开始，用 Python 的方式重新认识设计模式。别纠结于是不是和 GoF 书上长得一模一样，先看它能不能帮你把问题想清楚。能想清楚，这个模式就真正属于你了。