ErisPulse ErisPulse
在互動式文檔中心打開 →
本頁章節
本文為靜態鏡像,內容以互動版為準 在互動式文檔中心打開 →

路由管理器

Tip

什麼時候需要閱讀這篇:需要 HTTP / WebSocket / SSE 路由(含連接池廣播)時。不需要則跳過,不影響其它功能的使用。

ErisPulse 路由管理器提供統一的 HTTP 和 WebSocket 路由管理,支援多適配器路由註冊和生命週期管理。底層透過抽象層封裝(目前為 FastAPI + Uvicorn)

概述

路由管理器的主要功能:

  • 裝飾器路由:支援 @http / @get / @post / @put / @delete / @ws 裝飾器快捷註冊
  • 自動注入:路由處理器無需導入 FastAPI 類型,框架自動注入抽象物件
  • 路由分組:支援帶前綴和版本號的 RouteGroup
  • 路由中間件:支援 glob 模式匹配的請求攔截
  • 速率限制:內建滑動窗口限流
  • CORS 支援:一鍵開啟跨域資源共享
  • 安全頭:自動添加安全回應頭
  • 自動文件:基於 OpenAPI 的互動式文件
  • WebSocket 支援:完整的 WebSocket 連接管理、自訂認證和生命週期鉤子
  • 生命週期集成:與 ErisPulse 生命週期系統深度集成
  • SSL/TLS 支援:支援 HTTPS 和 WSS 安全連接
  • 主頁入口:支援模組在根路由 / 註冊快捷入口按鈕,支援國際化

抽象類型

ErisPulse 提供了服務端抽象類型,使模組無需直接依賴 FastAPI:

抽象類型 FastAPI 對應 說明
HttpRequest fastapi.Request HTTP 請求封裝,介面完全相容
WebSocketConnection fastapi.WebSocket WebSocket 連接封裝,額外提供生命週期鉤子
WebSocketDisconnect fastapi.WebSocketDisconnect WebSocket 斷開異常

WebSocketConnection 繼承自 WebSocketConnectionBase,與客戶端 WebSocket (ClientWebSocket) 共享相同的 send/receive/iter/close 介面。客戶端和服務端 WebSocket 可以使用相同的業務邏輯程式碼。

透過 .raw 屬性可存取底層 FastAPI 原生物件。直接使用 FastAPI 類型的程式碼也完全相容。

裝飾器路由(推薦)

註冊形態:單參(推薦)與雙參

裝飾器路由支援兩種形態,推薦單參——與命令 / 事件觸發器一致,命名空間自動歸屬當前模組:

from ErisPulse import router

# 單參(推薦):自動歸屬 模組名/hello → 實際路徑 /my_module/hello
@router.get("/hello")
async def hello():
    return {"ok": True}

# 單參 WebSocket:@ws("chat") → /my_module/chat
@router.ws("chat")
async def chat(ws):
    ...

# 雙參:顯式指定模組名(規則不變,跨模組/工具程式碼註冊時使用)
@router.get("other_module", "/info")
async def get_info(request):
    return {"method": request.method, "path": str(request.url)}

Note

單參形態要求在模組/適配器加載上下文中註冊(加載期框架已注入歸屬); 在無歸屬上下文處呼叫會拋 ValueError 並提示顯式傳入模組名。

HTTP 裝飾器

from ErisPulse import router, HttpRequest

# 也可顯式標註抽象類型
@router.post("/data")
async def post_data(request: HttpRequest):
    data = await request.json()
    return {"received": data}

@router.put("/data/{item_id}")
async def update_data(request):
    return {"updated": True}

@router.delete("/data/{item_id}")
async def delete_data(request):
    return {"deleted": True}

自動注入規則:當處理器第一個參數名為 request 或 req 且無 FastAPI 類型註解時,框架自動注入 HttpRequest。無參數或非請求參數名的處理器不受影響。

回應返回約定(2.10+)

處理器返回值支援元組約定(推薦寫法,明確控制狀態碼),dict/str/Response 照舊:

@router.post("/login")
async def login(request):
    if not check_token(request):
        # (body, status_code) → 401 JSON
        return {"error": "unauthorized", "message": "token 無效"}, 401
    # (body, status_code, headers) 還可帶回應頭
    return {"user_id": 1}, 200, {"X-Request-Cost": "12ms"}

# 或使用 respond() 幫助函數(message 自動合併進回應體)
from ErisPulse import respond

@router.get("/me")
async def me():
    return respond({"user_id": 1}, status_code=200, message="ok")

路徑 / 查詢參數直接用 FastAPI 原生註解即可(item_id: int、page: int = 1), 中間件見路由中間件一節。

WebSocket 裝飾器

from ErisPulse import WebSocketConnection, WebSocketDisconnect

# 基本 WebSocket(單參形態)
@router.ws("ws")
async def websocket_handler(ws):
    async for msg in ws.iter_text():
        await ws.send_text(f"Echo: {msg}")

# 帶生命週期鉤子的 WebSocket
@router.ws("/ws/chat")
async def chat(ws: WebSocketConnection):
    @ws.on_disconnect
    async def on_disconnect(ws, reason="unknown"):
        print(f"使用者斷開: {reason}")

    @ws.on_error
    async def on_error(ws, error=""):
        print(f"連接錯誤: {error}")

    async for msg in ws.iter_text():
        await ws.send_text(f"Echo: {msg}")

# 帶認證的 WebSocket(金鑰從環境變數讀取,勿在程式碼中硬編碼)
import os

async def ws_auth(ws: WebSocketConnection) -> bool:
    token = ws.query_params.get("token")
    expected = os.environ.get("ERISPULSE_WS_TOKEN", "")
    return bool(expected) and token == expected

@router.ws("secure_ws", auth_handler=ws_auth)
async def secure_ws_handler(ws):
    while True:
        data = await ws.receive_text()
        await ws.send_text(f"Echo: {data}")

注意:WebSocket 處理器和認證處理器也支援自動注入。無需參數註解即可獲得 WebSocketConnection。標註 fastapi.WebSocket 也可傳入原生物件,但推薦使用抽象類型。

連接自動登記(連接池,2.10+)

@ws / @sse 建立的連接預設自動登記進框架連接池(track=False 可關閉): handler 內 ws.id / ws.join_group(...) 可用,任意模組可 connections.list(namespace=...) 查看本模組連接、向分組廣播。 詳見連接池與廣播。

傳統註冊方式

async def hello_handler(request):
    return {"message": "Hello World"}

# 基本註冊
router.register_http_route(
    module_name="my_module",
    path="/hello",
    handler=hello_handler,
    methods=["GET"],
)

# 帶限流和文件資訊
router.register_http_route(
    module_name="my_module",
    path="/api/data",
    handler=data_handler,
    methods=["POST"],
    rate_limit="10/minute",
    summary="數據介面",
    tags=["API"],
)

WebSocket 註冊

from ErisPulse.Core import WebSocketConnection

async def websocket_handler(ws: WebSocketConnection):
    async for msg in ws.iter_text():
        await ws.send_text(f"Echo: {msg}")

# 基本註冊
router.register_websocket(
    module_name="my_module",
    path="/ws",
    handler=websocket_handler,
)

# 帶認證的註冊(推薦)
async def auth_handler(ws: WebSocketConnection) -> bool:
    token = ws.query_params.get("token")
    return token == "secret"

router.register_websocket(
    module_name="my_module",
    path="/secure_ws",
    handler=websocket_handler,
    auth_handler=auth_handler,
)

參數說明:

參數 說明 預設值
module_name 模組名稱(必須) -
path WebSocket 路徑 -
handler 處理函數 -
auth_handler 認證函數,回傳 False 會自動關閉連接 None
auto_accept 是否自動 accept() True

推薦:使用 auth_handler 進行連接確認,而非關閉 auto_accept。僅在你需要完全控制連接流程時才設定 auto_accept=False。

WebSocket 生命週期鉤子

WebSocketConnection 提供了斷開連接和錯誤的回調註冊,無需手動 try/catch:

from ErisPulse.Core import WebSocketConnection

@router.ws("my_module", "/ws")
async def my_ws(ws: WebSocketConnection):
    # 裝飾器方式註冊
    @ws.on_disconnect
    async def on_close(ws, reason="unknown"):
        print(f"斷開原因: {reason}")

    # 也可直接呼叫
    async def on_err(ws, error=""):
        print(f"錯誤: {error}")
    ws.on_error(on_err)

    # 正常業務邏輯
    async for msg in ws.iter_text():
        await ws.send_text(f"Echo: {msg}")

路由分組

# 創建帶前綴的路由組
group = router.group("my_module", prefix="/v1")

@group.get("/users")
async def list_users(request):
    return {"users": []}

@group.post("/users")
async def create_user(request):
    return {"created": True}

# 實際路徑: /my_module/v1/users

路由中間件

中間件支援 glob 模式匹配路徑:

@router.middleware("/my_module/*")
async def auth_middleware(request, call_next):
    token = request.headers.get("Authorization")
    if not token:
        return {"error": "Unauthorized"}
    return await call_next(request)

@router.middleware("/my_module/admin/*")
async def admin_middleware(request, call_next):
    return await call_next(request)

請求關聯 ID(X-Request-ID)

從 2.7.0 起,每個 HTTP 請求都會攜帶一個 X-Request-ID 關聯 ID,用於日誌 / 鏈路追蹤串聯:

  • 生成規則:優先沿用客戶端傳入的 X-Request-ID 請求頭(分散式追蹤場景);否則自生成 UUID
  • 回應頭:回應會回寫 X-Request-ID,方便客戶端把請求與日誌對應
  • 生命週期事件:server.request 與 server.response 事件資料中新增 request_id 字段
# 在模組中監聽請求事件,按 request_id 串聯請求-回應
@sdk.lifecycle.on("server.request")
async def on_request(data):
    print(f"[{data['request_id']}] {data['method']} {data['path']}")

@sdk.lifecycle.on("server.response")
async def on_response(data):
    print(f"[{data['request_id']}] -> {data['status_code']}")

客戶端可自定義 ID 以便跨服務追蹤:

curl -H "X-Request-ID: my-trace-id" http://localhost:8080/my_module/health

速率限制

使用滑動窗口演算法對路由進行限流:

@router.get("my_module", "/limited", rate_limit="10/minute")
async def limited_endpoint(request):
    return {"ok": True}

@router.post("my_module", "/submit", rate_limit="5/minute")
async def submit_data(request):
    return {"submitted": True}

速率限制格式:{次數}/{時間窗口},如 10/minute、100/hour。

CORS 配置

router.setup_cors(
    allow_origins=["https://example.com"],
    allow_methods=["GET", "POST"],
    allow_headers=["*"],
)

也可透過 config.toml 配置:

[router.cors]
allow_origins = ["https://example.com"]
allow_methods = ["GET", "POST"]
allow_headers = ["*"]

安全頭

router.setup_security_headers()

自動添加 X-Content-Type-Options、X-Frame-Options、X-XSS-Protection 等安全頭。

也可透過 config.toml 配置:

[router.security]
enabled = true

自動文件

Router 預設啟用 OpenAPI 互動式文件:

# 禁用文件
router.disable_docs()

# 自訂文件資訊
router.set_docs_info(
    title="我的 API",
    description="API 文件",
    version="1.0.0"
)

路徑處理

路由路徑會自動添加模組名稱作為前綴,避免衝突:

# 註冊路徑 "/api" 到模組 "my_module"
# 實際存取路徑為 "/my_module/api"
router.register_http_route("my_module", "/api", handler)

Warning

路由路徑(含模組名前綴)大小寫敏感。註冊時的模組名是什麼大小寫,實際路徑就是什麼大小寫:模組名為 Test 時註冊 /api 的實際路徑是 /Test/api,存取 /test/api 將回傳 404。

系統路由

路由管理器自動提供以下系統路由:

健康檢查

GET /health
# 回傳:
{"status": "ok", "service": "ErisPulse Router"}

根頁面

GET /
# 回傳 ErisPulse 品牌頁

根路由 / 顯示 ErisPulse 品牌頁面,自動檢測 Dashboard 可用性並添加入口按鈕。

主頁入口

路由管理器允許外部模組在根路由 / 上註冊快捷入口按鈕,方便使用者快速存取各模組的管理頁面。

註冊入口

# 簡單註冊
router.register_home_entry(
    name="我的面板",
    url="/mymodule/admin",
)

# 帶圖示的註冊(SVG)
router.register_home_entry(
    name="控制台",
    url="/console",
    icon_svg='<svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 17l6-6-6-6"/><path d="M12 19h8"/></svg>',
)

# 支援國際化的註冊(項目 i18n 字典格式)
router.register_home_entry(
    name={"i18n": "mymodule.home.entry", "default": "我的面板"},
    url="/mymodule/admin",
)

參數說明:

參數 類型 說明 必填
name str / dict 按鈕顯示文字;傳入 {"i18n": "key", "default": "文字"} 字典時使用國際化 是
url str 按鈕連結地址 是
icon_svg str 可選 SVG 圖示標記 否

Dashboard 自動註冊

當檢測到 sdk.Dashboard 可用時,路由管理器自動在入口列表首位添加 Dashboard 按鈕,無需手動註冊。

生命週期集成

from ErisPulse.Core import lifecycle

@lifecycle.on("server.start")
async def on_server_start(event):
    print(f"伺服器已啟動: {event['data']['base_url']}")

@lifecycle.on("server.stop")
async def on_server_stop(event):
    print("伺服器正在停止...")

請求物件高階屬性

HttpRequest 除了 method / query / headers / json / body 基礎層面外, 還暴露高階能力(鑑權中介軟體、斷線感知長時間任務常用):

屬性 / 方法 說明
request.session 會話 dict(需會話中介軟體支援),跨請求保持
request.auth 認證資訊(認證中介軟體寫入)
request.user 當前使用者物件(認證中介軟體寫入)
request.url_for(name, **params) 反向路由:按路由名稱生成 URL
await request.is_disconnected() 客戶端是否已斷線(SSE / 長時間任務輪詢退出用)
request.raw 底層 Starlette 請求物件(逃生艙,見下節相容性說明)

逃生艙:router.app

router.app 直接暴露底層 FastAPI 應用實例(惰性建立,首次存取載入 web 堆疊並註冊核心路由),涵蓋裝飾器表達不了的場景——掛載子應用、全域中介軟體、 接入 FastAPI 生態(StaticFiles / 背景任務模板等):

from ErisPulse.Core import router
from starlette.staticfiles import StaticFiles

app = router.app
app.mount("/static", StaticFiles(directory="static"), name="static")

Warning

相容性邊界:router.app 是逃生艙而非穩定契約——取得的是當前 web 堆疊(FastAPI/Starlette)的實例。框架日後若遷移底層 web 實作,依賴 app 內部結構(中介軟體順序、Starlette 特定 API)的程式碼會遇到破壞性 變更。優先使用 @router.http / HttpRequest 抽象層(request.raw 同理),並把 .app 的使用收斂在模組的獨立適配層裡——遷移時只需改一處。

最佳實踐

  1. 優先使用抽象類型:使用 HttpRequest / WebSocketConnection 替代 fastapi.Request / fastapi.WebSocket,避免硬依賴
  2. 利用自動注入:處理器第一個參數命名為 request 或 req,無需任何類型註解即可獲得 HttpRequest
  3. 單參形態優先:模組載入上下文中優先單參形態(自動歸屬命名空間);跨模組/工具程式碼註冊時顯式傳模組名
  4. 使用路由分組:對同一模組的多個路由使用 group() 組織
  5. 安全性考量:為敏感操作實作認證機制和安全標頭
  6. 合理限流:對高頻介面設定速率限制
  7. 使用生命週期鉤子:透過 @ws.on_disconnect / @ws.on_error 處理 WebSocket 異常,避免手動 try/catch
  8. 逃生艙收斂使用:router.app / request.raw 僅在抽象層表達不了時使用,並把依賴收斂到單點,降低框架底層遷移時的適配面

相關文件