callback

特性

1. 以 Callback 或 AsyncCallback 为根 定义子类，类型注解 描述「这一次调用要携带哪些数据」；触发后返回同一条已校验、可被处理函数改写的实例，不是新拷贝。

2. 处理函数分 前、中间、后 三层；触发时先整层前、再整层中间、再整层后；同一层里多段逻辑可以一起收尾，这一层全部跑完才进下一层。

3. from callback 只面对外给出 Callback 与 AsyncCallback 两个根名，其它是细节。

同步根和异步根怎么选

在 async def 里要 await 管线、不额外嵌一套阻塞，用 AsyncCallback 子类。同步脚本、同步 Web 视图中只想「一调就结束」时，用 Callback 子类即可。

处理函数必须和根类型一致

• 继承 Callback 的类：登记 async def 会 TypeError；只接受普通函数。
• 继承 AsyncCallback 的类：登记非协程的 def 会 TypeError；只接受协程函数。

这样触发时的调度方式与根类型一一对应，不会在同一套子类上混用两套语法。

子类名当装饰器、当「触发」

单参数、可调用、且没有关键字参数 的类调用，一律走登记；若某次调用的第一个数据字段就是可调用对象，用关键字传，例如 MyType(fn=某函数)，避免和 @MyType 撞形态。

仍可直接用 register / register_before / register_after，与上表各层一一对应。

子类里哪些名字算「这次调用的数据」

触发时多出来的参数名、没声明的，不能传。只有「普通类型注解、名字不以 _ 开头」的才当作这一次载荷的字段；下划线名用来给类型检查看可以；ClassVar 是类级常量，不算在每条实例的字段里。

字段可以填任意 Python 对象；处理函数和外面读到的是同一引用。

前、中、后三层和装饰器

中间层和以前「@子类」是同一层。可以写带载荷参数的，也可以无参。

每棵子类在类型对象上各自挂一套分层登记，不和父类共享一份列表。根类型 Callback / AsyncCallback 自己 不再挂可登记容器，只供往下继续定义业务子类。

同一层里同函数只保留一条

同一个可调用对象在同一层里登记多次，内部仍是一条，触发只跑一遍。同一段逻辑可以分别落在不同层，那是三层里各记一条、各跑一遍。

列出子类、清空登记

• 子类名.get_all()（在根或中间类型上点）：列出从该类型直接派生的下一层子类。换一根就要在对应根上再点一次。
• Callback.clear_layer_registries() 与 AsyncCallback.clear_layer_registries()：从各自根向下清空已登记的处理函数；两棵根都用过时，各清一次。

@OrderPaid.before
def prepare(cb: OrderPaid) -> None: ...

@OrderPaid
def bump_total(cb: OrderPaid) -> None:
    cb.total += 1

@OrderPaid.after
def notify(cb: OrderPaid) -> None: ...

paid = OrderPaid(order_id="x", total=1)

AsyncCallback 子类把上面三处都改成 async def，最后一行在协程里写成 paid = await OrderPaid(...) 即可。