Master plugin frameworks: cont…

# FastAPI 插件框架设计：Context 结构与插件注册/卸载机制

一、设计目标

• DI 支持：插件间及插件与宿主的依赖注入（基于类型注解）
• Typed Events：强类型事件发布/订阅，编译期（IDE/mypy）可检查
• 可卸载：插件可安全启停，资源可清理

二、Context 结构设计

Context 是插件与宿主交互的唯一入口，建议分层：

• AppContext（全局）
• app: FastAPI 实例引用
• settings: BaseSettings 全局配置
• db: AsyncEngine / Session 数据库资源句柄
• event_bus: EventBus 类型化事件总线
• container: ServiceContainer DI 容器
• PluginContext（每个插件独享，包装 AppContext）
• plugin_id: str
• logger：带插件名前缀的日志器
• router: APIRouter：插件注册自己的路由
• register_service[T](impl) / get_service[T]：注册与获取服务
• publish(event) / subscribe(EventType, handler)

关键点：插件只能通过 PluginContext 操作，禁止直接持有全局对象，便于卸载时回收。

三、Typed Events 设计

• 用 dataclass 或 pydantic 定义事件类，如 OrderCreated(order_id: str, amount: float)
• EventBus 用泛型：subscribe(event_type: type[E], handler: Callable[[E], Awaitable[None]])
• 内部以 dict[type, list[handler]] 存储订阅关系
• publish 时按事件类型精确分发；可选支持继承链分发（inspect.getmro）

四、插件注册流程

1. 声明：插件类实现 Plugin 协议，包含 name、dependencies: list[str]、setup(ctx: PluginContext)、teardown() 方法

2. 加载：通过 importlib 扫描插件目录或手动注册

3. 依赖检查：拓扑排序解析 dependencies，检测循环依赖并按序 setup

4. 挂载：setup 中通过 ctx 注册 router、service、事件订阅

5. 生命周期钩子：结合 FastAPI lifespan，启动时依次 setup，关闭时逆序 teardown

五、插件卸载机制

• 逆序卸载：按依赖关系反向 teardown（先卸依赖别人的）
• 自动清理：PluginContext 记录本插件注册的所有资源（router、service key、事件订阅、后台任务），teardown 后由框架统一移除：
• 从 app.router.routes 移除该插件路由
• 从 EventBus 与 DI 容器删除对应条目
• 引用检查（可选）：卸载前检测其他插件是否仍订阅其事件/依赖其服务，有则告警或拒绝卸载
• 状态机：插件状态 LOADED → ACTIVE → SUSPENDED → UNLOADED，支持热重载（t