Python functools.singledispatchmethod 如何让类方法按参数类型分派：注册顺序与继承边界

在消息入口里，字符串、整数和未知对象经常要走不同处理分支。如果把判断全堆在一个方法里，后续新增类型很容易改坏旧逻辑。functools.singledispatchmethod 可以保留一个统一的类方法入口，再按第一个非 self 或 cls 参数的运行时类型选择实现。

它适合把“统一接收消息”和“按类型处理消息”拆开，但注册的是运行时类型，不是泛型参数；bool 与 int 的注册顺序、装饰器嵌套位置和子类继承都要单独验收。

先把消息入口拆成 ingest、normalize 和 handle

假设一个事件类同时接收文本、整数状态码和未来尚未登记的对象。这里让 ingest 负责接收原始值，normalize 只做轻量整理，真正的类型分派集中在 handle。这样新增实现时，不必继续扩张一串 isinstance。

from functools import singledispatchmethod

class EventHandler:
    @singledispatchmethod
    def handle(self, value):
        return f"object:{value!r}"

    @handle.register
    def _(self, value: int):
        return f"int:{value + 1}"

    @handle.register
    def _(self, value: bool):
        return f"bool:{value}"

    def normalize(self, value):
        return value.strip() if isinstance(value, str) else value

    def ingest(self, value):
        return self.handle(self.normalize(value))

图中只保留正文里真实出现的节点：ingest 调用 normalize，再进入 handle；handle 依据类型选择 int、bool 或 object 实现。

注册完成后，dispatch 到底选择哪一个实现

运行检查不要只看返回字符串，还要用公开的 dispatch 属性检查选择结果。bool 虽然是 int 的子类，但显式注册了 bool 后，True 会优先走布尔实现。未知类型则沿方法解析顺序寻找更通用的实现，默认实现就是 object。

handler = EventHandler()
assert handler.ingest(3) == "int:4"
assert handler.ingest(True) == "bool:True"
assert handler.ingest({"kind": "unknown"}) == "object:{'kind': 'unknown'}"

assert handler.handle.dispatch(int).__name__ == "_"
assert handler.handle.dispatch(bool).__name__ == "_"
assert handler.handle.dispatch(dict)(handler, {"kind": "unknown"}) == "object:{'kind': 'unknown'}"

dispatch 是核对注册表的快速入口，实际调用仍然使用 handle。如果删掉 bool 注册，True 会按继承关系落到 int，这正是容易被测试遗漏的边界。

装饰器顺序和继承边界别混在一起

singledispatchmethod 必须包在外层

如果要和 classmethod 或 staticmethod 嵌套，singledispatchmethod 必须是最外层装饰器，这样类属性才暴露 register。把顺序反过来，类定义阶段就可能找不到注册入口。

class Parser:
    @singledispatchmethod
    @classmethod
    def parse(cls, value):
        return value

    @parse.register
    @classmethod
    def _(cls, value: int):
        return value + 1

子类新增注册要写在子类自己的分派器上

子类可以继续注册类型，常见做法是通过子类继承到的分派方法完成扩展，但要用小测试确认基类和子类的注册表没有被误认为一份全局配置。尤其不要把“能调用”当成“注册到了预期类”。

什么时候不该用 singledispatchmethod

如果分支依赖多个参数、业务状态或外部配置，单分派会把真正的决策隐藏在第一个参数类型后面；这时显式策略表或普通方法往往更直白。它也不理解 list[int] 的元素类型，运行时只会把整个值看作 list，类型注解不能改变这一点。

生产代码建议为每个注册实现保留独立测试，并用 dispatch 检查关键类型。这样升级 Python 或调整装饰器时，失败点会落在注册边界，而不是等到线上收到未知消息才暴露。

相关问题

singledispatchmethod 看哪个参数的类型？

实例方法看第一个非 self 参数，类方法看第一个非 cls 参数。

为什么 bool 不应该默认当成 int？

Python 的布尔值属于整数体系，但业务含义通常不同；显式注册 bool 才能让真假状态不误走数值分支。

没有注册类型时会发生什么？

分派器会沿类型的 MRO 找更通用的实现，最后使用默认的 object 实现。

小结

把入口收敛到 handle，用 register 添加类型实现，再用 dispatch 验证选择结果，是采用 singledispatchmethod 的最小闭环。真正需要守住的是三个边界：第一个非 self/cls 参数、装饰器外层顺序，以及从具体类型回退到 object 的路径。