pytest中mock重载方法不生效，是因为@overload仅用于类型提示，运行时只存在未标注@overload的实现函数，mock必须针对该真实函数而非重载签名。
pytest里mock重载方法为什么总不生效
因为Python的重载（overload）只是类型提示层面的声明，运行时并不存在多个同名函数实体。@overload装饰的函数不会被实际执行，真正运行的是后面那个未加@overload的实现函数。所以你mock了某个带@overload的签名，其实没碰到底层逻辑。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 只mock最终那个**未标注
@overload的实现函数**，而不是任意一个重载签名 - 检查目标方法是否真被
typing.overload修饰过——用help()或inspect.signature()确认，别凭IDE提示判断 - 如果类里有多个重载版本，但只覆盖了部分参数组合，mock后仍可能走其他分支，得看调用时的实际参数类型
mocker.patch对实例方法重载的常见失效场景
当你用mocker.patch去patch一个实例方法，而该方法又被@overload修饰过，容易掉进两个坑：一是patch路径写错（比如patch了类名却忘了实例绑定），二是patch时机不对（在fixture setup之后才导入目标模块）。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 确保patch路径指向**运行时实际调用的那个函数对象**，例如
mocker.patch('mymodule.MyClass.real_implementation')，而不是某个@overload装饰的占位符 - 在测试函数开头就patch，或者用
@pytest.fixture配合autouse=True，避免模块已缓存导致patch失效 - 如果方法是通过
self.method()调用的，且你mock的是类属性，记得用autospec=True，否则可能漏掉绑定行为
用mocker.spy替代patch来验证重载调用路径
当你要确认某次调用到底匹配了哪个重载签名，patch会切断真实逻辑，反而看不出分发结果；这时spy更合适——它保留原行为，只记录调用信息。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 对最终实现函数使用
mocker.spy(MyClass, 'real_implementation')，然后检查spy.call_args里的参数类型 - 结合
isinstance()或type()在测试中手动模拟不同重载条件，比依赖类型检查器更可靠 - 注意
spy不会自动处理classmethod或staticmethod，需显式指定spy=MyClass.classmethod_name而非MyClass.classmethod_name
pytest-mock和unittest.mock在重载场景下的兼容性差异
pytest-mock本质是unittest.mock的封装，底层行为一致，但它的mocker fixture默认启用spec_set=True，对重载函数的属性访问更严格——比如试图读取__signature__可能抛AttributeError。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 遇到
AttributeError: __signature__这类报错，优先尝试关闭spec：mocker.patch('...', spec=False) - 如果项目用了
pyright或mypy做静态检查，mock后的返回类型可能和重载声明不一致，需要手动加# type: ignore或用cast - 不要在同一个测试里混用
unittest.mock.patch和mocker.patch，它们的patch栈不共享，容易漏还原
重载本身不改变运行时对象结构，所有mock操作都得落在那个唯一的真实函数上——这点最容易被类型提示带偏。盯着id()输出或__code__.co_filename确认你mock的到底是不是它，比看函数名靠谱得多。
