用途:在 Litestar 应用中通过事件总线实现进程内、解耦的异步副作用,让一次动作触发一个或多个副作用,而不把路由处理器与具体实现耦合。它不负责应用生命周期,也不提供基于消息中间件的消息传递。
主要能力:用 listeners=[...] 在应用上注册监听器;用 @listener 装饰器定义监听器;通过 request.app.emit(...) 或其它 app 引用发射事件;支持同一事件注册多个监听器、一个监听器监听多个事件 ID,以及监听器共享 *args/**kwargs 参数契约;默认使用内置的 SimpleEventEmitter 进行简单进程内异步扇出,并可在确有持久化、重试、调度或外部传输需求时实现自定义后端。
使用方式:先确定稳定的事件 ID 与参数契约,再注册监听器并在权威状态变更之后发射事件;监听器尽量保持小而聚焦于副作用,重型领域逻辑交给服务层;契约可能演进时优先发射关键字参数;多个监听器共享事件时,监听器签名应容忍额外 kwargs。参考文件为 references/listener-patterns.md(监听器注册、多事件/多监听器、参数形状、发射模式与服务层设计)和 references/emitter-backends.md(后端选择、SimpleEventEmitter、自定义后端要求、异步上下文管理器行为与失败语义)。
适用场景:一个动作需要触发多个相互独立的异步副作用;需要在 handler 与副作用实现之间解耦。限制与注意事项:不要把事件用于 on_startup/on_shutdown 等生命周期管理,那是不同机制;不要用事件替代跨进程发布订阅,这种情况应使用 litestar-channels;同一事件 ID 不要发射形状不一致的参数;不要在默认内存发射器尚能满足需求时过早引入自定义后端;监听器失败不应连带取消同级监听器(建议用测试验证)。事件交付若需跨进程或重试/历史语义,需自定义后端。测试可用 litestar-testing 断言事件发射与监听器失败场景。