litestar-events

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Events

事件系统

Execution Workflow

执行工作流

Decide whether the event bus is the right tool: decoupled in-process side effects, not app lifecycle or broker-backed messaging.
Define stable event IDs and argument contracts before wiring emitters and listeners.
Register listeners on the
```
Litestar
```
app with
```
listeners=[...]
```
.
Emit events from handlers or services through
```
request.app.emit(...)
```
or another app reference.
Keep listeners independent so multiple listeners can react to the same event safely.
Replace the default emitter backend only when retry, persistence, or external infrastructure requirements justify it.

判断事件总线是否为合适工具：适用于解耦的进程内异步副作用，而非应用生命周期或代理支持的消息传递场景。
在连接发射器和监听器之前，定义稳定的事件ID和参数约定。
通过
```
listeners=[...]
```
在
```
Litestar
```
应用上注册监听器。
从处理器或服务中通过
```
request.app.emit(...)
```
或其他应用引用触发事件。
保持监听器独立，确保多个监听器可安全响应同一事件。
仅当重试、持久化或外部基础设施需求有必要时，才替换默认发射器后端。

Core Rules

核心规则

Treat event IDs as stable contracts, not ad hoc strings scattered through the codebase.
Make every listener for an event compatible with the full emitted
```
*args
```
and
```
**kwargs
```
set.
Use
```
**kwargs
```
defensively when multiple listeners consume different subsets of the same event payload.
Keep listener bodies side-effect focused and small; delegate heavy domain logic to services.
Use the built-in in-memory emitter for simple in-process async fanout.
Implement a custom emitter backend only when persistence, retry, scheduling, or external transport is required.
Do not confuse the event bus with
```
on_startup
```
/
```
on_shutdown
```
; those are different Litestar mechanisms.

将事件ID视为稳定约定，而非分散在代码库中的临时字符串。
确保某一事件的所有监听器都能兼容完整的触发
```
*args
```
和
```
**kwargs
```
集合。
当多个监听器消费同一事件负载的不同子集时，谨慎使用
```
**kwargs
```
。
监听器主体应聚焦于副作用且保持精简；将复杂领域逻辑委托给服务处理。
对于简单的进程内异步扇出场景，使用内置的内存发射器。
仅当需要持久化、重试、调度或外部传输时，才实现自定义发射器后端。
请勿将事件总线与
```
on_startup
```
/
```
on_shutdown
```
混淆；二者是Litestar的不同机制。

Decision Guide

决策指南

Use events when one action should trigger one or more async side effects without coupling the route handler to each implementation.
Use multiple listeners when several side effects should react to the same event independently.
Use one listener with multiple event IDs only when the argument contract and behavior are genuinely shared.
Use a custom backend when event delivery must survive process boundaries or support retry/history semantics.
Use
```
litestar-channels
```
instead when the problem is real pub-sub or cross-process fanout.
Use
```
litestar-app-setup
```
instead when the task is startup/shutdown initialization.

当一个操作需要触发一个或多个异步副作用，且无需将路由处理器与每个实现耦合时，使用事件系统。
当多个副作用需要独立响应同一事件时，使用多监听器。
仅当参数约定和行为真正共享时，才使用单个监听器处理多个事件ID。
当事件传递必须跨进程边界或支持重试/历史语义时，使用自定义后端。
当问题涉及真正的发布-订阅或跨进程扇出时，使用
```
litestar-channels
```
替代。
当任务为启动/关闭初始化时，使用
```
litestar-app-setup
```
替代。

Reference Files

参考文件

Read only the sections you need:

For listener registration, multi-event listeners, multiple listeners, argument-shape rules, emission patterns, and service-layer design, read references/listener-patterns.md.
For backend selection,
```
SimpleEventEmitter
```
, custom backend requirements, async context manager behavior, and failure semantics, read references/emitter-backends.md.

仅阅读你需要的章节：

关于监听器注册、多事件监听器、多监听器、参数格式规则、触发模式以及服务层设计，请阅读references/listener-patterns.md。
关于后端选择、
```
SimpleEventEmitter
```
、自定义后端要求、异步上下文管理器行为以及失败语义，请阅读references/emitter-backends.md。

Recommended Defaults

Anti-Patterns

反模式

Using events for startup/shutdown resource management.
Emitting inconsistent argument shapes for the same event ID.
Writing listeners that break as soon as another listener needs an extra kwarg.
Hiding critical synchronous business steps behind fire-and-forget event listeners.
Reaching for a custom backend before the in-process emitter's limits are real.
Using events as a substitute for channels when cross-process delivery is required.

将事件系统用于启动/关闭资源管理。
同一事件ID触发的参数格式不一致。
编写的监听器会因其他监听器需要额外kwargs而失效。
将关键同步业务步骤隐藏在“触发即遗忘”的事件监听器之后。
在进程内发射器的限制未实际显现时就选择自定义后端。
当需要跨进程传递时，将事件系统作为channels的替代方案。

Validation Checklist

验证检查清单

Confirm each emitted event ID has an intentional contract and owner.
Confirm every listener can accept the full emitted arg/kwarg shape.
Confirm multiple listeners for the same event remain independent and idempotent enough for the use case.
Confirm event emission is placed after the authoritative state change that should trigger it.
Confirm the default emitter backend is sufficient, or document why a custom backend is required.
Confirm listener failures do not accidentally cancel sibling listeners.
Confirm tests cover both emission side effects and listener argument compatibility.

确认每个触发的事件ID都有明确的约定和负责人。
确认每个监听器都能接受完整的触发参数/关键字参数格式。
确认同一事件的多个监听器保持独立，且在使用场景下具备足够的幂等性。
确认事件触发的位置在应该触发它的权威状态变更之后。
确认默认发射器后端足够用，或记录需要自定义后端的原因。
确认监听器失败不会意外取消同级监听器。
确认测试覆盖了触发副作用和监听器参数兼容性。

Cross-Skill Handoffs

跨技能交接

Use
```
litestar-app-setup
```
for startup/shutdown hooks and lifespan ownership.
Use
```
litestar-lifecycle-hooks
```
for request/response interception and instrumentation.
Use
```
litestar-channels
```
for broker-backed or cross-process publish-subscribe flows.
Use
```
litestar-testing
```
for event-emission assertions and listener-failure tests.

启动/关闭钩子和生命周期管理使用
```
litestar-app-setup
```
。
请求/响应拦截和埋点使用
```
litestar-lifecycle-hooks
```
。
代理支持或跨进程发布-订阅流使用
```
litestar-channels
```
。
事件触发断言和监听器失败测试使用
```
litestar-testing
```
。

litestar-events

Original

Translation

Events

事件系统

Execution Workflow

执行工作流

Core Rules

核心规则

Decision Guide

决策指南

Reference Files

参考文件

Recommended Defaults

推荐默认方案

Anti-Patterns

反模式

Validation Checklist

验证检查清单

Cross-Skill Handoffs

跨技能交接

Litestar References

Litestar参考链接