Python functools.singledispatch 怎样按参数类型选择函数

当一个函数需要同时处理整数、映射和普通对象时，最容易写成一串 isinstance() 分支。分支少时问题不大，但类型越来越多后，主函数会同时承担分派、业务处理和默认行为。Python 的 functools.singledispatch 可以把这个决策拆开：保留一个默认实现，再按第一个参数的类型注册专用实现。

官方文档：https://docs.python.org/3/library/functools.html

singledispatch 只根据第一个参数的类型选择实现；没有更具体的注册项时，会沿类型关系寻找可用实现，最后回退到默认的 object 实现。关键是把“选择哪个函数”交给注册表，把每个类型的业务写在自己的函数里。

先确定 singledispatch 的选择边界

这里的 single 指的是单参数分派。被装饰的公共函数仍然是调用入口，但真正选择实现时只看第一个位置参数的类型。第二个参数可以继续作为普通业务参数传入，却不会参与类型选择。

这意味着它适合“同一动作面对不同输入类型有不同处理方式”的接口，例如把值转换成说明文本、把不同消息对象交给对应的序列化逻辑。若选择条件是多个字段的组合、数值范围或运行时状态，直接写清晰的普通分支往往更容易维护。

用默认函数和 register 拆开类型实现

下面先保留一个默认实现，再给整数和映射类型注册专用函数。默认函数就是最宽的 object 处理方式，因此没有注册专用实现的输入仍然有明确行为。

from collections.abc import Mapping
from functools import singledispatch

@singledispatch
def describe(value, verbose=False):
    # 默认实现覆盖 object，负责处理未单独注册的类型。
    text = f"普通对象：{value!r}"
    return f"{text}（详细模式）" if verbose else text

@describe.register
def _(value: int, verbose=False):
    # 类型注解让 register 自动把第一个参数绑定到 int。
    text = f"整数：{value}"
    return f"{text}（详细模式）" if verbose else text

@describe.register
def _(value: Mapping, verbose=False):
    # Mapping 适合接住 dict 等虚拟子类，而不是只匹配一个具体类。
    text = f"映射：{len(value)} 个键"
    return f"{text}（详细模式）" if verbose else text

# verbose 是普通业务参数，不会改变类型分派对象。
describe(7, verbose=True)
describe({"lang": "Python"})
describe(["a", "b"])

注册函数的第一个参数必须对应分派类型；verbose 只是被选中实现继续使用的参数。列表没有专门注册项时，会走默认实现。若不想依赖注解，也可以写成 @describe.register(int)，把类型直接放在装饰器参数中。

用 dispatch 和 registry 看清实际选择

“我注册过了”和“这个类型会命中它”不是一回事。调试分派规则时，可以用 dispatch(type) 查询某个类型将使用的函数，用只读的 registry 查看目前登记过的类型。

# 查询具体类型对应的实现函数，不需要构造一个真实业务对象。
int_handler = describe.dispatch(int)
dict_handler = describe.dispatch(dict)

# registry.keys() 便于记录当前注册范围；object 通常是默认实现。
registered_types = list(describe.registry.keys())

print(int_handler.__name__)
print(dict_handler.__name__)
print(registered_types)

dict 没有单独注册时，查询结果可能是 Mapping 的实现，因为 dict 满足这个抽象基类；如果没有任何更具体的匹配，就会回到默认函数。这个查询接口很适合写启动期诊断日志或针对分派规则的单元测试，但不需要把整个注册表暴露给业务调用方。

继承、抽象基类和 bool 要特别留意

分派不是简单的字典查找。官方文档说明，找不到精确类型时会根据方法解析顺序寻找更通用的注册项；注册到抽象基类的实现也可以接收它的虚拟子类。因此注册 Mapping 通常比只注册 dict 更能表达“所有映射对象都使用这套逻辑”。

另一个常见边界是 bool。在 Python 的类型关系中，bool 是 int 的子类。如果只注册了 int，布尔值可能命中整数实现；如果布尔值需要不同语义，就显式注册 bool，让更具体的实现表达真实业务意图。

@describe.register(bool)
def _(value, verbose=False):
    # bool 与 int 有继承关系；单独注册后可以避免语义混用。
    return "布尔值：真" if value else "布尔值：假"

# 只查看规则，不把调用过程改写成多个 isinstance 分支。
bool_handler = describe.dispatch(bool)
print(bool_handler.__name__)

如果类型层级重叠较多，建议先列出“默认类型、抽象基类、具体类型”三层边界，再决定是否注册。不要为了消灭一两个分支而把复杂的多参数决策硬塞进 singledispatch。

接口设计时怎么选

落地时可以按“默认行为先行、专用类型后加、调试查询收口”的顺序设计。默认实现保证接口不会因为遗漏注册而失控，专用实现保持职责单一，dispatch() 和 registry 则让类型规则能够被解释和测试。

常见疑问

singledispatch 会根据第二个参数类型选择函数吗？

不会。它只看第一个参数；第二个参数仍会传给最终函数，但不参与实现选择。

没有注册某个具体类型时一定报错吗？

不一定。只要默认函数存在，未命中的类型会沿类型关系寻找更通用的实现，最终通常回退到默认的 object 实现。

什么时候应该用 singledispatchmethod？

当分派入口是类方法或实例方法，并且你希望按第一个业务参数类型选择实现时，可以考虑它；普通函数则使用 singledispatch 更直接。

总结一下，functools.singledispatch 解决的是“一个入口、多个按类型组织的实现”问题。先写默认函数，再用 register 扩展具体类型；遇到继承或抽象基类时用 dispatch(type) 和 registry 把实际规则讲清楚。只要分派条件不是多参数组合或数值范围，它就能让类型边界比一长串 isinstance() 更集中。