Python 的 functools.singledispatch 是什么？怎么实现函数重载？

简化版

**functools.singledispatch 是 Python 的「单分派泛型函数」——它让你写一个函数，根据「第一个参数的类型」自动选择不同的实现，从而实现「按类型重载」（Python 本身不支持像 Java 那样的函数重载）。**用法：给主函数加 @singledispatch 装饰器（作为默认实现），再用 @主函数.register(类型) 注册各类型的专门实现，调用时会根据第一个参数的类型自动分派到对应实现。例子：@fmt.register(int) 处理整数、@fmt.register(list) 处理列表、没匹配的走默认。为什么叫「单分派」——只根据「一个参数」（第一个）的类型分派（「多分派」会根据多个参数的类型，Python 标准库只提供单分派）。核心价值：替代「一长串 if isinstance(x, int): ... elif isinstance(x, list): ...」，让「按类型处理」的代码可扩展（新增类型只需 register 一个，不改原函数）、更清晰。相关：functools.singledispatchmethod（3.8+，用于类的方法）。核心记忆：singledispatch 按第一个参数的类型分派到不同实现（Python 版函数重载），@singledispatch 定默认 + @f.register(类型) 注册各类型，替代 if-isinstance 链、可扩展。

详细版

singledispatch 的用法：

步骤	写法
定义默认实现	`@singledispatch def f(arg): ...`
注册类型实现	`@f.register(int) def _(arg): ...`
注册（类型注解式，3.7+）	`@f.register def _(arg: int): ...`
查看分派	`f.dispatch(int)`
类的方法	`@singledispatchmethod`（3.8+）

from functools import singledispatch

# 定义泛型函数（默认实现）
@singledispatch
def to_json(obj):
    raise TypeError(f"不支持的类型: {type(obj)}")

# 为不同类型注册实现
@to_json.register(int)
def _(obj):
    return str(obj)

@to_json.register(str)
def _(obj):
    return f'"{obj}"'

@to_json.register(list)
def _(obj):
    return "[" + ", ".join(to_json(x) for x in obj) + "]"

# 调用时根据第一个参数的类型自动分派
print(to_json(42))          # "42"（走 int 实现）
print(to_json("hi"))        # '"hi"'（走 str 实现）
print(to_json([1, "a", 2])) # '[42, "a", ...]'（走 list 实现，递归）

# 类型注解式注册（3.7+，更简洁）
@to_json.register
def _(obj: float):          # 从注解推断类型
    return str(obj)

# 一个实现注册多个类型（3.7+）
@to_json.register(int)
@to_json.register(float)
def _(obj):
    return str(obj)

# 查看某类型会分派到哪个实现
print(to_json.dispatch(int))    # <function _>

# 对比：不用 singledispatch 的 if-isinstance 链（难扩展）
def to_json_bad(obj):
    if isinstance(obj, int): return str(obj)
    elif isinstance(obj, str): return f'"{obj}"'
    elif isinstance(obj, list): return ...   # 每加类型都改这个函数
    else: raise TypeError()

⚠️ 核心价值：singledispatch 把「一长串 if isinstance(...) elif isinstance(...)」变成「可扩展的类型分派」——主函数是默认实现（兜底），每个类型的处理逻辑用 @f.register(类型) 单独注册，新增一个类型只需再 register 一个函数、完全不用改原函数或其他分支，符合「开闭原则」。它解决的是 Python「没有函数重载」的痛点：Java/C++ 里可以写多个同名函数（参数类型不同、编译期选），Python 不行（后定义的会覆盖前面的），只能靠运行时 isinstance 判断——而 isinstance 链有三个问题：① 每加类型要改原函数（违反开闭）、② 一长串 elif 难读、③ 逻辑集中在一处不好维护。singledispatch 让「同一操作、不同类型不同实现」的代码变得优雅、可扩展。两个要点：① 只按「第一个位置参数」的类型分派（这就是「单」分派，其余参数不参与选择）；② 按 MRO 匹配——如果注册了 int 而传入 bool（bool 是 int 子类），会分派到 int 的实现（找最接近的注册类型）。类里的方法用 singledispatchmethod（3.8+），因为普通 singledispatch 会把 self 当第一个参数、类型判断错位。

完整版教学

一、Python 没有函数重载

先理解痛点——Python 不支持传统重载：

传统函数重载（Java/C++）：
  同名函数、参数类型不同 → 编译期根据参数类型选
  void print(int x) {...}
  void print(String s) {...}
  print(42);      // 调 int 版
  print("hi");    // 调 String 版

Python 不支持：
  def process(x): ...       # 后定义的覆盖前面的
  def process(x): ...       # 这个覆盖了上面的
  → 只有一个 process 存在（同名 = 重新绑定）

Python 传统解法：运行时 isinstance 判断
  def process(x):
      if isinstance(x, int):
          return handle_int(x)
      elif isinstance(x, str):
          return handle_str(x)
      elif isinstance(x, list):
          return handle_list(x)
      else:
          return handle_default(x)

isinstance 链的问题：
  ① 违反开闭原则——每加一个类型要改 process 函数
  ② 难读——一长串 elif
  ③ 集中——所有类型逻辑挤在一个函数里
  ④ 第三方类型难扩展——改不了别人的函数

singledispatch 的解法：
  按类型"分派"到不同实现，注册式、可扩展
  → 新增类型只 register 一个，不改原函数

所以 Python 无函数重载(同名覆盖),传统用 isinstance 链(违反开闭),singledispatch 解决

传统函数重载（Java/C++）：同名函数、参数类型不同 → 编译期根据参数类型选。Python 不支持：def process(x) 后定义的覆盖前面的（同名 = 重新绑定、只有一个存在）。Python 传统解法：运行时 isinstance 判断（if isinstance(x, int): ... elif isinstance(x, str): ...）。isinstance 链的问题：① 违反开闭原则（每加类型要改函数）、② 难读（一长串 elif）、③ 集中（所有类型逻辑挤一个函数）、④ 第三方类型难扩展（改不了别人的函数）。singledispatch 的解法：按类型「分派」到不同实现、注册式、可扩展（新增类型只 register 一个、不改原函数）。理解「Python 无函数重载(同名覆盖只留一个);传统用 isinstance 链(违反开闭+难读+集中+难扩展第三方);singledispatch 按类型分派、注册式可扩展」，就理解了痛点。

二、singledispatch 的用法

理解基本用法：

三步用法：

① @singledispatch 装饰主函数（默认/兜底实现）：
   @singledispatch
   def area(shape):
       raise NotImplementedError("未知形状")

② @主函数.register(类型) 注册各类型实现：
   @area.register(Circle)
   def _(shape):          # 函数名用 _（不重要，被 register 收走）
       return 3.14 * shape.r ** 2

   @area.register(Square)
   def _(shape):
       return shape.side ** 2

③ 正常调用，自动分派：
   area(Circle(5))   # 走 Circle 实现
   area(Square(3))   # 走 Square 实现
   area("???")       # 走默认（raise）

注册的几种写法（3.7+）：
  # 显式指定类型
  @f.register(int)
  def _(x): ...
  # 从类型注解推断（更简洁）
  @f.register
  def _(x: int): ...
  # 一个实现注册多个类型（堆叠）
  @f.register(int)
  @f.register(float)
  def _(x): ...

内省：
  f.dispatch(int)     # 查 int 会分派到哪个实现
  f.registry          # 所有注册的映射（类型→实现）
  f.registry.keys()   # 已注册的类型

所以用法:@singledispatch 定默认+@f.register(类型)注册各实现,调用自动按类型分派

三步用法：① @singledispatch 装饰主函数（默认/兜底实现）（@singledispatch def area(shape): raise ...）；② @主函数.register(类型) 注册各类型实现（@area.register(Circle) def _(shape): ...，函数名用 _ 不重要）；③ 正常调用、自动分派（area(Circle(5)) 走 Circle 实现、area("???") 走默认）。注册的几种写法（3.7+）：显式指定类型 @f.register(int)、从类型注解推断 @f.register def _(x: int)、一个实现注册多个类型（堆叠 @f.register(int) + @f.register(float)）。内省：f.dispatch(int)（查 int 分派到哪个实现）、f.registry（所有注册映射）。理解「用法:①@singledispatch 定默认兜底②@f.register(类型)注册各实现(函数名用_)③调用自动按类型分派;注册可显式类型/注解推断/堆叠多类型;f.dispatch/f.registry 内省」，就掌握了用法。

三、单分派 vs 多分派

理解「单」分派的含义：

"单分派（single dispatch）"：只按"一个参数"的类型分派
  singledispatch 只看"第一个位置参数"的类型
  → 根据第一个参数选实现，其余参数不参与选择

  @process.register(int)
  def _(x, y, z): ...    # 只看 x 的类型（y、z 不影响分派）

"多分派（multiple dispatch）"：按"多个参数"的类型组合分派
  根据多个参数的类型组合选实现
  process(int, str) 和 process(int, list) 走不同实现
  → Python 标准库不提供（需要第三方库如 multipledispatch）

为什么标准库只做单分派：
  ① 单分派覆盖了大多数需求（按主对象类型分派）
  ② 多分派实现复杂、类型组合爆炸
  ③ 单分派简单清晰

只按第一个参数：
  def f(a, b): ...
  → 只有 a 的类型决定走哪个实现
  → 想按 b 的类型分派？singledispatch 做不到（用多分派库或手动）

类比：
  单分派 ≈ 面向对象的"方法分派"（按 self 的类型选方法）
  实际上 singledispatch 就是把"OOP 的多态"用在函数上
  obj.method() 按 obj 类型选 → f(obj) 按 obj 类型选

所以单分派只按第一个参数类型分派(其余不参与),多分派按多参数组合(标准库不提供)

「单分派（single dispatch）」：只按「一个参数」的类型分派——singledispatch 只看「第一个位置参数」的类型（根据第一个参数选实现、其余参数不参与选择，@process.register(int) def _(x, y, z) 只看 x 的类型）。「多分派（multiple dispatch）」：按「多个参数」的类型组合分派（process(int, str) 和 process(int, list) 走不同实现、Python 标准库不提供、需要第三方库如 multipledispatch）。为什么标准库只做单分派：① 单分派覆盖大多数需求、② 多分派实现复杂（类型组合爆炸）、③ 单分派简单清晰。类比：单分派 ≈ 面向对象的「方法分派」（按 self 的类型选方法）——singledispatch 就是把「OOP 的多态」用在函数上（obj.method() 按 obj 类型选、f(obj) 按 obj 类型选）。理解「单分派只按第一个参数类型分派(其余不参与);多分派按多参数组合(标准库不提供、要第三方库);单分派覆盖多数需求+简单;类似 OOP 多态用在函数上」，就掌握了单分派 vs 多分派。

四、按 MRO 匹配与继承

理解类型匹配规则：

按 MRO（方法解析顺序）匹配：
  传入的对象类型，会沿"继承链"找最接近的注册类型

  @f.register(int)
  def _(x): return "int impl"

  f(True)   # bool 是 int 的子类
  → 没注册 bool，但 bool 的 MRO 是 [bool, int, object]
  → 找到 int 的实现 → "int impl"

匹配规则：
  ① 精确匹配注册的类型 → 用那个实现
  ② 没精确匹配 → 沿 MRO 找最近的已注册祖先类型
  ③ 都没有 → 用默认（@singledispatch 的主函数）

例子：
  @f.register(Animal)  # 注册基类
  def _(x): ...
  f(Dog())   # Dog 继承 Animal → 走 Animal 实现（未注册 Dog）
  → 注册基类，所有子类自动适用（除非子类另有注册）

注册抽象基类（ABC）：
  @f.register(numbers.Integral)  # 抽象基类
  def _(x): ...
  → int、bool 等都匹配（因为是 Integral 的虚子类）
  → 用 ABC 注册能覆盖一族类型

注册 collections.abc：
  @f.register(list) 只匹配 list
  @f.register(collections.abc.Sequence) 匹配所有序列
  → 用抽象基类注册更通用

歧义（多个祖先都注册）：
  按 MRO 顺序，取最先匹配的（最具体的）

所以按 MRO 匹配:沿继承链找最近的已注册类型;注册基类/ABC 覆盖一族子类

按 MRO（方法解析顺序）匹配：传入的对象类型会沿「继承链」找最接近的注册类型（@f.register(int) 时 f(True)——bool 是 int 子类、MRO 是 [bool, int, object]、找到 int 的实现）。匹配规则：① 精确匹配注册的类型 → 用那个实现、② 没精确匹配 → 沿 MRO 找最近的已注册祖先类型、③ 都没有 → 用默认。例子：@f.register(Animal) 注册基类、f(Dog()) 走 Animal 实现（Dog 继承 Animal、未注册 Dog）——注册基类所有子类自动适用。注册抽象基类（ABC）：@f.register(numbers.Integral) 时 int/bool 都匹配、@f.register(collections.abc.Sequence) 匹配所有序列（用抽象基类注册更通用）。歧义（多个祖先都注册）：按 MRO 顺序取最先匹配的（最具体的）。理解「按 MRO 匹配:沿继承链找最近的已注册类型(bool 走 int 实现);规则精确匹配/沿 MRO 找祖先/默认;注册基类/ABC(numbers.Integral、abc.Sequence)覆盖一族子类」，就掌握了 MRO 匹配。

五、singledispatchmethod 与陷阱

理解类方法版本和常见坑：

类里的方法用 singledispatchmethod（3.8+）：
  普通 singledispatch 用在方法上会出错：
  → 因为方法第一个参数是 self，singledispatch 会按 self 的类型分派（错）

  正确用 singledispatchmethod：
  from functools import singledispatchmethod
  class Formatter:
      @singledispatchmethod
      def format(self, arg):
          raise NotImplementedError
      @format.register(int)
      def _(self, arg):        # 按第二个参数（arg）的类型分派
          return f"int: {arg}"
      @format.register(str)
      def _(self, arg):
          return f"str: {arg}"
  → singledispatchmethod 跳过 self，按第一个"真实参数"分派

陷阱1：只看第一个参数
  singledispatch 只按第一个位置参数分派
  → 关键字参数、其余位置参数不参与
  f(1, "x")  # 只看 1 的类型（int）

陷阱2：不能按值分派，只能按类型
  singledispatch 按"类型"分派，不能按"值"（如 x==0）
  → 值分派要自己 if

陷阱3：函数名 _ 只是惯例
  @f.register 的函数名会被覆盖（一般用 _）
  → 若想单独用可给真名

陷阱4：泛型类型（3.11+ 才支持部分）
  @f.register(list[int]) 老版本不支持（只能 list）
  → 泛型参数化类型分派有限

所以 singledispatchmethod 用于类方法(跳过 self);陷阱:只看第一个位置参数、只按类型不按值

类里的方法用 singledispatchmethod（3.8+）：普通 singledispatch 用在方法上会出错（方法第一个参数是 self、会按 self 的类型分派、错），正确用 singledispatchmethod——@singledispatchmethod def format(self, arg) + @format.register(int) def _(self, arg)（跳过 self、按第一个「真实参数」arg 分派）。陷阱1：只看第一个参数（关键字参数、其余位置参数不参与）。陷阱2：不能按值分派，只能按类型（不能按 x==0、值分派要自己 if）。陷阱3：函数名 _ 只是惯例（register 的函数名会被覆盖、一般用 _）。陷阱4：泛型类型分派有限（@f.register(list[int]) 老版本不支持、只能 list）。理解「singledispatchmethod 用于类方法(跳过 self、按第一个真实参数);陷阱:只看第一个位置参数(关键字/其余不参与)、只按类型不按值、函数名_是惯例、泛型分派有限」，就掌握了类方法版本和陷阱。

六、总结与实践

总结 singledispatch：

核心：
  singledispatch 按"第一个参数的类型"分派到不同实现
  = Python 版的"函数重载"（按类型）

用法：
  @singledispatch def f(arg): ...    # 默认/兜底
  @f.register(int) def _(arg): ...   # 注册类型实现
  f(x)  # 按 x 的类型自动分派

特性：
  单分派（只看第一个参数、其余不参与）
  按 MRO 匹配（子类用父类实现、注册 ABC 覆盖一族）
  可扩展（新增类型只 register 一个，不改原函数）

vs if-isinstance 链：
  isinstance 链：违反开闭、集中、难读、难扩展第三方
  singledispatch：注册式、可扩展、清晰

适用场景：
  ① 同一操作、不同类型不同实现（序列化、格式化、可视化）
  ② 需要为第三方类型扩展处理（register 即可）
  ③ 替代长长的 isinstance 分支

不适用：
  按"值"分派（用 if）、按"多个参数"分派（用多分派库）

类方法：用 singledispatchmethod（3.8+，跳过 self）

核心总结：
  singledispatch 按第一个参数类型分派（Python 函数重载）
  @singledispatch + @f.register(类型)
  替代 isinstance 链、可扩展、按 MRO 匹配

所以 singledispatch 按第一个参数类型分派,替代 isinstance 链,可扩展

核心：singledispatch 按「第一个参数的类型」分派到不同实现（Python 版函数重载）。用法：@singledispatch def f(arg)（默认兜底）+ @f.register(int) def _(arg)（注册类型实现）+ f(x)（自动分派）。特性：单分派（只看第一个参数）、按 MRO 匹配（子类用父类实现、注册 ABC 覆盖一族）、可扩展（新增类型只 register、不改原函数）。vs if-isinstance 链：isinstance 链违反开闭/难扩展、singledispatch 注册式可扩展清晰。适用场景：同一操作不同类型不同实现（序列化/格式化）、为第三方类型扩展、替代长 isinstance 分支。不适用：按值分派（用 if）、按多参数分派（用多分派库）。类方法：用 singledispatchmethod（3.8+）。理解「singledispatch 按第一个参数类型分派(Python 函数重载);@singledispatch+@f.register(类型);替代 isinstance 链可扩展、按 MRO 匹配;适用序列化/格式化/扩展第三方;类方法用 singledispatchmethod」，就掌握了总结与实践。

记忆钩子：「functools.singledispatch 是『单分派泛型函数』——根据『第一个参数的类型』自动选择不同的实现,实现 Python 版的『函数重载』(Python 本身不支持像 Java 那样同名函数按参数类型选,后定义的会覆盖前面的);★三步用法:①@singledispatch 装饰主函数(默认/兜底实现)②@主函数.register(类型)注册各类型的专门实现(函数名用_,或用 @f.register 从类型注解推断,或堆叠注册多个类型)③正常调用 f(x),按 x 的类型自动分派;★核心价值:替代『一长串 if isinstance(x,int):…elif isinstance(x,str):…』,让『按类型处理』的代码可扩展——新增一个类型只需 register 一个函数、完全不改原函数(符合开闭原则),清晰;★为什么叫『单』分派:只按第一个位置参数的类型分派(其余参数不参与选择),多分派(按多个参数类型组合)Python 标准库不提供;★按 MRO 匹配:没精确匹配就沿继承链找最近的已注册祖先(bool 会走注册的 int 实现),注册基类/抽象基类(numbers.Integral、collections.abc.Sequence)能覆盖一族子类;类里的方法要用 singledispatchmethod(3.8+,跳过 self、按第一个真实参数分派);陷阱:只能按类型不能按值分派」。

七、常见误区与追问

误区：Python 支持像 Java 那样定义多个同名函数做重载。 不支持——在 Python 里 def f(x): ... 后面再 def f(x): ... 只是把名字 f 重新绑定到第二个函数、第一个被覆盖，最终只有一个 f 存在；Python 没有编译期的「按参数类型选函数」的重载；要实现「同名操作、不同类型不同行为」，传统靠运行时 isinstance 判断，或者用 functools.singledispatch（按第一个参数类型分派）。
误区：singledispatch 会根据所有参数的类型来选实现。 只根据「第一个位置参数」的类型——这就是「单分派」的含义，其余的位置参数和关键字参数都不参与选择实现；f(1, "x", [2]) 只看第一个参数 1 的类型（int）来决定走哪个实现；如果需要根据多个参数的类型组合来分派（多分派），Python 标准库不提供，要用第三方库（如 multipledispatch）。
误区：register 时函数名要和主函数一样。 不需要、也不该——注册的实现函数名通常用 _（下划线），因为 @f.register(int) 会把这个函数收进 f 的注册表、函数名本身不重要（甚至会污染命名空间）；写 @to_json.register(int) def _(obj): ... 是惯例；如果你确实想让某个实现也能单独按名字调用，可以给它一个真实的名字，但一般没必要。
误区：singledispatch 可以用在类的实例方法上。 直接用会出错——普通 singledispatch 按「第一个位置参数」分派，而实例方法的第一个参数是 self，它会尝试按 self（也就是实例本身）的类型分派、而不是你想要的业务参数类型，导致分派错误；类的方法要用 functools.singledispatchmethod（Python 3.8+），它会跳过 self、按第一个「真实参数」的类型分派；所以在类里做类型分派方法用 singledispatchmethod。
追问：singledispatch 相比一长串 if-isinstance 有什么好处？ 主要是「可扩展性和清晰度」：① 符合开闭原则——新增一个类型的处理只需 @f.register(新类型) def _(x): ... 注册一个函数，完全不用修改原来的主函数或其他分支；而 isinstance 链每加一个类型都要去改那个大函数、加一个 elif；② 分散而清晰——每个类型的处理逻辑是独立的小函数、职责单一，不像 isinstance 链把所有类型逻辑挤在一个函数里越来越长；③ 能为第三方类型扩展——你可以对别人库里的函数（如果它用了 singledispatch）register 你自己的类型处理，而 isinstance 链你改不了别人的函数；④ 按 MRO 自动匹配继承——注册基类，所有子类自动适用；所以「同一操作、多种类型、可能持续新增类型」的场景（序列化、格式化、可视化转换等）用 singledispatch 比 isinstance 链优雅得多。
追问：如果传入的类型没有精确注册，singledispatch 怎么选实现？ 按 MRO（方法解析顺序）沿继承链找「最接近的已注册祖先类型」：先看有没有精确注册这个类型的实现，没有就沿着这个类型的 MRO（继承链）往上找、用第一个匹配到的已注册祖先类型的实现，如果一直找到 object 都没有匹配，就用 @singledispatch 装饰的主函数（默认/兜底实现）；比如注册了 int 的实现、传入 bool（bool 是 int 的子类），因为没注册 bool、会沿 bool 的 MRO [bool, int, object] 找到 int 的实现；这个特性很有用——注册一个基类或抽象基类（如 collections.abc.Sequence、numbers.Number）就能让它的所有子类/虚子类自动走同一个实现、覆盖一整族类型。
追问：singledispatch 能不能按参数的「值」分派（比如 x==0 走一个实现、x>0 走另一个）？ 不能——singledispatch 只能按「类型」分派、不能按「值」分派；它看的是 type(第一个参数)、然后在注册表里按类型匹配实现，无法根据参数是 0 还是正数、是空列表还是非空列表这类「值的条件」来选；如果需要按值分派，还是得在实现里自己写 if 判断值；singledispatch 的定位是「按类型的多态」（类似 OOP 里按对象类型选方法），值层面的分支逻辑不在它的能力范围内；同理它也不能按参数的个数或关键字参数来分派。

八、加强记忆

functools.singledispatch 是「单分派泛型函数」——根据「第一个参数的类型」自动选择不同的实现，实现 Python 版的「函数重载」（Python 本身不支持像 Java 那样同名函数按参数类型选、后定义的会覆盖前面的）。三步用法：① @singledispatch 装饰主函数（默认/兜底实现）、② @主函数.register(类型) 注册各类型的专门实现（函数名用 _，或 @f.register 从类型注解推断，或堆叠注册多个类型）、③ 正常调用 f(x) 按 x 的类型自动分派。核心价值：替代「一长串 if isinstance(x, int): ... elif isinstance(x, str): ...」，让「按类型处理」的代码可扩展——新增一个类型只需 register 一个函数、完全不改原函数（符合开闭原则）。为什么叫「单」分派：只按第一个位置参数的类型分派（其余参数不参与选择），多分派（按多个参数类型组合）Python 标准库不提供。按 MRO 匹配：没精确匹配就沿继承链找最近的已注册祖先（bool 会走注册的 int 实现），注册基类/抽象基类（numbers.Integral、collections.abc.Sequence）能覆盖一族子类。类里的方法要用 singledispatchmethod（3.8+，跳过 self）；陷阱：只能按类型不能按值分派。一句话「singledispatch 按第一个参数的类型分派到不同实现(Python 函数重载);@singledispatch 定默认+@f.register(类型)注册各实现;替代 if-isinstance 链、可扩展(新增类型只 register 不改原函数)、按 MRO 匹配子类;类方法用 singledispatchmethod、只按类型不按值分派」。

简化版

详细版