一、从一个问题出发
当你定义一个基类，希望所有子类在被定义时（而非实例化时）就自动完成某些注册、校验或增强逻辑，你会怎么做？
传统方案是元类（metaclass），但元类的心智负担极重。Python 3.6 引入的__init_subclass__正是为了解决这一痛点——用一个普通的类方法，优雅地拦截子类的创建过程。
二、它是什么
classBase:def__init_subclass__(cls,**kwargs):super().__init_subclass__(**kwargs)# cls 是正在被定义的子类，不是 Base 本身__init_subclass__是一个隐式的classmethod，定义在父类中，每当有子类继承该父类时，Python 解释器会自动调用它，并将新创建的子类作为第一个参数cls传入。
PEP 487（Python 3.6）正式引入此机制，目标是提供一种比元类更轻量的子类定制钩子。
三、调用时机与调用链
classA:def__init_subclass__(cls,**kwargs):super().__init_subclass__(**kwargs)print(f"A.__init_subclass__ called:{cls}")classB(A):# 触发 A.__init_subclass__(B)passclassC(B):# 触发 A.__init_subclass__(C)（沿 MRO 向上找）pass输出：
A.__init_subclass__ called: <class '__main__.B'> A.__init_subclass__ called: <class '__main__.C'>关键细节：
| 时机 | 是否触发 |
|---|---|
定义Base本身 | ❌ 不触发 |
直接继承Base的子类被定义 | ✅ 触发 |
| 子类的子类被定义 | ✅ 触发（沿 MRO 传播） |
| 实例化子类 | ❌ 不触发 |
四、传递关键字参数
__init_subclass__最精妙的设计之一是支持通过class语句的关键字参数向父类传递配置：
classAnimal:def__init_subclass__(cls,sound:str="...",**kwargs):super().__init_subclass__(**kwargs)cls.sound=soundprint(f"Registered{cls.__name__}with sound '{sound}'")classDog(Animal,sound="woof"):passclassCat(Animal,sound="meow"):passprint(Dog.sound)# woofprint(Cat.sound)# meow这些关键字参数不会出现在__init__中，它们专属于类定义阶段，语义清晰，无副作用。
⚠️ 务必用
**kwargs接收未消费的参数并传给super()，否则多重继承时会因参数不匹配而抛出TypeError。
五、核心应用场景
5.1 自动注册子类（插件系统）
这是最经典的用法，无需手动维护注册表：
classHandler:_registry:dict[str,type]={}def__init_subclass__(cls,name:str|None=None,**kwargs):super().__init_subclass__(**kwargs)key=nameorcls.__name__.lower()Handler._registry[key]=clsprint(f"Handler '{key}' registered.")classJSONHandler(Handler,name="json"):defhandle(self):...classXMLHandler(Handler,name="xml"):defhandle(self):...# 无需任何手动注册print(Handler._registry)# {'json': <class 'JSONHandler'>, 'xml': <class 'XMLHandler'>}工厂方法只需查表：
@classmethoddefcreate(cls,name:str)->"Handler":returncls._registry[name]()5.2 强制接口约束（抽象检查的增强版）
abc.ABC在实例化时才报错，__init_subclass__可以在类定义时就报错：
classStrictBase:_required_methods=("execute","rollback")def__init_subclass__(cls,**kwargs):super().__init_subclass__(**kwargs)formethodinStrictBase._required_methods:ifnotcallable(getattr(cls,method,None)):raiseTypeError(f"{cls.__name__}must implement '{method}'")classGoodTransaction(StrictBase):defexecute(self):...defrollback(self):...classBadTransaction(StrictBase):# 立即 TypeError！defexecute(self):...# 忘记实现 rollback5.3 自动注入行为（装饰器的类级等价物）
importfunctools,timeclassTimed:def__init_subclass__(cls,**kwargs):super().__init_subclass__(**kwargs)forname,fninvars(cls).items():ifcallable(fn)andnotname.startswith("_"):setattr(cls,name,_timer(fn))def_timer(fn):@functools.wraps(fn)defwrapper(*args,**kwargs):t=time.perf_counter()result=fn(*args,**kwargs)print(f"{fn.__name__}:{time.perf_counter()-t:.4f}s")returnresultreturnwrapperclassMyService(Timed):deffetch(self):time.sleep(0.1)defprocess(self):time.sleep(0.2)svc=MyService()svc.fetch()# fetch: 0.1002ssvc.process()# process: 0.2001s5.4 ORM 字段收集（Django/SQLAlchemy 同款思路）
classField:def__init__(self,col_type):self.col_type=col_typeclassModelMeta:def__init_subclass__(cls,**kwargs):super().__init_subclass__(**kwargs)cls._fields={k:vfork,vinvars(cls).items()ifisinstance(v,Field)}print(f"Model '{cls.__name__}' fields:{list(cls._fields)}")classUser(ModelMeta):id=Field("INTEGER")name=Field("VARCHAR")email=Field("VARCHAR")# 输出: Model 'User' fields: ['id', 'name', 'email']六、与元类的对比
| 维度 | __init_subclass__ | 元类（Metaclass） |
|---|---|---|
| 语法复杂度 | 低，普通方法 | 高，需理解type体系 |
| 作用时机 | 子类定义完成后 | 子类定义过程中（可修改类命名空间） |
| 能否修改类命名空间 | ❌ | ✅ |
| 多重继承兼容性 | 好（用super()链式调用） | 差（元类冲突是常见陷阱） |
| 传递配置 | 关键字参数，优雅 | __new__参数，繁琐 |
| 适用场景 | 注册、校验、增强 | 需要深度控制类创建过程 |
结论：能用__init_subclass__解决的问题，不必引入元类。
七、与__set_name__的协同
Python 3.6 同期引入的__set_name__在描述符被赋值给类属性时触发，两者常配合使用：
classValidatedField:def__set_name__(self,owner,name):# 此时 owner 是拥有该描述符的类，name 是属性名self.name=namedef__set__(self,obj,value):ifnotisinstance(value,int):raiseTypeError(f"{self.name}must be int")obj.__dict__[self.name]=valueclassSchema:def__init_subclass__(cls,**kwargs):super().__init_subclass__(**kwargs)# 可在此对 cls 上的 ValidatedField 做额外处理fields=[kfork,vinvars(cls).items()ifisinstance(v,ValidatedField)]cls._validated_fields=fieldsclassConfig(Schema):timeout=ValidatedField()retries=ValidatedField()八、多重继承下的正确姿势
多重继承时，__init_subclass__沿 MRO 链式调用，必须调用super()，否则链条断裂：
classLoggable:def__init_subclass__(cls,**kwargs):super().__init_subclass__(**kwargs)# ✅ 必须cls._log=TrueclassSerializable:def__init_subclass__(cls,**kwargs):super().__init_subclass__(**kwargs)# ✅ 必须cls._serializable=TrueclassDocument(Loggable,Serializable):pass# Document._log 和 Document._serializable 均已设置若省略super().__init_subclass__(**kwargs)，MRO 中后续的__init_subclass__将被静默跳过，引发难以追踪的 bug。
九、常见陷阱总结
1. 忘记调用super()
链式调用断裂，多重继承场景必现问题。
2. 关键字参数未用**kwargs透传
# 错误示范def__init_subclass__(cls,my_param=None):# 漏掉 **kwargssuper().__init_subclass__()# 漏掉 **kwargs一旦有其他父类也消费关键字参数，即报TypeError。
3. 误以为cls是父类cls始终是正在被创建的那个子类，不是定义了__init_subclass__的类。
4. 在__init_subclass__中访问未完全初始化的子类
某些装饰器逻辑若依赖子类的__init__已存在，要注意此时子类的方法已在vars(cls)中，但父类方法通过 MRO 继承，不在vars(cls)里。
十、一句话总结
__init_subclass__是 Python 3.6 给类体系提供的轻量级生命周期钩子，它在子类被定义的瞬间触发，让父类得以观察、校验、增强乃至注册每一个子类——用最小的复杂度，实现了元类 80% 的日常用途。
掌握它，你将拥有一把构建插件系统、ORM、接口约束框架的利器，同时保持代码的可读性与可维护性。
