别急着上 Metaclass：用 `__init_subclass__` 设计一套可测试的 Python 自动插件注册机制

别急着上 Metaclass：用 __init_subclass__ 设计一套可测试的 Python 自动插件注册机制

在 Python 里，一旦需求里出现“所有子类自动登记”“框架自动发现实现类”“插件只需要继承基类即可生效”这样的描述，很多有经验的开发者会立即想到一个词：

metaclass（元类）。

这个答案当然没错。

但问题是：真的每一次都需要 metaclass 吗？

从 Python 3.6 开始，__init_subclass__ 提供了一种明显更轻量的扩展机制。对于插件注册、策略类登记、序列化器发现、命令路由、任务处理器注册等大量实际场景，它往往比 metaclass 更简单、更容易测试，也更容易让团队成员看懂。

这篇 Python 实战文章，我们就围绕一个看似简单、实际很有深度的问题展开：

__init_subclass__ 能不能替代 metaclass？

我们不会只停留在语法层面，而是从一个真正可运行的自动插件系统开始，逐步处理三个工程中最容易踩坑的问题：

• 多重继承时，super() 到底该怎么调用？
• import 时自动注册，会产生什么副作用？
• 全局 registry 会污染测试，应该如何隔离？

如果你正在学习 Python 编程，这篇文章能帮你真正理解“类创建时发生了什么”；如果你已经在做框架、SDK、基础设施或中大型 Python 项目，希望其中关于继承协议、导入机制和测试架构的讨论，也能给你一些新的启发。

一、先看问题：我们到底想实现什么？

假设我们正在开发一个数据处理系统。

系统允许用户实现不同格式的处理插件：

class Plugin:
pass

class JsonPlugin(Plugin):
pass

class CsvPlugin(Plugin):
pass

我们希望框架能够自动获得：

{
"json": JsonPlugin,
"csv": CsvPlugin,
}

然后可以这样创建插件：

plugin_cls = Plugin.registry["json"]
plugin = plugin_cls()

最直接的实现方式可能是手动注册：

class Plugin:
registry = {}

@classmethod
def register(cls, name, plugin_cls):
cls.registry[name] = plugin_cls

class JsonPlugin(Plugin):
pass

Plugin.register("json", JsonPlugin)

代码没有问题，但随着插件越来越多，它会暴露几个缺点。

第一，声明插件和注册插件被拆成了两件事。

你很容易写出：

class XmlPlugin(Plugin):
pass

然后忘记：

Plugin.register("xml", XmlPlugin)

第二，框架使用者需要理解额外的注册 API。

第三，插件定义已经能够表达“我是一个 Plugin”，再要求开发者重复告诉系统一次，实际上增加了冗余。

理想状态应该是：

class JsonPlugin(Plugin):
name = "json"

类一创建，注册自动完成。

这正是 __init_subclass__ 非常擅长的场景。

二、__init_subclass__ 到底是什么？

先写一个最小例子：

class Plugin:
def __init_subclass__(cls, **kwargs):
super().__init_subclass__(**kwargs)
print("发现子类：", cls.__name__)

class JsonPlugin(Plugin):
pass

class CsvPlugin(Plugin):
pass

运行后得到：

发现子类： JsonPlugin
发现子类： CsvPlugin

这里有一个必须理解的关键点：

__init_subclass__ 不是在创建对象实例时执行，而是在创建子类时执行。

也就是说：

class JsonPlugin(Plugin):
pass

执行到这里时，JsonPlugin 类对象被创建。

随后 Python 会调用父类定义的：

Plugin.__init_subclass__()

所以可以把它理解成：

定义子类
↓
Python 创建 class 对象
↓
调用父类的 __init_subclass__
↓
执行校验、登记、配置等初始化逻辑

这使它天然适合：

插件注册
序列化器注册
命令 Handler 注册
ORM 子类检查
策略模式实现类登记
任务类型登记
协议实现检查

三、第一个版本：10 行代码完成自动注册

我们先实现最简单的插件系统：

class Plugin:
registry = {}

def __init_subclass__(cls, **kwargs):
super().__init_subclass__(**kwargs)

name = getattr(cls, "name", cls.__name__.lower())
Plugin.registry[name] = cls

定义插件：

class JsonPlugin(Plugin):
name = "json"

class CsvPlugin(Plugin):
name = "csv"

查看 registry：

print(Plugin.registry)

结果类似：

{
"json": <class '__main__.JsonPlugin'>,
"csv": <class '__main__.CsvPlugin'>
}

于是插件创建可以变成：

plugin_cls = Plugin.registry["json"]
plugin = plugin_cls()

进一步封装：

class Plugin:
registry = {}

def __init_subclass__(cls, **kwargs):
super().__init_subclass__(**kwargs)

name = getattr(cls, "name", cls.__name__.lower())
Plugin.registry[name] = cls

@classmethod
def create(cls, name, *args, **kwargs):
try:
plugin_cls = cls.registry[name]
except KeyError:
raise ValueError(f"未知插件：{name}") from None

return plugin_cls(*args, **kwargs)

现在：

plugin = Plugin.create("json")

一个最基础的 Factory + Registry 组合就形成了。

四、不要滥用类属性：把插件元数据写进声明

实际框架中，经常希望这样写：

class JsonPlugin(Plugin, name="json"):
pass

而不是：

class JsonPlugin(Plugin):
name = "json"

__init_subclass__ 同样支持。

class Plugin:
registry = {}

def __init_subclass__(cls, name=None, **kwargs):
super().__init_subclass__(**kwargs)

plugin_name = name or cls.__name__.lower()
Plugin.registry[plugin_name] = cls

然后：

class JsonPlugin(Plugin, name="json"):
pass

class CsvPlugin(Plugin, name="csv"):
pass

这个设计很有意思。

这里的：

name="json"

不是实例构造函数：

__init__()

的参数，而是类声明阶段的参数。

整个语义非常自然：

class JsonPlugin(Plugin, name="json"):

几乎可以读成：

创建一个 Plugin 子类，它在插件系统里的名称叫 json。

相比元类，这种 DSL 风格通常更容易理解。

五、生产版本不能直接覆盖：处理插件名冲突

上一版代码存在一个危险问题：

Plugin.registry[plugin_name] = cls

如果两个人都注册 "json"：

class JsonPluginV1(Plugin, name="json"):
pass

class JsonPluginV2(Plugin, name="json"):
pass

那么 V2 会悄无声息覆盖 V1。

在框架代码里，这通常是非常糟糕的行为。

更合理的是 fail fast：

class Plugin:
registry = {}

def __init_subclass__(cls, name=None, **kwargs):
super().__init_subclass__(**kwargs)

plugin_name = name or cls.__name__.lower()

if plugin_name in Plugin.registry:
old = Plugin.registry[plugin_name]
raise ValueError(
f"插件名称冲突：{plugin_name!r}，"
f"已经由 {old.__module__}.{old.__qualname__} 注册"
)

Plugin.registry[plugin_name] = cls

这样错误会在类定义时立刻暴露，而不是运行几小时之后，在某个业务请求里突然发现使用了错误插件。

这是一个值得记住的 Python 最佳实践：

能够在声明阶段发现的配置错误，不要拖到运行阶段。

六、抽象基类怎么办？不是每个子类都应该注册

进一步考虑：

class DatabasePlugin(Plugin):
pass

class MySQLPlugin(DatabasePlugin):
pass

DatabasePlugin 可能只是一个中间基类，并不是真正可执行的插件。

如果所有子类全部自动注册，就会产生无效条目。

可以使用 abc：

from abc import ABC, abstractmethod

class Plugin(ABC):
registry = {}

def __init_subclass__(cls, name=None, **kwargs):
super().__init_subclass__(**kwargs)

if name is not None:
Plugin.registry[name] = cls

@abstractmethod
def run(self, data):
...

中间基类：

class DatabasePlugin(Plugin):
def connect(self):
print("connecting…")

具体插件：

class MySQLPlugin(DatabasePlugin, name="mysql"):
def run(self, data):
print("MySQL:", data)

这样可以规定：

只有显式提供 name 的类才参加注册。

在实际大型项目中，这往往比“所有子类自动注册”更安全。

七、关键追问：多重继承时 super() 怎么处理？

这部分是很多 __init_subclass__ 教程一笔带过，但工程中非常重要的问题。

假设有两个 mixin：

class LoggingMixin:
def __init_subclass__(cls, **kwargs):
print("LoggingMixin:", cls.__name__)
super().__init_subclass__(**kwargs)

class ValidationMixin:
def __init_subclass__(cls, **kwargs):
print("ValidationMixin:", cls.__name__)
super().__init_subclass__(**kwargs)

然后：

class Plugin(LoggingMixin, ValidationMixin):
pass

Python 使用的是 MRO：

print(Plugin.__mro__)

大致得到：

Plugin
LoggingMixin
ValidationMixin
object

因此调用链类似：

Plugin
↓
LoggingMixin.__init_subclass__
↓
ValidationMixin.__init_subclass__
↓
object.__init_subclass__

关键就在这一句：

super().__init_subclass__(**kwargs)

错误做法：直接点名父类

例如：

class LoggingMixin:
def __init_subclass__(cls, **kwargs):
ValidationMixin.__init_subclass__(**kwargs)

这种代码会破坏 cooperative multiple inheritance，也就是 Python 的协作式多重继承机制。

一旦继承顺序调整：

class Plugin(OtherMixin, LoggingMixin, ValidationMixin):
...

逻辑就可能彻底失效。

因此在设计可组合的 mixin 时，一个核心原则是：

super()

不是简单的：

调用我的父类

它真正表示的是：

把处理权交给 MRO 中的下一个实现。

这是理解 Python 多重继承最重要的思想之一。

八、__init_subclass__ 参数也必须协作消费

更加隐蔽的问题来自关键字参数。

假设：

class Plugin:
def __init_subclass__(cls, plugin_name=None, **kwargs):
...

另一个 mixin：

class RetryMixin:
def __init_subclass__(cls, retries=3, **kwargs):
...

于是：

class HttpPlugin(
RetryMixin,
Plugin,
retries=5,
plugin_name="http",
):
pass

推荐写法：

class RetryMixin:
def __init_subclass__(cls, retries=3, **kwargs):
cls.retries = retries
super().__init_subclass__(**kwargs)

class Plugin:
registry = {}

def __init_subclass__(cls, plugin_name=None, **kwargs):
super().__init_subclass__(**kwargs)

if plugin_name:
Plugin.registry[plugin_name] = cls

注意两个类都只消费自己认识的参数。

RetryMixin 拿走：

retries

剩下参数交给：

super().__init_subclass__(**kwargs)

Plugin 再消费：

plugin_name

这是一种非常漂亮的“参数管道”。

可以把它想象成：

class 声明 kwargs
│
▼
RetryMixin
消费 retries
│
▼
Plugin
消费 plugin_name
│
▼
object

最后到达 object.__init_subclass__() 时，不应该留下未知参数，否则可能出现：

TypeError: … takes no keyword arguments

因此实现 mixin 时最好始终遵守：

def __init_subclass__(cls, my_option=None, **kwargs):
...
super().__init_subclass__(**kwargs)

而不要轻易写：

def __init_subclass__(cls, **kwargs):
...

然后吞掉所有参数。

九、那它到底能不能替代 metaclass？

现在终于可以回答标题里的核心问题。

答案是：

很多场景能替代，但不能完全替代。

理解两者的关键，在于它们介入类创建流程的时间点不同。

简单表示：

class 语句
│
▼
准备 namespace
│
▼
执行 class body
│
▼
metaclass.__new__()
│
▼
类对象产生
│
▼
父类.__init_subclass__()
│
▼
class 创建完成

Metaclass 控制的是：

类是如何被制造出来的。

而 __init_subclass__ 解决的是：

我的子类创建出来之后，我要对它做什么。

因此，如果需求是：

发现子类
校验子类
登记子类
补充子类属性
限制接口
收集声明信息

优先考虑：

__init_subclass__

如果需求需要干预：

类对象真正的创建过程
namespace 的准备
自定义 class 构造规则
metaclass 级别操作符行为
复杂框架类模型

才更适合 metaclass。

例如元类：

class PluginMeta(type):
registry = {}

def __new__(mcls, name, bases, namespace, **kwargs):
cls = super().__new__(mcls, name, bases, namespace)

plugin_name = namespace.get("plugin_name")

if plugin_name:
mcls.registry[plugin_name] = cls

return cls

使用：

class Plugin(metaclass=PluginMeta):
pass

它当然能实现注册。

但如果需求只有“子类注册”，这种方案实际上引入了额外概念：

普通类
↓
元类
↓
元类创建类
↓
元类注册类

而 __init_subclass__ 可以直接表达：

父类
↓
子类创建
↓
父类登记子类

后者明显更贴近问题本身。

十、一个非常实用的设计原则

我在实际 Python 框架设计里通常采用下面这条判断标准：

能用 class decorator 解决的，不急着用 __init_subclass__；能用 __init_subclass__ 解决的，不急着用 metaclass。

可以粗略理解为复杂度阶梯：

普通函数
↓
Decorator
↓
__init_subclass__
↓
Descriptor
↓
Metaclass

这不是说 metaclass 不好。

恰恰相反，metaclass 非常强大。

问题在于：

框架能力越强，维护它所需的认知成本通常越高。

一个高级技巧真正成熟的标志，不是“我会使用它”，而是：

“我知道什么时候应该不用它。”

十一、第二个大坑：import 时注册有什么副作用？

现在假设项目结构如下：

project/
├── plugins/
│ ├── __init__.py
│ ├── json_plugin.py
│ └── csv_plugin.py
└── main.py

json_plugin.py：

from .base import Plugin

class JsonPlugin(Plugin, name="json"):
pass

你可能期待：

Plugin.registry

自动包含 "json"。

但是请注意：

__init_subclass__ 只有在 Python 执行 class 定义时才会运行。

如果：

json_plugin.py

从来没有被 import，那么：

class JsonPlugin(...)

根本没有执行。

自然也不会注册。

这意味着“自动注册”其实不是：

文件存在
→ 自动发现

而是：

模块被 import
→ class body 执行
→ 创建类
→ __init_subclass__
→ 注册

这一点极其重要。

十二、自动注册不等于自动发现

很多插件框架第一次实现时都会混淆两个概念：

注册 Registry

表示：

系统已经知道某个插件类

发现 Discovery

表示：

系统如何找到插件模块

__init_subclass__ 解决的是：

Registration。

它并不会替你完成：

Discovery。

因此你仍然需要解决“插件模块由谁 import”的问题。

最简单方案：

# plugins/__init__.py

from .json_plugin import JsonPlugin
from .csv_plugin import CsvPlugin

然后入口：

import plugins

所有插件就完成注册了。

但这又带来了新的问题：

import 产生了业务副作用。

十三、import side effect 到底有什么风险？

通常我们喜欢认为：

import module

只是在“加载代码”。

但 Python 的 import 实际上会执行模块顶层代码。

例如：

print("loading plugin")

class JsonPlugin(Plugin, name="json"):
pass

执行：

import json_plugin

不仅加载定义，还会触发：

print
class 创建
__init_subclass__
registry 修改

如果插件模块更激进：

db = connect_database()

client = HttpClient()

load_config()

register_metrics()

那么 import 一个模块甚至可能：

建立数据库连接
读取环境变量
访问网络
初始化线程
修改全局状态

这就是典型的 import-time side effect。

我的建议非常明确

插件模块的顶层代码应该尽可能接近：

import ...

CONSTANT = ...

class PluginImplementation(...):
...

避免：

client = connect()

更避免：

client.fetch_remote_config()

如果资源初始化比较重，应移动到实例构造或显式生命周期：

class HttpPlugin(Plugin, name="http"):
def __init__(self):
self.client = HttpClient()

甚至进一步：

class HttpPlugin(Plugin, name="http"):
def start(self):
self.client = HttpClient()

def stop(self):
self.client.close()

这样可以把：

插件发现

与：

插件启动

分开。

这是成熟插件系统非常重要的架构边界。

十四、不要靠扫描所有 .py 文件来“神奇发现”

有些开发者会写：

import pkgutil
import importlib

for _, module_name, _ in pkgutil.iter_modules(package.__path__):
importlib.import_module(f"{package.__name__}.{module_name}")

这确实可以自动扫描插件。

但是这种“魔法”有代价：

启动时间增加
不可预测的 import 顺序
隐藏副作用
异常定位困难
测试变慢
模块意外被加载

如果系统规模比较大，我更推荐显式发现机制。

例如配置：

PLUGINS = [
"myapp.plugins.json_plugin",
"myapp.plugins.csv_plugin",
]

启动：

from importlib import import_module

def load_plugins(plugin_modules):
for module_name in plugin_modules:
import_module(module_name)

这样你可以非常清楚地知道：

系统到底加载了哪些插件。

十五、第三个核心问题：全局 registry 如何污染测试？

现在看这段代码：

class Plugin:
registry = {}

它非常方便。

但从测试角度看，它是一个典型的 mutable global state。

例如测试 A：

def test_json_plugin():
class JsonPlugin(Plugin, name="json"):
pass

assert "json" in Plugin.registry

随后测试 B：

def test_registry_empty():
assert Plugin.registry == {}

测试 B 会失败。

因为测试 A 已经修改了：

Plugin.registry

更麻烦的是，测试结果可能依赖执行顺序：

pytest test_a.py test_b.py

失败。

但：

pytest test_b.py test_a.py

可能成功。

这是非常危险的测试污染。

十六、方案一：pytest fixture 清理 registry

最直接：

import pytest

@pytest.fixture(autouse=True)
def clean_plugin_registry():
Plugin.registry.clear()

yield

Plugin.registry.clear()

这样每个测试运行前后都会清理。

测试：

def test_register_plugin():
class DemoPlugin(Plugin, name="demo"):
pass

assert Plugin.registry["demo"] is DemoPlugin

另一个测试：

def test_registry_isolated():
assert Plugin.registry == {}

这是成本最低、非常实用的方案。

但它依赖测试纪律。

如果未来 registry 不再只是一个 dict，而是拥有缓存、索引、状态机，这种清理方式会越来越脆弱。

十七、方案二：测试时保存并恢复状态

如果测试不能简单地全部 clear()，可以 snapshot：

import pytest

@pytest.fixture
def isolated_registry():
old_registry = Plugin.registry.copy()

try:
Plugin.registry.clear()
yield Plugin.registry
finally:
Plugin.registry.clear()
Plugin.registry.update(old_registry)

使用：

def test_custom_plugin(isolated_registry):
class TestPlugin(Plugin, name="test"):
pass

assert "test" in isolated_registry

优点是测试结束后能够恢复原来的插件状态。

十八、方案三：真正工程化——Registry 本身做成对象

如果系统逐渐复杂，我不建议一直写：

Plugin.registry = {}

更好的设计是：

class PluginRegistry:
def __init__(self):
self._plugins = {}

def register(self, name, plugin_cls):
if name in self._plugins:
raise ValueError(f"重复插件：{name}")

self._plugins[name] = plugin_cls

def get(self, name):
return self._plugins[name]

def unregister(self, name):
self._plugins.pop(name, None)

def clear(self):
self._plugins.clear()

def __contains__(self, name):
return name in self._plugins

然后：

class Plugin:
registry = PluginRegistry()

def __init_subclass__(cls, name=None, **kwargs):
super().__init_subclass__(**kwargs)

if name:
Plugin.registry.register(name, cls)

这样做看似只是把 dict 包了一层，但它产生了非常大的设计收益。

以后你可以加入：

重复检测
日志
插件版本
优先级
别名
禁用状态
来源模块
插件元数据
统计信息
线程安全

而不需要修改所有调用方。

例如：

class PluginRegistry:
def register(self, name, plugin_cls):
...

以后可以扩展为：

def register(
self,
name,
plugin_cls,
*,
version=None,
priority=0,
):
...

十九、更进一步：不要让基类直接依赖全局 Registry

大型项目里我更偏爱依赖注入。

例如：

class PluginRegistry:
def __init__(self):
self._plugins = {}

def register(self, name, cls):
self._plugins[name] = cls

def get(self, name):
return self._plugins[name]

创建默认 registry：

default_registry = PluginRegistry()

基类：

class Plugin:
registry = default_registry

def __init_subclass__(cls, name=None, **kwargs):
super().__init_subclass__(**kwargs)

if name is not None:
cls.registry.register(name, cls)

测试中就可以创建专用基类：

def test_plugin_registration():
test_registry = PluginRegistry()

class TestPluginBase(Plugin):
registry = test_registry

class DemoPlugin(TestPluginBase, name="demo"):
pass

assert test_registry.get("demo") is DemoPlugin

但这里又藏着一个值得讨论的问题。

我们当前写的是：

cls.registry.register(...)

而不是：

Plugin.registry.register(...)

这两者区别非常大。

前者允许子类覆盖 registry：

class TestPluginBase(Plugin):
registry = test_registry

从而获得测试隔离。

后者会永远修改全局：

Plugin.registry

从框架可扩展性来说，通常：

cls.registry

会更加灵活。

二十、一个隐藏 BUG：中间基类可能继承错 registry

考虑：

class Plugin:
registry = PluginRegistry()

def __init_subclass__(cls, name=None, **kwargs):
super().__init_subclass__(**kwargs)

if name:
cls.registry.register(name, cls)

测试：

test_registry = PluginRegistry()

class TestPluginBase(Plugin):
registry = test_registry

class DemoPlugin(TestPluginBase, name="demo"):
pass

效果很好。

但如果你创建多个插件家族：

class ParserPlugin(Plugin):
registry = PluginRegistry()

class StoragePlugin(Plugin):
registry = PluginRegistry()

它们就可以拥有完全独立的注册空间。

class JsonParser(ParserPlugin, name="json"):
pass

class S3Storage(StoragePlugin, name="s3"):
pass

最终：

ParserPlugin.registry

只包含：

json

而：

StoragePlugin.registry

只包含：

s3

这种结构非常适合大型系统。

二十一、完整实现：一个真正可用的插件注册框架

把前面的经验组合起来：

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Any

class PluginRegistry:
def __init__(self):
self._plugins: dict[str, type["Plugin"]] = {}

def register(
self,
name: str,
plugin_cls: type["Plugin"],
) –> None:
if not name:
raise ValueError("插件名称不能为空")

if name in self._plugins:
old = self._plugins[name]

raise ValueError(
f"插件 {name!r} 已注册："
f"{old.__module__}.{old.__qualname__}"
)

self._plugins[name] = plugin_cls

def get(self, name: str) –> type["Plugin"]:
try:
return self._plugins[name]
except KeyError:
available = ", ".join(sorted(self._plugins))

raise LookupError(
f"找不到插件 {name!r}。"
f"可用插件：{available or '无'}"
) from None

def create(
self,
name: str,
*args: Any,
**kwargs: Any,
) –> "Plugin":
plugin_cls = self.get(name)
return plugin_cls(*args, **kwargs)

def clear(self) –> None:
self._plugins.clear()

def names(self) –> tuple[str, ...]:
return tuple(sorted(self._plugins))

class Plugin(ABC):
registry = PluginRegistry()

def __init_subclass__(
cls,
*,
name: str | None = None,
**kwargs,
):
super().__init_subclass__(**kwargs)

if name is not None:
cls.registry.register(name, cls)

@abstractmethod
def run(self, data: Any) –> Any:
raise NotImplementedError

创建插件：

class JsonPlugin(Plugin, name="json"):
def run(self, data):
return {
"type": "json",
"data": data,
}

class CsvPlugin(Plugin, name="csv"):
def run(self, data):
return {
"type": "csv",
"data": data,
}

运行：

plugin = Plugin.registry.create("json")

result = plugin.run({"id": 1})

print(result)

结果：

{
"type": "json",
"data": {"id": 1},
}

查看插件：

print(Plugin.registry.names())

得到：

("csv", "json")

到这里，一套非常轻量的插件框架已经形成。

二十二、加入元数据：插件系统真正开始“像框架”

真实项目很少只有插件名称。

可能还需要：

version
priority
description
enabled

可以定义：

from dataclasses import dataclass

@dataclass(frozen=True)
class PluginInfo:
name: str
version: str
priority: int
plugin_cls: type

Registry：

class PluginRegistry:
def __init__(self):
self._plugins = {}

def register(self, info: PluginInfo):
if info.name in self._plugins:
raise ValueError(
f"duplicate plugin: {info.name}"
)

self._plugins[info.name] = info

基类：

class Plugin:
registry = PluginRegistry()

def __init_subclass__(
cls,
*,
name=None,
version="1.0",
priority=0,
**kwargs,
):
super().__init_subclass__(**kwargs)

if name is None:
return

cls.registry.register(
PluginInfo(
name=name,
version=version,
priority=priority,
plugin_cls=cls,
)
)

插件声明：

class JsonPlugin(
Plugin,
name="json",
version="2.1",
priority=100,
):
pass

此时 class 声明本身就成为了一种小型 DSL：

这个类是什么插件？
叫什么？
什么版本？
什么优先级？

信息全部集中在定义位置。

这种声明式 API正是 __init_subclass__ 最有魅力的地方之一。

二十三、插件注册流程图

完整过程可以概括成：

应用启动
│
▼
加载插件模块
import plugins.json_plugin
│
▼
执行 class JsonPlugin(…)
│
▼
Python 创建 JsonPlugin 类
│
▼
调用 Plugin.__init_subclass__()
│
▼
校验插件元数据
│
▼
registry.register(…)
│
▼
Registry
┌───────────────┐
│ json → Json │
│ csv → Csv │
│ xml → Xml │
└───────────────┘
│
▼
Plugin.create("json")
│
▼
实例化 JsonPlugin

理解这张图以后，__init_subclass__ 的工作机制基本就清楚了。

二十四、如果插件很多，考虑 Entry Points

如果插件全部属于同一个代码库：

myapp/
plugins/

显式 import 已经很好用。

但如果目标是让第三方开发者能够安装：

pip install awesome-plugin

然后主程序无需修改就发现它，那么应该进一步考虑 Python Packaging 提供的 entry points 机制，而不是扫描 site-packages 或疯狂 import 所有模块。

架构会变成：

第三方 Python Package
│
▼
package metadata / entry points
│
▼
主程序发现插件
│
▼
import 指定对象
│
▼
Plugin Registry

这时有一个非常重要的架构思想：

__init_subclass__ 可以负责“类级别注册”，而 entry points 负责“包级别发现”。

两者不是竞争关系。

它们解决的是完全不同的问题。

二十五、什么时候 class decorator 反而更合适？

我们一直在讨论自动注册，但有时：

@register_plugin("json")
class JsonPlugin:
...

反而更加明确。

例如：

registry = {}

def register_plugin(name):
def decorator(cls):
registry[name] = cls
return cls

return decorator

使用：

@register_plugin("json")
class JsonPlugin:
pass

Decorator 的优势是：

显式。

看到：

@register_plugin

读者立刻知道这个类会产生注册行为。

而：

class JsonPlugin(Plugin):

如果不知道 Plugin.__init_subclass__ 的实现，可能并不知道定义类会修改 registry。

因此我的选择标准通常是：

只有少量类需要注册
→ decorator

属于整个类族的统一规则
→ __init_subclass__

需要真正控制 class 创建
→ metaclass

这个判断比简单地争论“哪个技术更高级”更有价值。

二十六、常见错误一：忘记 super()

错误：

class Plugin:
def __init_subclass__(cls, **kwargs):
cls.registry[cls.__name__] = cls

当前可能没事。

但未来加入：

class OtherMixin:
def __init_subclass__(cls, **kwargs):
...

它可能永远收不到调用。

正确：

class Plugin:
def __init_subclass__(cls, **kwargs):
super().__init_subclass__(**kwargs)
...

如果你正在编写的是准备被继承的框架基类，请养成一个习惯：

除非你明确要终止继承链，否则让 super() 继续沿 MRO 前进。

二十七、常见错误二：registry 放错地方

容易写：

class Plugin:
registry = {}

def __init_subclass__(cls, name=None, **kwargs):
super().__init_subclass__(**kwargs)

cls.registry[name] = cls

这不一定错误。

但你必须明确它意味着：

Registry 可以被子类覆盖。

如果业务规定“所有插件永远使用同一个根 Registry”，可以写：

Plugin.registry[name] = cls

如果你希望支持：

Parser Registry
Storage Registry
Command Registry
测试专用 Registry

则：

cls.registry[name] = cls

更灵活。

这是一个非常小的语法差异，却对应着完全不同的架构选择。

二十八、常见错误三：注册阶段做太多工作

不要这样：

class Plugin:
def __init_subclass__(cls, **kwargs):
super().__init_subclass__(**kwargs)

cls.client = connect_database()
cls.config = fetch_remote_config()
cls.model = load_large_model()

因为：

定义类
= import 模块
= 连接数据库
= 请求网络
= 加载模型

这会让系统：

启动缓慢
测试困难
import 行为不可预测
异常发生太早
生命周期难以管理

__init_subclass__ 最适合做的是：

轻量校验
元数据整理
类型登记
接口约束

而不是：

网络访问
数据库连接
重型初始化
长时间计算

二十九、测试建议：至少覆盖这 6 个场景

一个真正可靠的 Plugin Registry，我建议至少测试：

def test_plugin_registered():
...

验证正常注册。

def test_duplicate_name_rejected():
...

验证名称冲突。

def test_unknown_plugin():
...

验证未知插件错误。

def test_registry_isolation():
...

验证测试之间不会污染。

def test_multiple_inheritance():
...

验证 super() / MRO。

def test_plugin_import():
...

验证插件只有加载模块后才出现。

其中多重继承测试尤其值得写：

events = []

class Mixin:
def __init_subclass__(cls, **kwargs):
events.append("mixin")
super().__init_subclass__(**kwargs)

class Base:
def __init_subclass__(cls, **kwargs):
events.append("base")
super().__init_subclass__(**kwargs)

class Demo(Mixin, Base):
pass

assert events == [
"mixin",
"base",
]

这种测试不仅是在测业务代码，也是把团队对 Python MRO 的设计预期固化下来。

三十、性能：不要对这类优化过度焦虑

有读者可能会问：

每定义一个子类都执行 __init_subclass__，会不会影响性能？

通常不值得担心。

绝大多数插件类只会在：

进程启动
模块 import
测试收集

阶段创建一次。

它并不发生在：

plugin.run()

这样的高频业务路径上。

所以真正应该避免的是：

def __init_subclass__(...):
expensive_network_request()

而不是担心：

registry[name] = cls

这样的字典操作。

性能优化必须先明确：

这是 cold path 还是 hot path？

类注册通常属于 cold path。

业务处理循环才往往是 hot path。

三十一、__init_subclass__ 真正值得学习的，不只是一个魔术方法

如果把它仅仅理解成：

Python 自动注册子类的技巧

其实低估了它。

它背后涉及了一整组非常重要的 Python 设计思想：

class 本身也是对象

类创建具有生命周期

继承使用 MRO

super() 是协作机制

import 会执行代码

全局可变状态影响测试

声明式 API 可以降低使用成本

框架设计需要控制“魔法”的边界

这些能力一旦理解，你会发现很多 Python 框架的源码突然变得容易读了。

例如当看到：

class User(BaseModel):
...

或者：

class MyCommand(Command):
...

你会开始意识到：

class 定义本身可能就是一个框架扩展点。

三十二、最终结论：什么时候用哪一种？

可以把今天的内容浓缩成这张决策表：

所以，对于文章最开始的问题：

__init_subclass__ 能不能替代 metaclass？

更准确的答案应该是：

当你的目标是“管理子类”，它往往可以替代 metaclass，而且应该优先考虑；当你的目标是“管理类本身如何被创建”，metaclass 仍然不可替代。

写在最后：Python 的高级，不在“魔法多”，而在“抽象刚刚好”

刚学习 Python 的时候，我们常常为简洁的语法着迷：

[x * 2 for x in numbers]

再深入一点，我们开始喜欢：

decorator
generator
context manager
descriptor
metaclass

但写过越来越多生产代码以后，会慢慢发现另一个事实：

高级 Python 编程并不是尽可能多地使用高级语法。

真正成熟的代码往往是在不断寻找那个恰到好处的抽象层级。

插件注册只是十几行代码。

但如果认真追究下去，我们会碰到：

类生命周期
MRO
super()
模块导入
全局状态
测试隔离
依赖注入
插件发现
框架 API 设计

而这正是学习 Python 最有意思的地方。

一个看起来只有几行代码的问题，背后往往连接着整套语言设计。

下一次，当你准备写：

class PluginMeta(type):

的时候，不妨先问自己一句：

我是真的需要控制类的创建，还是只需要在子类创建之后做一点事情？

如果答案是后者，那么：

def __init_subclass__(cls, **kwargs):
super().__init_subclass__(**kwargs)

可能就是你需要的全部魔法。

而如果你已经在实际项目里设计过 Python 插件机制，也很欢迎继续思考几个问题：

你更倾向显式 decorator 注册，还是继承即注册？

当插件达到几十甚至几百个以后，你会选择 import、配置文件，还是 entry points 做 discovery？

你遇到过哪些由于 registry、import side effect 或多重继承导致的诡异 Bug？

这些问题没有绝对统一的答案，但每一次认真讨论，都会让我们更接近真正可靠、可维护的 Python 设计。

附录：延伸学习方向

如果准备继续深入这一主题，可以顺着下面几个知识点学习：

• Python Data Model：深入理解 class、MRO、descriptor 与 metaclass。
• PEP 487：了解 __init_subclass__ 和 __set_name__ 为什么被引入 Python。
• abc.ABC：设计抽象插件接口。
• importlib：理解 Python 模块加载与动态导入机制。
• importlib.metadata：构建基于 Entry Points 的第三方插件系统。
• pytest fixture：解决全局状态与测试隔离。
• Dependency Injection：将 registry、配置和资源生命周期从全局状态中解耦。
• Python Packaging：进一步实现真正可通过 pip 分发的插件架构。

如果掌握了这些内容，你面对的就不再只是一个“Python 自动注册技巧”，而是一套能够真正用于框架、SDK、数据平台、自动化系统以及后端工程中的 Python 插件架构设计方法。