ErisPulse.Core.router 模块
模块概述
ErisPulse 路由系统
提供统一的HTTP和WebSocket路由管理,支持多适配器路由注册和生命周期管理。 增强功能: 装饰器路由、路由中间件、自动文档、路由限流、分组/版本管理、CORS/安全头
提示
- 使用 @http / @get / @post / @ws 装饰器快速注册路由
- module_name 为必填第一个参数,决定路径前缀
- 支持 route group 进行版本管理和路由分组
- 支持 CORS 和安全响应头配置化
函数列表
_to_http_response(result: Any) -> Any
内部方法 HTTP handler 返回值的元组约定后处理
(body, status_code) / (body, status_code, headers) 形式的元组
转为对应状态码的 JSONResponse;其余返回值原样透传(dict/str/Response
由 FastAPI 原生机制处理,保持既有行为)。
_load_web_stack() -> None
懒加载 FastAPI / Uvicorn / Starlette
内部方法 将 web 栈依赖推迟到路由实际服务时才导入。幂等:重复调用仅做一次实际导入。
_web_stack_required(fn: Callable[..., Any]) -> Callable[..., Any]
装饰器:在被装饰方法执行前确保 web 栈已加载
内部方法 自动适配同步与异步方法。
- fn (
Callable): 被装饰的方法
返回值 (Callable): 包装后的方法
类列表
class FuncMiddleware
函数式路由中间件包装
内部方法
class RouteGroup
路由分组
提示 通过 sdk.router.group() 创建,支持版本前缀和嵌套分组
示例:
api = sdk.router.group("MyModule", "/api", version="1", tags=["API"])
@api.get("/users")
async def users(request):
return {"users": []}
方法列表
__init__(module_name: str, prefix: str, version: str | None = None, tags: list[str] | None = None, middlewares: list | None = None, router: RouterManager | None = None)
初始化路由分组
- module_name (
str): 模块名称 (路径前缀) - prefix (
str): 路由前缀 - version (
str): 版本号 (可选, 如 "1") - tags: list[str] API 文档标签 (可选)
- middlewares (
list): 分组级中间件 (可选) - router (
RouterManager): 路由管理器实例
_resolve_path(path: str) -> str
解析完整路径
内部方法
http(path: str, methods: list[str] | None = None, **kwargs) -> Callable
HTTP 路由装饰器
- path (
str): 路由路径 - methods: list[str] HTTP 方法列表 (默认: ["POST"])
返回值 (Callable): 装饰器
get(path: str, **kwargs) -> Callable
GET 路由装饰器
- path (
str): 路由路径
返回值 (Callable): 装饰器
post(path: str, **kwargs) -> Callable
POST 路由装饰器
- path (
str): 路由路径
返回值 (Callable): 装饰器
put(path: str, **kwargs) -> Callable
PUT 路由装饰器
- path (
str): 路由路径
返回值 (Callable): 装饰器
delete(path: str, **kwargs) -> Callable
DELETE 路由装饰器
- path (
str): 路由路径
返回值 (Callable): 装饰器
ws(path: str, **kwargs) -> Callable
WebSocket 路由装饰器
- path (
str): 路由路径 - auth_handler (
Callable): 认证函数 (可选) - auto_accept (
bool): 是否自动 accept (默认: True)
sse(path: str, **kwargs) -> Callable
SSE (Server-Sent Events) 路由装饰器
- path (
str): 路由路径
group(prefix: str, **kwargs) -> RouteGroup
创建嵌套分组
- prefix (
str): 子路由前缀
返回值 (RouteGroup): 嵌套分组实例
示例:
api = sdk.router.group("MyModule", "/api", version="1")
users = api.group("/users")
@users.get("/")
async def list_users(request):
...
class RouterManager
路由管理器
提示 核心功能:
- HTTP/WebSocket 路由注册
- 路由中间件 (前/后置处理)
- 自动 OpenAPI 文档 (/docs, /redoc)
- 路由限流 (rate_limit 参数)
- 路由分组/版本管理
- CORS / 安全头配置化
方法列表
_erispulse_version() -> str(staticmethod)
惰性获取 SDK 版本号(首次访问经包元数据读取,结果缓存)
内部方法 避免在导入期为读版本号而加载 importlib.metadata 依赖链
__init__()
初始化路由管理器
提示 首次访问
app属性时才创建 FastAPI 实例并注册核心路由。
app -> FastAPI(property)
FastAPI 应用实例(惰性创建,首次访问时加载 web 栈并注册核心路由)
_normalize_path(prefix: str, path: str) -> str
标准化路径,确保格式正确
- prefix (
str): 路径前缀(如模块名) - path (
str): 路径部分
返回值 (str): 标准化后的完整路径
内部方法
_track_owner_namespace(namespace: str) -> None
内部方法 若当前处于加载上下文(current_owner 已设置),记录命名空间归属, 以便后续按 owner 兜底清理路由。
适配器常以"平台名"作为 owner,却使用更细颗粒度的命名空间 (如 onebot11_default)注册路由。仅靠 unregister_all_by_namespace(平台名) 无法覆盖这些路由,故在此自动建立 owner -> namespace 的映射。
_make_http_endpoint(handler: Callable) -> Callable
根据处理器签名创建 FastAPI 兼容的 HTTP 端点
自动检测第一个参数的类型注解:
- fastapi.Request → 直接透传(向后兼容)
- HttpRequest / 无注解且名称类似 request → 注入 HttpRequest 包装
- 其他类型 / 非请求参数名 → 不注入
返回值支持元组约定:(body, status_code) / (body, status_code, headers) 自动转为对应状态码的 JSONResponse(详见 respond);
dict/str/Response 照旧由 FastAPI 原生机制处理。
内部方法
_make_ws_handler(handler: Callable) -> Callable
根据处理器签名创建 WebSocket 处理器包装
- fastapi.WebSocket 注解 → 提取 .raw 透传
- WebSocketConnection / 无注解 → 直接传递 WebSocketConnection
内部方法
_make_ws_auth_handler(auth_handler: Callable) -> Callable
根据签名创建 WebSocket 认证处理器包装
内部方法
_make_sse_endpoint(handler: Callable, module_name: str = '', track: bool = True) -> Callable
根据处理器签名创建 SSE 端点包装器
自动检测处理器是否需要 HttpRequest 参数。 为处理器创建 SseEmitter 实例,通过回调桥接 SSE 协议到底层 StreamingResponse。 track=True 时连接自动登记进连接池(kind="sse"),断开时自动注销。
内部方法
_create_sse_route(full_path: str, module_name: str, handler: Callable, track: bool = True, **kwargs) -> None
内部方法 在当前 app 实例上创建 SSE 路由(纯路由创建,不做重复检查、不写记录)
供 _register_sse_endpoint(新注册)与 _restore_routes_from_records(恢复)
共用,确保两条路径的路由创建逻辑完全一致。
_register_sse_endpoint(full_path: str, module_name: str, handler: Callable, track: bool = True, **kwargs) -> None
SSE 路由注册内部实现
内部方法
包含重复检查、owner 追踪、记录写入;路由创建委托 :meth:_create_sse_route。
async _run_ws_hooks(ws_conn: WebSocketConnection, hook_type: str, **kwargs) -> None(staticmethod)
执行 WebSocket 生命周期钩子
内部方法
_setup_core_routes() -> None
设置系统核心路由
内部方法
_setup_error_pages() -> None
设置错误页面
内部方法
为 GET 请求添加 ErisPulse 主题化错误页面。
POST 等非 GET 请求仍然返回 JSON 格式的错误响应。
所有错误码共用同一套 HTML 模板(render_error_page),仅注入不同的标题/描述。
_restore_routes_from_records() -> None
将内部记录中已有的路由重新注册到当前 FastAPI 实例
内部方法
_ensure_middleware_installed()
确保 FastAPI 级中间件已安装
内部方法
middleware(*paths: str) -> Callable
路由中间件装饰器
- paths (
str): 路径匹配模式 (支持通配符), 留空则为全局中间件
返回值 (Callable): 装饰器
提示 前置中间件签名: (request) -> request | Response 后置中间件签名: (request, response) -> response 根据函数参数数量自动判断是前置还是后置 paths 参数为 glob 模式路径匹配,如 "/MyModule/*",而非 (module_name, pattern)
示例:
@sdk.router.middleware()
async def log_all(request):
return request
@sdk.router.middleware("/MyModule/api/*")
async def auth_check(request):
return request
add_middleware(before: Callable | None = None, after: Callable | None = None, *paths: str) -> None
添加中间件函数
- before (
Callable): 前置中间件 (可选) - after (
Callable): 后置中间件 (可选) - paths (
str): 路径匹配模式, 留空为全局
register_home_entry(name: str | dict, url: str, icon_svg: str = '') -> None
在根路由页面注册一个入口按钮
name (
str | dict): 按钮显示文本。纯文本直接传入字符串;也可传入 i18n 字典格式: {"i18n": "key", "default": "兜底"}url (
str): 按钮链接地址icon_svg (
str): 可选 SVG 图标标记
示例:
# 纯文本
router.register_home_entry(name="Dashboard", url="/Dashboard")
# i18n 字典格式
router.register_home_entry(
name={"i18n": "core.router.entry_dashboard", "default": "Dashboard"},
url="/Dashboard",
)
# 带 SVG 图标
router.register_home_entry(
name="控制台",
url="/console",
icon_svg='<svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M4 17l6-6-6-6"/></svg>',
)
unregister_home_entries_by_owner(owner: str) -> int
移除指定归属者注册的全部首页入口按钮
- owner: 归属者(模块名或适配器平台名)
返回值 (int): 移除的入口数量
_match_path(pattern: str, path: str) -> bool(staticmethod)
通配符路径匹配
- pattern (
str): 匹配模式 - path (
str): 实际路径
返回值 (bool): 是否匹配
内部方法
_shadow_registration() -> bool
内部方法 当前注册上下文是否属于影子 owner(方向十一:只登记不挂载)
_mount_route(route: Any) -> Any
内部方法 把 route 挂载到 Starlette app(全路由唯一挂载点)
影子 owner 注册的路由只登记不挂载:route 由调用方经
_save_route_object 留档,counts 审计可见、reclaim 可清,
但对真实流量不可达。
- route: APIRoute / WebSocketRoute 路由对象
返回值: 路由对象(供 WS 等调用方留存)
_save_route_object(namespace: str, full_path: str, kind: str, route: Any) -> None
内部方法 记录 route 对象引用(kind ∈ {"http", "ws", "sse"})
_take_saved_routes(namespace: str, full_path: str, kind: str) -> list[Any]
内部方法 取出指定类型的已保存 route 对象(其它类型的索引条目保留)
_http_decorate(full_path: str, module_name: str, methods: list[str] | None = None, **kwargs)
HTTP 路由装饰器内部实现
内部方法
_ws_decorate(full_path: str, module_name: str, **kwargs)
WebSocket 路由装饰器内部实现
内部方法
_resolve_namespace(module_name_or_path: str, path: str | None) -> tuple[str, str]
内部方法 解析装饰器路由的命名空间与路径
双参形态
@router.get("MyModule", "/path"):显式命名空间,规则不变单参形态
@router.get("/path")/@router.ws("api"):命名空间 自动归属当前 owner(模块/适配器加载上下文),与其余触发器 (命令 / 事件处理器)的归属规则一致module_name_or_path: 双参时为模块名,单参时为路径
path: 双参路径;单参形态为 None
返回值: (namespace, path)
异常: ValueError - 单参形态且无归属上下文时
http(module_name_or_path: str, path: str | None = None, methods: list[str] | None = None, **kwargs) -> Callable
HTTP 路由装饰器
支持两种形态(推荐单参,与命令/事件触发器一致):
@router.http("/api/data"):命名空间自动归属当前模块(加载上下文)@router.http("MyModule", "/api/data"):显式命名空间module_name_or_path (
str): 模块名称或路由路径(单参形态)path (
str | None): 路由路径(双参形态时传入)methods: list[str] HTTP 方法列表 (默认: ["POST"])
rate_limit (
str|dict): 限流规则 (可选)summary: str API 摘要 (可选, 用于文档)
description: str API 描述 (可选, 用于文档)
tags: list[str] API 标签 (可选, 用于文档分组)
response_model (
type): 响应模型 (可选)deprecated (
bool): 是否废弃 (可选)
返回值 (Callable): 装饰器
示例:
# 单参(推荐):自动归属 模块名/api/data
@sdk.router.http("/api/data", methods=["GET", "POST"])
async def handle_data(request):
return {"ok": True}
# 双参:显式指定模块名
@sdk.router.http("MyModule", "/api/data", methods=["GET", "POST"])
async def handle_data(request):
return {"ok": True}
get(module_name_or_path: str, path: str | None = None, **kwargs) -> Callable
GET 路由装饰器
单参形态 @router.get("/path") 命名空间自动归属当前模块;
双参形态 @router.get("MyModule", "/path") 显式指定。
- module_name_or_path (
str): 模块名称或路由路径(单参形态) - path (
str | None): 路由路径(双参形态时传入)
返回值 (Callable): 装饰器
post(module_name_or_path: str, path: str | None = None, **kwargs) -> Callable
POST 路由装饰器(单参/双参形态见 :meth:get)
- module_name_or_path (
str): 模块名称或路由路径(单参形态) - path (
str | None): 路由路径(双参形态时传入)
返回值 (Callable): 装饰器
put(module_name_or_path: str, path: str | None = None, **kwargs) -> Callable
PUT 路由装饰器(单参/双参形态见 :meth:get)
- module_name_or_path (
str): 模块名称或路由路径(单参形态) - path (
str | None): 路由路径(双参形态时传入)
返回值 (Callable): 装饰器
delete(module_name_or_path: str, path: str | None = None, **kwargs) -> Callable
DELETE 路由装饰器(单参/双参形态见 :meth:get)
- module_name_or_path (
str): 模块名称或路由路径(单参形态) - path (
str | None): 路由路径(双参形态时传入)
返回值 (Callable): 装饰器
ws(module_name_or_path: str, path: str | None = None, **kwargs) -> Callable
WebSocket 路由装饰器
单参形态 @router.ws("api") 命名空间自动归属当前模块(实际路径
模块名/api);双参形态 @router.ws("MyModule", "/api") 显式指定。
module_name_or_path (
str): 模块名称或 WebSocket 路径(单参形态)path: str | None WebSocket 路径(双参形态时传入)
auth_handler (
Callable): 认证函数 (可选)auto_accept (
bool): 是否自动 accept (默认: True)track (
bool): 是否将连接自动登记进连接池 (默认: True;登记后 handler 内 ``ws.id`` 可用,可 join_group / 被广播)
提示 推荐单参注册与 auth_handler 进行连接确认,而非关闭 auto_accept。 仅在需要完全控制连接流程时才设置 auto_accept=False。
示例:
# 单参(推荐):自动归属 模块名/chat
@sdk.router.ws("chat")
async def chat(websocket):
websocket.join_group("chat")
await websocket.send_text("Hello!")
# 双参:显式指定模块名
@sdk.router.ws("MyModule", "/ws/chat")
async def chat(websocket):
await websocket.send_text("Hello!")
sse(module_name_or_path: str, path: str | None = None, **kwargs) -> Callable
SSE (Server-Sent Events) 路由装饰器
单参形态 @router.sse("/events") 命名空间自动归属当前模块;
双参形态 @router.sse("MyModule", "/events") 显式指定。
- module_name_or_path (
str): 模块名称或 SSE 端点路径(单参形态) - path: str | None SSE 端点路径(双参形态时传入)
- track (
bool): 是否将连接自动登记进连接池 (默认: True) - summary: str API 摘要 (可选)
- description: str API 描述 (可选)
- tags: list[str] API 标签 (可选)
示例:
# 单参(推荐):自动归属 模块名/events
@sdk.router.sse("/events")
async def event_stream(sse):
sse.join_group("dashboard")
while True:
await sse.send({"msg": "hello"})
await asyncio.sleep(1)
# 双参:显式指定模块名
@sdk.router.sse("MyModule", "/logs")
async def log_stream(request, sse):
token = request.query_params.get("token")
while True:
line = await get_next_log(token)
await sse.send(line, event="log")
_sse_decorate(full_path: str, module_name: str, **kwargs)
SSE 路由装饰器内部实现
内部方法
register_http_route(module_name: str, path: str, handler: Callable, methods: list[str] | None = None, rate_limit: str | dict | None = None, summary: str | None = None, description: str | None = None, tags: list[str] | None = None, response_model: type | None = None, deprecated: bool | None = None) -> None
注册HTTP路由
- module_name (
str): 模块名称 - path (
str): 路由路径 - handler (
Callable): 处理函数 - methods: list[str] HTTP方法列表(默认["POST"])
- rate_limit (
str|dict|None): 限流规则 (可选, 如 "10/minute") - summary: str API 摘要 (可选)
- description: str API 描述 (可选)
- tags: list[str] API 标签 (可选)
- response_model (
type): 响应模型 (可选) - deprecated (
bool): 是否废弃 (可选)
异常: ValueError - 当路径和方法都已注册时抛出
register_webhook(*args, **kwargs) -> None
兼容性方法:注册HTTP路由(适配器旧接口)
unregister_http_route(module_name: str, path: str) -> bool
取消注册HTTP路由
- module_name: 模块名称
- path: 路由路径
返回值 (bool): 是否成功取消注册
_make_ws_endpoint_fn(full_path: str, module_name: str, wrapped_handler: Callable, wrapped_auth: Callable | None, auto_accept: bool, track: bool = True) -> Callable[[WebSocket], Awaitable[None]]
内部方法 构建 WebSocket 端点处理函数(注册与恢复路由共用同一实现)
- full_path: 完整路由路径
- module_name: 模块名
- wrapped_handler: 已包装的 WebSocket 处理器
- wrapped_auth: 已包装的鉴权处理器(可为 None)
- auto_accept: 是否自动 accept 连接
- track: 是否将连接自动登记进连接池(ErisPulse.connections)
返回值 (WebSocket): 端点协程函数
_register_ws_endpoint(full_path: str, module_name: str, handler: Callable[[WebSocket], Awaitable[Any]], auth_handler: Callable[[WebSocket], Awaitable[bool]] | None = None, auto_accept: bool = DEFAULT_WS_AUTO_ACCEPT, track: bool = True) -> None
WebSocket 路由注册内部实现
内部方法
register_websocket(module_name: str, path: str, handler: Callable[[WebSocket], Awaitable[Any]], auth_handler: Callable[[WebSocket], Awaitable[bool]] | None = None, auto_accept: bool = True, track: bool = True) -> None
注册WebSocket路由
module_name (
str): 模块名称path: str WebSocket路径
handler: Callable[[WebSocket], Awaitable[Any]] 主处理函数
auth_handler: Optional[Callable[[WebSocket], Awaitable[bool]]] 认证函数
auto_accept (
bool): 是否自动调用 websocket.accept(),默认 Truetrack (
bool): 是否将连接自动登记进连接池(默认 True;登记后可经 ``connections`` 广播 / 分组 / 跨模块查看)
提示 推荐使用 auth_handler 进行连接确认,而非关闭 auto_accept。 auth_handler 在连接建立后执行,返回 False 会自动关闭连接。 仅在需要完全控制连接流程时才设置 auto_accept=False。
异常: ValueError - 当路径已注册时抛出
unregister_websocket(module_name: str, path: str) -> bool
取消注册WebSocket路由
- module_name: 模块名称
- path (
WebSocket): 路径
返回值 (bool): 是否成功取消注册
register_sse(module_name: str, path: str, handler: Callable, **kwargs) -> None
注册 SSE (Server-Sent Events) 路由
SSE 路由为 HTTP GET 端点,返回 text/event-stream 流式响应。
处理器接收 SseEmitter 实例(以及可选的 HttpRequest),
通过 sse.send() 推送事件,调用 sse.close() 断开连接。
- module_name (
str): 模块名称 - path: str SSE 端点路径
- handler (
Callable): 事件处理器, 签名:async def handler(sse)或async def handler(request, sse) - track (
bool): 是否将连接自动登记进连接池(默认 True)
异常: ValueError - 当路径已注册时抛出
示例:
async def event_stream(sse):
for i in range(10):
await sse.send({"count": i})
await asyncio.sleep(1)
router.register_sse("MyModule", "/events", event_stream)
unregister_sse(module_name: str, path: str) -> bool
取消注册 SSE 路由
- module_name: 模块名称
- path (
SSE): 路径
返回值 (bool): 是否成功取消注册
unregister_all_by_namespace(namespace: str) -> dict[str, int]
清理指定命名空间下的所有路由
- namespace: 命名空间(适配器名或模块名)
返回值 (dict): 清理统计 {"http_count": int, "websocket_count": int, "sse_count": int}
unregister_all_by_owner(owner: str) -> dict[str, int]
清理指定归属者注册的所有路由 / 中间件 / 首页入口
与 :meth:unregister_all_by_namespace 不同,本方法基于注册期间
通过 current_owner 自动追踪的归属关系进行清理,适用于"以平台名
为 owner、却用更细颗粒度命名空间(如 onebot11_default)注册路由"
的适配器热重载场景,也用于模块卸载时的兜底清理(覆盖中间件与
首页入口等不携带命名空间的资源)。
- owner: 归属者(适配器平台名或模块名)
返回值 (dict): 清理统计 {"http_count", "websocket_count", "sse_count", "middleware_count", "home_entry_count"}
list_namespaces() -> dict[str, dict[str, list[str]]]
列出所有已注册的命名空间及其路由
返回值: dict {namespace: {"http": [paths], "websocket": [paths], "sse": [paths]}}
示例:
router.list_namespaces()
{
"onebot11": {
"http": ["/onebot11/webhook", "/onebot11/callback"],
"websocket": ["/onebot11/ws"],
"sse": ["/onebot11/events"]
}
}
get_module_routes(module_name: str) -> dict[str, list[dict]]
获取指定命名空间的详细路由信息
与 list_namespaces() 不同,此方法返回每个路由的详细信息:
HTTP 路由包含路径和 HTTP 方法列表
WebSocket 路由包含路径和是否需要认证
SSE 路由包含路径和流式标记
module_name: 模块/平台名称
返回值: {"http": [...], "websocket": [...], "sse": [...]}
http: [{"path": str, "methods": [str]}] websocket: [{"path": str, "auth": bool}] sse: [{"path": str, "streaming": true}]
示例:
router.get_module_routes("onebot11")
{
"http": [{"path": "/onebot11/webhook", "methods": ["POST"]}],
"websocket": [{"path": "/onebot11/ws", "auth": true}],
"sse": [{"path": "/onebot11/events", "streaming": true}]
}
get_module_urls(module_name: str) -> dict[str, Any]
获取指定命名空间的完整连接 URL
在 get_module_routes() 的基础上拼接 base_url,生成可直接使用的完整 URL。 HTTP 路由使用 base_url 前缀,WebSocket 路由自动将 http/https 转换为 ws/wss, SSE 路由使用 base_url 前缀(HTTP)。
- module_name: 模块/平台名称
返回值: {
"base_url": str,
"http": [{"path": str, "method": str, "url": str}],
"websocket": [{"path": str, "url": str}],
"sse": [{"path": str, "url": str}]
}
示例:
# 假设 base_url = "http://localhost:8080"
router.get_module_urls("onebot11")
{
"base_url": "http://localhost:8080",
"http": [
{"path": "/onebot11/webhook", "method": "POST",
"url": "http://localhost:8080/onebot11/webhook"}
],
"websocket": [
{"path": "/onebot11/ws",
"url": "ws://localhost:8080/onebot11/ws"}
],
"sse": [
{"path": "/onebot11/events",
"url": "http://localhost:8080/onebot11/events"}
]
}
get_module_urls_matching(prefix: str) -> dict[str, Any]
获取指定前缀的所有命名空间的聚合连接 URL
适配器多账户场景下,路由可能注册为 yunhu_bot1、yunhu_bot2 等命名空间。
此方法按前缀匹配聚合所有相关命名空间的路由信息。
- prefix: 命名空间前缀(如 "yunhu")
返回值: {
"base_url": str,
"http": [{"path": str, "method": str, "url": str, "namespace": str}],
"websocket": [{"path": str, "url": str, "namespace": str}],
"sse": [{"path": str, "url": str, "namespace": str}]
}
示例:
# 命名空间: yunhu_bot1, yunhu_bot2, onebot11
router.get_module_urls_matching("yunhu")
{
"base_url": "http://localhost:8080",
"http": [
{"path": "/yunhu_bot1/webhook", "method": "POST",
"url": "http://localhost:8080/yunhu_bot1/webhook",
"namespace": "yunhu_bot1"},
{"path": "/yunhu_bot2/webhook", "method": "POST",
"url": "http://localhost:8080/yunhu_bot2/webhook",
"namespace": "yunhu_bot2"}
],
"websocket": [],
"sse": []
}
group(module_name: str, prefix: str, **kwargs) -> RouteGroup
创建路由分组
- module_name (
str): 模块名称 (必填) - prefix (
str): 路由前缀 - version (
str): 版本号 (可选) - tags: list[str] API 标签 (可选)
- middlewares (
list): 分组中间件 (可选)
返回值 (RouteGroup): 路由分组实例
示例:
api = sdk.router.group("MyModule", "/api", version="1")
@api.get("/users")
async def users(request):
return {"users": []}
_rate_limit_client_ip(request: Request) -> str
限流键客户端地址
默认取直连地址(request.client.host);配置
ErisPulse.router.rate_limit_trust_proxy 为 true 后取
X-Forwarded-For 首个地址(仅在可信反向代理后启用,避免伪造)。
- request: 请求对象
返回值 (str): 用于限流键的客户端地址
_apply_rate_limit(full_path: str, limit: str | dict)
为路由应用限流
内部方法
_parse_rate_limit(limit: str | dict) -> tuple[int, int](staticmethod)
解析限流规则
- limit (
str|dict): 限流规则
返回值: tuple[int, int] (max_requests, window_seconds)
内部方法
setup_cors(allow_origins: list[str] | None = None, allow_methods: list[str] | None = None, allow_headers: list[str] | None = None, allow_credentials: bool = False, max_age: int = DEFAULT_CORS_MAX_AGE_SECS, expose_headers: list[str] | None = None) -> None
配置 CORS
- allow_origins (
list[str]): 允许的来源 (默认: ["*"]) - allow_methods (
list[str]): 允许的方法 (默认: ["*"]) - allow_headers (
list[str]): 允许的头 (默认: ["*"]) - allow_credentials (
bool): 允许凭据 (默认: False) - max_age (
int): 预检缓存时间 (默认: 600) - expose_headers (
list[str]): 暴露的响应头 (可选)
示例:
sdk.router.setup_cors(
allow_origins=["https://example.com"],
allow_methods=["GET", "POST"],
)
setup_security_headers(headers: dict[str, str] | None = None) -> None
配置安全响应头
- headers (
dict[str, str]): 自定义安全头 (可选, 会合并默认值)
示例:
sdk.router.setup_security_headers({
"Strict-Transport-Security": "max-age=31536000",
})
disable_docs() -> None
关闭 API 文档端点(生产环境推荐)
示例:
sdk.router.disable_docs()
set_docs_info(title: str | None = None, description: str | None = None) -> None
更新 API 文档信息
- title (
str): 文档标题 (可选) - description (
str): 文档描述 (可选)
_apply_config()
从配置文件自动应用 CORS 和安全头
内部方法
_on_router_config_changed(_data: dict) -> None
router 中间件配置变更回调:CORS/安全头需重启进程才能生效
get_app() -> FastAPI
获取FastAPI应用实例
返回值 (FastAPI): 应用实例
_get_local_ips() -> None
获取本机局域网IP地址
内部方法
_build_ssl_context_from_pem(cert_pem: str, key_pem: str)(staticmethod)
内部方法 从 PEM 文本内容构建 SSLContext
将证书/密钥写入临时文件(load_cert_chain 需要文件路径),加载完成后 立即删除临时文件——PEM 内容不落盘残留。
- cert_pem: 证书 PEM 文本
- key_pem: 密钥 PEM 文本
返回值: ssl.SSLContext
_create_uvicorn_server(config: uvicorn.Config) -> tuple[uvicorn.Server, Callable[[], Any]]
构建 uvicorn.Server 并解析内嵌启动入口(私有接口缺失时告警回退)
内部方法
内嵌启动优先调用私有方法 Server._serve()(跳过 serve() 的
capture_signals——后者会抢注进程信号并在退出时重抛,与 SDK 的
信号管理冲突),该接口自 uvicorn 0.34.0 引入且属私有 API。
兼容性按能力探测判定(仅检查接口是否存在、不比较版本):
接口存在即直接使用,上游大版本更新若保留该接口则无需跟进发版;
缺失时仅告警并回退公开 serve()(服务期间进程信号由 uvicorn
暂时接管,属可接受的降级),建议用户前往 uvicorn 仓库确认其正式
支持情况。已验证范围见 :data:UVICORN_COMPAT_RANGE(与
pyproject.toml 锁定一致)。
- config: 已构建的 :class:
uvicorn.Config
返回值: (server, serve_entry) 二元组——Server 实例与启动协程
工厂(调用即返回待调度协程,供 ``asyncio.create_task`` 使用)
async start(host: str = DEFAULT_SERVER_HOST, port: int = DEFAULT_SERVER_PORT, ssl_certfile: str | None = None, ssl_keyfile: str | None = None, *, ssl_cert: str | None = None, ssl_key: str | None = None) -> None
启动路由服务器
SSL 支持两种配置方式(内容优先于路径):
路径方式:
ssl_certfile/ssl_keyfile传入证书/密钥文件路径内容方式:
ssl_cert/ssl_key直接传入 PEM 文本内容 (适合容器/无文件系统场景,框架落盘临时文件构建 SSLContext 后即删除)host (
str): 监听地址(默认"0.0.0.0")port (
int): 监听端口(默认8000)ssl_certfile: str | None SSL证书路径
ssl_keyfile: str | None SSL密钥路径
ssl_cert: str | None SSL证书 PEM 文本内容(优先于 ssl_certfile)
ssl_key: str | None SSL密钥 PEM 文本内容(优先于 ssl_keyfile)
异常: RuntimeError - 当服务器已在运行时抛出
.. note:
端口被占用时不视为致命错误:服务器不启动,但机器人继续运行。
async _stop_uvicorn_listener() -> None
仅停止 uvicorn 监听(不清理路由等应用状态,供 reload 复用)
与 :meth:stop 的区别:stop 面向完整关停(路由 / 限流任务 / 命名
空间一并清理),本方法只停服务器进程本体,模块注册的路由全部保留。
内部方法
async _launch_uvicorn(params: dict[str, Any]) -> bool
以给定参数构建并启动 uvicorn 服务器(reload 复用)
内联 PEM 优先于证书路径(与 :meth:start 同口径);启动后等待
uvicorn 完成监听绑定,启动失败(端口被抢占、绑定异常)返回 False。
params: 服务器参数(host / port / ssl_certfile / ssl_keyfile
/ ssl_cert / ssl_key)
返回值 (bool): 服务器是否成功进入监听状态
内部方法
async reload(host: str | None = None, port: int | None = None, ssl_certfile: str | None = None, ssl_keyfile: str | None = None, *, ssl_cert: str | None = None, ssl_key: str | None = None) -> bool
运行时热重载路由服务器(host / port / SSL),无需进程重启
复用同一 FastAPI 应用实例,模块已注册的 http / ws / sse 路由全部
保留。参数缺省时沿用当前生效配置(start() 记录的参数)。
切换顺序保证 返回 False = 旧服务保持可用:先验证新 SSL 配置 可构建,再停止旧监听并以新参数重建;新监听启动失败(端口被抢占、 绑定异常)时以旧配置重新拉起服务。
- host (
str | None): 监听地址(缺省沿用当前值) - port (
int | None): 监听端口(缺省沿用当前值) - ssl_certfile: str | None SSL证书路径(缺省沿用当前值)
- ssl_keyfile: str | None SSL密钥路径(缺省沿用当前值)
- ssl_cert: str | None SSL证书 PEM 文本内容(优先于 ssl_certfile)
- ssl_key: str | None SSL密钥 PEM 文本内容(优先于 ssl_keyfile)
返回值 (bool): 重载是否成功;False 时旧配置服务保持可用
示例:
await router.reload(port=9000) # 修改监听端口
await router.reload(ssl_cert=new_pem, ssl_key=new_key) # 热更换证书
_check_port_available(host: str, port: int) -> None
检测端口是否被占用(有进程正在监听)
使用 connect 而非 bind 探测:bind 会因上次进程退出后的
TIME_WAIT 残留而误判端口被占用,导致重启死循环;connect 只在
端口有活跃监听者时才成功,能准确区分"真正占用"与"TIME_WAIT 残留"。
- host (
str): 监听地址 - port (
int): 监听端口
异常: RuntimeError - 当端口被占用时抛出,携带友好的错误提示
_start_rate_limit_cleanup() -> None
内部方法 启动限流存储的定期清理后台任务
定期扫描 _rate_limit_store,移除窗口已过期的 IP 记录,防止长期运行时无限增长。
_stop_rate_limit_cleanup() -> None
内部方法 停止限流存储定期清理任务
_cleanup_expired_rate_limits() -> int
内部方法 清除过期的限流记录
扫描 _rate_limit_store,移除所有时间戳均已超出限流窗口的条目。
返回值 (int): 被清除的条目数
async stop() -> None
停止服务器并清理所有路由
_format_display_url(url: str) -> str
格式化URL显示
- url (
str): 原始URL
返回值 (str): 格式化后的URL