ErisPulse.Core.di 模块
模块概述
ErisPulse 依赖注入模块
为各处理器注入点(命令处理器 / 事件处理器 / 生命周期钩子 / 路由处理器)提供 统一的声明式依赖注入:
- 处理器参数以
Depends(dependency)作为默认值声明依赖 - 注册期由 :func:
extract_depends提取声明(fail-fast:依赖不可调用直接抛 ValueError) - 分发期由 :func:
resolve_depends解析:以上下文对象(注入点的第一参数,如Event/ 生命周期data/ 路由HttpRequest)调用依赖函数, 结果按参数名注入处理器 - 依赖函数支持同步与异步;同一注入点的所有依赖按声明顺序逐个解析
提示
- 依赖函数的第一个参数是注入点上下文对象——命令/事件场景为
Event, 生命周期钩子为事件data,路由场景为HttpRequest/SseEmitterargs=/options=参数声明与依赖注入参数重名时注册期抛 ValueError(fail-fast)- FastAPI 承载的 HTTP 路由请使用 FastAPI 原生
fastapi.Depends(生态成熟、 支持请求级缓存);ErisPulse.Core.Depends 覆盖框架自有分发链路
函数列表
_freeze_key(value: Any) -> Any
内部方法 把依赖声明的固定参数递归冻结为可哈希的稳定结构(请求级缓存键用): dict → 排序条目元组、list/tuple → 元组、set → 排序表示元组;其余叶子原样保留
extract_depends(func: Callable) -> dict[str, Depends]
注册期提取处理器签名中以 Depends(...) 为默认值的参数(fail-fast)
在处理器注册时调用一次(命令装饰器 / BaseEventHandler.register /
lifecycle.register / 路由注册),分发期零反射开销。
- func: 处理器函数
返回值: 参数名 → Depends 声明(无依赖声明时为空 dict)
异常: ValueError - 依赖不可调用
示例:
extract_depends(admin)
{"db": Depends(dependency=<function get_db>)}
async resolve_depends(depends: dict[str, Depends], ctx: Any) -> dict[str, Any]
分发期解析依赖:以上下文对象调用各依赖函数,返回处理器关键字参数
同步依赖直接调用;异步依赖依次 await。任一依赖抛出的异常原样向上 传播,由注入点的统一错误路径处理(与处理器自身异常同口径)。
请求级缓存(默认开启):处于缓存作用域内(事件分发链)且声明
use_cache=True 时,相同依赖函数只解析一次、结果在整次事件内共享;
use_cache=False 或不在作用域内(lifecycle / 路由独立调用链)时
每次解析。
- depends: :func:
extract_depends的提取结果 - ctx: 注入点上下文对象(作为依赖函数第一参数)
返回值: 参数名 → 依赖函数返回值
async call_with_depends(func: Callable, *args: Any) -> Any
以 Depends 注入调用模块生命周期方法(on_load / on_unload 等)
供模块加载器调用:上下文对象为第一实参(事件数据 dict,如
{"module_name": ...})。同步方法直接调用,async 方法 await;
依赖声明的解析失败原样向上传播(on_load 失败即加载失败,on_unload
失败由调用方记录日志)。
- func: 生命周期方法(绑定方法)
- args: 透传的位置参数(第一参为上下文对象)
返回值: 方法返回值
call_with_depends_sync(func: Callable, *args: Any) -> Any
同步上下文版本的 Depends 注入调用(emit_sync / 同步 disable 等)
仅支持同步依赖;声明了异步依赖时抛 TypeError(携带本地化原因),
由调用方决定跳过或降级。
- func: 生命周期方法(绑定方法)
- args: 透传的位置参数(第一参为上下文对象)
返回值: 方法返回值
异常: TypeError - 声明了异步依赖(同步上下文无法 await)
类列表
class Depends
依赖声明标记(作为处理器参数默认值使用)
dependency: 依赖函数(同步或异步),签名
dependency(ctx)——ctx为注入点上下文对象(Event / data / HttpRequest 等), 返回值按参数名注入处理器use_cache: 请求级缓存开关(默认开启):同一次事件分发内,
相同依赖函数只解析一次、所有注入点共享结果(如数据库会话复用); 置
False每次注入都重新解析
示例:
async def get_db(event):
return await sdk.module.call("DB", "get_session")
@command("admin")
async def admin(event, db=Depends(get_db)):
...
方法列表
module(module_name: str, method: str, *args: Any, **kwargs: Any) -> 'Depends'(staticmethod)
声明模块服务依赖(语法糖):等价于在依赖函数内调用 sdk.module.call(...)
- module_name: 目标模块名
- method: 目标服务方法名(须在目标模块 get_meta().services 契约内)
- args: 透传给目标方法的固定位置参数
- kwargs: 透传给目标方法的固定关键字参数
返回值 (Depends): 声明(上下文对象被忽略——模块调用不依赖注入点上下文)
示例:
@command("admin")
async def admin(event, db=Depends.module("DB", "get_session")):
...