5.5 装饰器和类的选择

情况1：中间件只用一个钩子函数，推荐用装饰器，需要多个钩子函数推荐类写法

• 当一个中间件只需要实现一个钩子函数时，直接使用装饰器最简单。
• 当一个中间件需要实现多个钩子函数时，类写法更合适。

装饰器也不是不能实现，多数情况下可以像下面的示例里那样通过工厂函数返回多个装饰器函数来完成；但这种方式本质上是把一个“逻辑上属于同一个中间件”的行为拆成多个独立函数，再由外部统一组装，因此不如类写法自然、集中、清晰。

1. 使用装饰器实现

2. 使用类实现

结合上面的两个示例，可以得出结论：

• 装饰器写法适合把单个 hook 快速挂到 agent 生命周期的某个节点上；
• 类写法更适合把多个 hook 组织为一个完整的中间件组件；
• 当中间件同时涉及 before_model 、after_model 等多个钩子时，虽然装饰器工厂也能实现，但类写法在结构表达、配置归属、可维护性上更好。

总结：
单钩子场景下，装饰器即可；多钩子场景下，类不是唯一可行方案，但通常是更自然、更推荐的实现方式。
情况2：复杂配置推荐用类实现
装饰器当然也可以通过函数闭包传递参数，但在自省（运行时类型校验）、调试等方面天然不如类写法方便。

基于类的写法可以随时打印参数信息，而基于装饰器的闭包实现则难以做到。
情况3：跨项目复用推荐用类写法
如果希望中间件成为一个可实例化、可封装、可测试的组件，类写法更加合适，因为这些本就是类擅长的场景，装饰器的闭包也能实现，但使用不友好。
总结：

装饰器写法和类写法都能实现 middleware hook，本质上只是两种定义中间件的方式，并不是能力上完全割裂的两套机制。底层实现是统一的。
一般来说：

• 装饰器写法更适合单个 hook、逻辑简单、快速原型的场景；
• 类写法更适合多个 hook 组合、复杂配置、需要同时提供同步/异步实现、以及更强复用与可测试性的场景；