A. 簡介
Consumer 本身是有效的 ASGI 應用程式,也可以單獨交給伺服器使用;當專案需要處理多種連線或多個 Consumer 時,Channels 的路由類別可將它們與其他 ASGI 應用程式組合,依 scope 中的協定及路徑選擇對應的處理者。
Channels 的路由器僅在範圍(scope)層工作,而不是在個別事件的層次上運作,這意味著對於任何給定的連接,你只能指定一個消費者。路由的目的是決定要將一條連接交給哪個單一消費者,而非將一個連接的事件分散至多個消費者。
路由器本身也遵循 ASGI 介面,可以分層組合。常見安排是以 ProtocolTypeRouter 作為根入口,再使用協定專屬的路由器;根應用程式的匯入路徑由 ASGI_APPLICATION 設定,通常放在專案層的 asgi.py,與 urls.py 並列。
以下是asgi.py的範例:
import os
from channels.auth import AuthMiddlewareStack
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.security.websocket import AllowedHostsOriginValidator
from django.core.asgi import get_asgi_application
from django.urls import path
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "mysite.settings")
# Initialize Django ASGI application early to ensure the AppRegistry
# is populated before importing code that may import ORM models.
django_asgi_app = get_asgi_application()
from chat.consumers import AdminChatConsumer, PublicChatConsumer
application = ProtocolTypeRouter({
# Django's ASGI application to handle traditional HTTP requests
"http": django_asgi_app,
# WebSocket chat handler
"websocket": AllowedHostsOriginValidator(
AuthMiddlewareStack(
URLRouter([
path("chat/admin/", AdminChatConsumer.as_asgi()),
path("chat/", PublicChatConsumer.as_asgi()),
])
)
),
})
在配置 Django Channels 的路由時,我們會使用 `as_asgi()` 類方法。這個方法會返回一個 ASGI 包裝應用程序,這樣每當有新的連線或 scope(範圍)時,就會自動實例化一個新的 consumer(消費者)實例。這種設計理念與 Django 的 `as_view()` 類似,後者是在每個請求中為 class-based views(基於類的視圖)創建相應的實例。
B. ProtocolTypeRouter
channels.routing.ProtocolTypeRouter
在建立 Django Channels 應用時,ASGI(Asynchronous Server Gateway Interface)應用程式堆疊的頂層應用,通常會是在路由檔案(routing file)中的主要入口。這個入口負責根據「範疇」(scope)中的 type 值,將請求分派給不同的其他 ASGI 應用。因此,協議會定義範疇內固定的 type 值,讓你可以利用這樣的資訊來辨別進來連線的類型。
ProtocolTypeRouter 接收一個字典,鍵是 scope 的 type,值是負責該類連線的 ASGI 應用程式,例如將 HTTP 交給 Django ASGI application、WebSocket 交給 URLRouter。這個分派發生在 scope 層級,不會把同一條連線的不同事件重新路由到多個 Consumer。
ProtocolTypeRouter({
"http": some_app,
"websocket": some_other_app,
})
此外,如果你希望在 HTTP 處理上區分長輪詢(long-poll)處理器與 Django 傳統的視圖,你可以在使用 URLRouter 路由時,把 Django 的 `get_asgi_application()` 指定為最後一個進入點,並使用一個「匹配所有」的模式(pattern)。這樣的設定會確保 Django 在其他特定 ASGI 處理應用都沒有匹配上請求時,作為最後的處理者來處理剩下的 HTTP 請求。
這種分層安排可以讓不同協定的處理方式在根入口中並列,同時保留各自的路徑與中介軟體;新增處理者時,仍需確認實際協定伺服器能產生該類 scope。
C. URLRouter
channels.routing.URLRouter
在 Django Channels 中,路由配置負責通過 HTTP 路徑來管理 HTTP 或 WebSocket 類型的連接。這個路由配置需要一個參數,即 Django URL 對象的列表,這些對象可以是 `path()` 或 `re_path()` 函數的結果。
URLRouter([
re_path(r"^longpoll/$", LongPollConsumer.as_asgi()),
re_path(r"^notifications/(?P<stream>\w+)/$", LongPollConsumer.as_asgi()),
re_path(r"", get_asgi_application()),
])
任何捕獲到的群組將以字典的形式在 scope 中提供,這個字典的鍵為 url_route,包含兩個鍵:kwargs 和 args。kwargs 鍵對應一個字典,該字典包含所有命名的正則表達式群組,而 args 鍵對應一個列表,包含位置正則表達式群組。
stream = self.scope["url_route"]["kwargs"]["stream"]
注意,命名和未命名的群組不能混用:一旦匹配到一個命名群組,位置群組將被拋棄。
from django.urls import re_path
from myapp import consumers
# 使用命名群組的路由定義
websocket_urlpatterns_named = [
re_path(r'ws/chat/(?P<room_name>\w+)/$', consumers.ChatConsumer.as_asgi()),
]
# 使用位置群組的路由定義
websocket_urlpatterns_positional = [
re_path(r'ws/chat/(\w+)/$', consumers.ChatConsumer.as_asgi()),
]
在這個範例中,我們有兩個路由定義:
命名群組路由使用 (?P<room_name>\w+),匹配值會放在 scope["url_route"]["kwargs"]["room_name"],讓 Consumer 依名稱取得參數。
位置群組路由使用 (\w+),匹配值會依順序放入 scope["url_route"]["args"]。同一個路由若出現命名群組,未命名的位置群組就不會一起保留。
若你嘗試在同一個路由中混用命名和位置群組,例如:
re_path(r'ws/chat/(?P<room_name>\w+)/(\d+)/$', consumers.ChatConsumer.as_asgi())
在這個例子中,`(?P<room_name>\w+)` 是命名群組,而 `(\d+)` 是未命名的(位置)群組。根據 Django Channels 的行為,一旦匹配到命名群組,所有位置群組將被丟棄,也就是說 `(\d+)` 的匹配結果不會被儲存,因此這種混用方式會導致資料無法被正確捕獲。這就是為何建議不要混用兩者的原因。
注意,如果 URLRouter 的內層路由器被額外的中介軟體包裹,那麼 path() 路徑形式的路由嵌套將無法正常運作。
當中介軟體需要包裹內層 URLRouter 時,可以使用 AuthMiddlewareStack 為 WebSocket scope 提供驗證資訊。下例以 re_path 定義巢狀路徑,避免中介軟體包裹內層路由時,path 的巢狀匹配限制。
from django.urls import re_path
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.auth import AuthMiddlewareStack
from myapp import consumers
# 定義頂層的路由
application = ProtocolTypeRouter({
# WebSocket 路徑由外層與內層 URLRouter 依序匹配
"websocket": URLRouter([
re_path(r"^ws/", AuthMiddlewareStack( # 中介軟體包裹內層 URLRouter
URLRouter([
re_path(r"^chat/$", consumers.ChatConsumer.as_asgi()),
])
)),
]),
})
這裡的 AuthMiddlewareStack 包裹內層 URLRouter。Channels 文件指出,內層路由器被額外中介軟體包裹時,使用 path 的巢狀路由有已知限制,因此範例採用 re_path;實際專案也可以減少巢狀層數,讓路由與中介軟體的作用範圍更明確。
解決方法之一是避免這種嵌套的結構,或者在特定需要的情況下使用正則表達式(`re_path()`)來處理更複雜的匹配。
總結來說,當內層路由器包被額外的中介軟體包裹時,確保將可能存在的問題考慮在內,並根據需求選擇適當的路徑匹配方式。
D. ChannelNameRouter
channels.routing.ChannelNameRouter
ChannelNameRouter 根據 channel 類型 scope 裡的 channel 值分派工作,接收一個把固定頻道名稱對應到 ASGI 應用程式的字典。它主要用於 worker 與背景任務,和依 HTTP/WebSocket 路徑分派的 URLRouter 用途不同。
ChannelNameRouter({
"thumbnails-generate": some_app,
"thumbnails-delete": some_other_app,
})
E. 總結
路由的責任是在 scope 建立時選擇處理該連線的應用程式:ProtocolTypeRouter 依協定 type 分派,URLRouter 依路徑匹配並提供捕獲參數,ChannelNameRouter 則依固定 channel 名稱分派背景工作。組合路由時還要考慮中介軟體的層級,以及命名、位置參數和巢狀匹配的限制。
