用 Python init_subclass 实现处理器自动注册

问题场景

在处理命令路由、消息回调或插件扩展时，常见写法是先定义一批处理器类，再在模块末尾手动维护注册字典：

HANDLERS = {}
class EchoHandler:
    ...
HANDLERS['echo'] = EchoHandler

这种写法的问题很直接：新增处理器需要改两处，容易漏注册；分散修改核心注册字典容易产生冲突；测试时注册表状态也不够清晰。可以利用 Python 的 __init_subclass__，在子类创建时自动完成注册。

__init_subclass__ 是基类提供的钩子，子类定义完成时被调用。它不需要自定义元类，适合普通类层次。把注册逻辑放进 Handler 基类，新增处理器只要继承并声明 name，注册表自动更新。

最小可运行示例

下面示例包含注册表、重复名称检测、按名称分发和未知名称处理。保存为 handler_registry.py：

from __future__ import annotations
from typing import Any

class Handler:
    registry: dict[str, type['Handler']] = {}
    name: str = ''

    def __init_subclass__(cls, **kwargs: Any) -> None:
        super().__init_subclass__(**kwargs)
        raw_name = cls.__dict__.get('name')
        if not isinstance(raw_name, str) or not raw_name.strip():
            raise TypeError(f'{cls.__name__} 必须显式定义非空字符串 name')
        handler_name = raw_name.strip()
        if handler_name in Handler.registry:
            old = Handler.registry[handler_name]
            raise ValueError(
                f'处理器名称重复: {handler_name!r} 已被 {old.__name__} 使用，'
                f'当前类为 {cls.__name__}'
            )
        Handler.registry[handler_name] = cls
        cls.name = handler_name

    @classmethod
    def create(cls, name: str) -> 'Handler':
        try:
            handler_cls = cls.registry[name]
        except KeyError as exc:
            raise KeyError(f'未知处理器: {name!r}') from exc
        return handler_cls()

    def handle(self, payload: dict[str, Any]) -> str:
        raise NotImplementedError

class EchoHandler(Handler):
    name = 'echo'
    def handle(self, payload: dict[str, Any]) -> str:
        return str(payload.get('text', ''))

class UpperHandler(Handler):
    name = 'upper'
    def handle(self, payload: dict[str, Any]) -> str:
        return str(payload.get('text', '')).upper()

def dispatch(name: str, payload: dict[str, Any]) -> str:
    return Handler.create(name).handle(payload)

if __name__ == '__main__':
    try:
        class DuplicateUpper(Handler):
            name = 'upper'
    except ValueError as exc:
        print('重复检测:', exc)

    print(dispatch('echo', {'text': 'hello'}))
    print(dispatch('upper', {'text': 'hello'}))

    try:
        dispatch('missing', {})
    except KeyError as exc:
        print('未知分发:', exc)

关键点：

• raw_name = cls.__dict__.get('name') 要求每个具体处理器显式声明名称，避免从父类意外继承名称。
• 注册发生在类创建阶段，类定义本身失败会抛出 TypeError 或 ValueError，适合尽早暴露配置错误。
• dispatch 只依赖 Handler.create，不需要知道注册字典在哪里维护。
• 这里使用基类 Handler.registry 而不是 cls.registry，避免子类意外覆盖注册表引用。若项目设计允许每个处理器族独立注册表，可以改为 cls.registry，但要明确继承语义。

运行方法

在命令行执行：

python handler_registry.py

预期会看到重复名称的异常信息、两个正常分发的返回值，以及未知处理器提示。示例中的处理器名称 echo、upper 和输入文本 hello 都是演示用占位值，替换为实际业务名称即可。

边界与限制

1. 注册时机依赖导入。子类必须被导入，__init_subclass__ 才会执行。插件目录需要显式扫描并导入模块，或借助包初始化逻辑导入。
2. 同名处理器会直接失败。热重载、测试中重复导入同名模块时，需要清理注册表或使用独立注册表实例，不能依赖覆盖。
3. 抽象中间基类要处理。若存在不直接工作的中间基类，可约定 name = None 时不注册，或者用额外类属性 abstract = True 跳过；最终具体类仍需显式声明唯一名称。
4. 线程与动态创建。类通常在导入期创建，静态注册足够简单；若运行时多线程动态创建子类，注册字典的写入需要同步保护。
5. 不要用注册顺序表达优先级。字典顺序不是业务优先级，需要优先级时应显式排序或增加权重字段。
6. 与元类混用时注意 super().__init_subclass__(**kwargs)，否则可能破坏其他基类的初始化链。

小结

__init_subclass__ 把处理器注册从手工维护字典前移到类定义阶段，新增处理器只需继承基类并声明 name。配合重名检测和按名称分发，可以让命令路由或消息处理代码更集中、更易扩展，同时要正视导入时机、重复导入和中间基类等边界。