Python functools.singledispatch 如何按参数类型分派：注册顺序、继承匹配与调试

消息格式化函数一开始只有字符串，后来又要处理整数、日期和自定义事件。把所有判断都塞进一个 if isinstance(...) 里，新增类型时很容易改坏旧分支。functools.singledispatch 给出的答案是：保留一个默认实现，再用 register 为第一个参数的类型挂载专门实现。

singledispatch 只看被装饰函数的第一个参数类型；先调用默认实现，再按注册表和类型继承关系选择最匹配的实现。调试时用 dispatch 直接检查某个类型最终会命中哪个函数。

先把一个混乱的判断函数拆开

假设服务要把不同事件转换成日志短句。最小实现可以让字符串走默认逻辑，整数表示重试次数，Alert 表示需要提醒的业务事件：

from functools import singledispatch

@singledispatch
def describe(value):
    return f"未分类事件: {value!r}"

@describe.register
def _(value: int):
    return f"重试次数: {value}"

class Alert:
    def __init__(self, code):
        self.code = code

@describe.register
def _(value: Alert):
    return f"告警代码: {value.code}"

print(describe("connected"))
print(describe(2))
print(describe(Alert("E42")))

这里的 describe 是对外调用入口，字符串没有专门注册，所以落到默认实现；int 和 Alert 则分别命中自己的函数。注册函数写成下划线只是习惯，真正被保存的是分派实现。

注册表真正看的是第一个参数

singledispatch 的“single”不是只允许一个参数，而是只把第一个位置参数作为分派依据。后面的参数仍然可以承载上下文：

@singledispatch
def render(value, prefix="事件"):
    return f"{prefix}: {value!r}"

@render.register
def _(value: int, prefix="事件"):
    return f"{prefix}数量: {value}"

print(render(3, prefix="批次"))

调用 render(3, prefix="批次") 时，3 决定实现，prefix 只是传给已经选中的实现。不要试图让第二个参数也参与选择；如果业务确实需要多个维度，应另建明确的分派键或使用专门的多分派方案。

没有直接注册时，继承关系会接管选择

维护过程中常见一个误判：注册了基类，以为所有子类都会落回默认实现。实际上，注册表会结合类型继承关系寻找可用实现。

class Event:
    pass

class LoginEvent(Event):
    pass

@singledispatch
def route(value):
    return "default"

@route.register
def _(value: Event):
    return "event"

print(route(LoginEvent()))
print(route.dispatch(LoginEvent()).__name__)

LoginEvent 没有直接注册，但它继承自 Event，因此结果是 event。如果后来为 LoginEvent 增加专门实现，命中关系就会更具体。这个行为适合把通用兜底放在基类、少数特殊事件单独覆盖。

用 dispatch 把“到底命中了谁”查清楚

不要只看输出字符串来猜注册是否生效。dispatch 接收一个类型，返回最终使用的函数对象；这对单元测试和排查导入顺序问题都很直接。

handler = route.dispatch(LoginEvent)
assert handler(LoginEvent()) == "event"
print(handler.__name__)

注意传给 dispatch 的是 LoginEvent 这个类型，而不是 LoginEvent() 实例。若把实例传进去，会得到参数类型错误；若返回的是默认函数，优先检查注册装饰器是否写在可导入路径上，以及实现函数的第一个参数注解是否为预期类型。

注册顺序和实现边界怎么定

工程里更稳妥的做法是把注册集中在模块初始化区域，避免某个插件只有被导入后才完成注册，却没有在测试中显式导入。注册逻辑越分散，越应该给每个关键类型加一条 dispatch 断言。

常见问题

singledispatch 能根据两个参数一起选择吗？

不能。它只依据第一个参数类型，第二个及后续参数不会改变分派结果。

为什么子类没有注册也能命中实现？

因为分派会沿继承关系寻找可用实现，子类可以复用已注册基类的处理函数。

怎么确认某个类型的实现已生效？

调用 describe.dispatch(SomeType) 或 route.dispatch(SomeType)，再检查返回函数的名称或直接执行它。

把分派规则变成可维护的检查点

实际使用时可以记住三件事：默认实现负责兜底，register 负责扩展，第一个参数决定入口。新增类型后先写一个最小调用，再用 dispatch 核对函数对象；如果类型层级较深，再补一个继承场景测试。这样分派表的变化会有明确证据，不需要靠日志输出猜测。