FastAPI-Events 是一个专为 FastAPI 和 Starlette 框架设计的轻量级异步事件处理库。它让你可以轻松地在应用中触发和处理事件，且不会影响接口响应速度，非常适合需要异步任务和事件驱动的应用。
什么是事件驱动？
事件驱动编程就是应用程序通过“事件”来触发某些操作，比如用户注册后触发发送欢迎邮件、订单创建后触发库存更新等。事件可以异步处理，避免接口等待耗时操作，提升性能和用户体验。
FastAPI-Events 的核心特点
- 简单易用：一行代码即可触发事件。
- 异步非阻塞：事件处理在响应返回后执行，不影响接口响应速度。
- 支持本地和远程事件处理：支持本地处理，也能发送到 AWS SQS、Google Pub/Sub 等远程消息队列。
- 数据校验：用 Pydantic 模型定义事件数据结构，自动校验数据格式。
- 事件链：事件处理器内还可以触发新事件，支持复杂业务流程。
- 支持依赖注入：事件处理器可以使用 FastAPI 的依赖注入，方便获取数据库连接等资源。
- 集成 OpenTelemetry：支持分布式追踪，方便监控事件流。
安装 FastAPI-Events
pip install fastapi-events
如果需要支持 AWS、Google 云或 OpenTelemetry，可以安装对应扩展：
pip install fastapi-events[aws]
pip install fastapi-events[google]
pip install fastapi-events[otel]
快速上手示例
1. 配置事件中间件和本地处理器
from fastapi import FastAPI
from fastapi_events.dispatcher import dispatch
from fastapi_events.middleware import EventHandlerASGIMiddleware
from fastapi_events.handlers.local import local_handler
app = FastAPI()
# 注册事件处理中间件和本地事件处理器
app.add_middleware(EventHandlerASGIMiddleware, handlers=[local_handler])
@app.get("/")
async def root():
# 触发事件，事件名称为 "my-fancy-event"，携带数据
dispatch("my-fancy-event", payload={"id": 1})
return {"message": "事件已触发"}
2. 定义事件数据结构并触发事件
使用 Pydantic 模型定义事件数据，确保数据格式正确：
from pydantic import BaseModel
from fastapi_events.dispatcher import dispatch
class UserSignedUpEvent(BaseModel):
__event_name__ = "user_signed_up"
user_id: str
timestamp: str
# 触发事件，传入模型实例
dispatch(UserSignedUpEvent(user_id="12345", timestamp="2025-05-19T19:00:00Z"))
3. 编写本地事件处理器
捕获所有以 user_ 开头的事件名称：
from fastapi_events.handlers.local import local_handler
from fastapi_events.typing import Event
@local_handler.register(event_name="user_*")
async def handle_user_events(event: Event):
event_name, payload = event
print(f"收到事件：{event_name}，数据：{payload}")
生命周期事件示例（启动和关闭）
FastAPI 支持在应用启动和关闭时执行代码，适合初始化资源或清理工作：
from fastapi import FastAPI
app = FastAPI()
items = {}
@app.on_event("startup")
async def on_startup():
# 应用启动时初始化数据
items["foo"] = {"name": "Fighters"}
items["bar"] = {"name": "Tenders"}
@app.on_event("shutdown")
def on_shutdown():
# 应用关闭时写日志
with open("log.txt", "a") as f:
f.write("应用已关闭\n")
@app.get("/items/{item_id}")
async def get_item(item_id: str):
return items.get(item_id, {"error": "未找到该项"})
高级用法
- 事件链：事件处理器里可以继续触发新事件，实现复杂流程。
- 远程事件队列：支持发送事件到 AWS SQS、Google Pub/Sub 等，方便微服务解耦。
- 自定义事件处理器：继承基础类，自定义事件处理逻辑。
- 依赖注入：事件处理器支持 FastAPI 依赖注入，方便使用数据库、缓存等。
常见问题及解决方案
| 问题 | 解决方案 |
|---|---|
| dispatch() 报错 LookupError | 确认 dispatch 在请求生命周期内调用，或设置自定义 middleware_id，避免跨请求调用。 |
| 事件处理器不生效 | 确保事件处理器模块已正确导入，且中间件已注册。 |
总结
FastAPI-Events 是一个功能强大且易用的异步事件处理库，适合需要事件驱动和异步任务的 FastAPI 应用。它让代码更清晰，性能更高，扩展性更强，非常适合现代微服务和复杂业务场景。
如果你想快速体验，建议先用本地处理器和简单事件开始，逐步学习事件链和远程队列功能。这样可以稳步掌握 FastAPI-Events 的强大能力。
祝你开发顺利！🚀
