A. 簡介
ASGI 定義伺服器與應用程式之間的事件介面,Channels 則在這個介面之上提供 Consumer,讓應用程式以具名方法處理連線與訊息事件,不必在每個功能中自行撰寫完整的事件分派流程。
Consumers 特別做到以下幾件事:
1. 結構化代碼:將您的代碼組織成一系列函數,以便在事件發生時被調用,而不是讓您自己編寫事件迴圈。這使得代碼的組織和維護更加清晰和易於管理。
Consumer 提供同步與非同步兩種執行方式,協助安排執行緒與事件處理。選擇時仍需檢查所呼叫的函式庫是否支援非同步,以及同步工作可能占用的執行緒與資源,而不是把這些執行細節完全交給框架就不再處理。
Consumer 是 Channels 提供的抽象,並不是使用 ASGI 的必要條件。也可以將 Channels 的路由、session 與驗證中介軟體,搭配其他 ASGI 應用程式使用;如果功能主要由連線事件驅動,Consumer 通常是較容易組織程式的方式。
這些元件讓既有 Django 專案可以逐步加入 WebSocket 或其他長連線處理,同時保留原有的 HTTP view 與同步程式碼。
B. Basic Layout
Consumer 的兩個基底類別是 AsyncConsumer 與 SyncConsumer:前者以協程執行事件處理方法,後者在線程池內執行同步方法。選擇依據是所需的 I/O 介面與阻塞行為,不是任務長短或是否使用 WebSocket;同步 ORM 常適合 SyncConsumer,非同步原生 I/O 則可使用 AsyncConsumer。
以下是一個SyncConsumer的範例:
from channels.consumer import SyncConsumer
class EchoConsumer(SyncConsumer):
def websocket_connect(self, event):
self.send({
"type": "websocket.accept",
})
def websocket_receive(self, event):
self.send({
"type": "websocket.send",
"text": event["text"],
})
這是一個非常簡單的 WebSocket 回聲服務器 —— 它會接受所有傳入的 WebSocket 連結,並回覆所有傳入的 WebSocket 訊息文本框架,回覆的內容與接收到的相同。
消費者(Consumers)是基於一系列命名方法結構而成,這些方法對應他們將接收到的訊息類型值,其中任何”.”將被替換為”_”. 以上提到的兩個處理器分別處理 `websocket.connect` 和 `websocket.receive` 訊息。
我們是如何知道將會收到哪些事件類型以及事件中包含什麼(如 `websocket.receive` 包含一個 `text` 鍵)的呢?這是因為我們依據 ASGI WebSocket 規範來設計,它告訴我們 WebSockets 是如何展現的。
除此之外,唯一其他的基本 API 是 `self.send(event)`。這讓你可以依照協議將事件發送回客戶端或協議服務器——如果你查看 WebSocket 協議,就會發現我們發送的字典就是向客戶端發送文本框架的方式。
`AsyncConsumer` 的結構非常相似,但所有的處理方法必須是協程,而 `self.send` 也是一個協程:
from channels.consumer import AsyncConsumer
class EchoConsumer(AsyncConsumer):
async def websocket_connect(self, event):
await self.send({
"type": "websocket.accept",
})
async def websocket_receive(self, event):
await self.send({
"type": "websocket.send",
"text": event["text"],
})
1. 如何選擇使用AsyncConsumer或SyncConsumer
選擇 Consumer 類型時,先確認處理流程會呼叫哪些同步或非同步函式庫,以及是否有可並行等待的 I/O。WebSocket 與長輪詢都能採不同寫法,協定本身不會替你決定哪一種 Consumer 比較合適。
1-1. 使用AsyncConsumer
`AsyncConsumer` 是專為與異步代碼進行交互而設計的。當你的應用需要支援高併發和非阻塞 I/O 操作時,`AsyncConsumer` 是理想的選擇。這在使用 WebSockets 或需要同時處理多個網頁請求(例如使用 HTTPX 擷取多個頁面的資料)時特別有用。通過利用 Python 的 `asyncio` 模塊,`AsyncConsumer` 提升了效率和延展性。然而,要注意的是,如果在 `AsyncConsumer` 中調用耗時的同步函數,這可能會導致整個事件循環(event loop)被阻塞或延遲。因此,只有在確保操作以異步方式進行且使用異步原生庫時,才選擇 `AsyncConsumer`。
如果你在 `AsyncConsumer` 中確實需要調用同步函數,一個解決方案是使用 `asgiref.sync.sync_to_async` 工具。這個工具能將同步可調用物件轉換為異步協程,使得可以在異步環境下調用同步代碼而不阻塞事件循環。這對於擴展應用程序的處理能力非常重要,特別是在處理 WebSockets 和其他需要持久連接的協議時。
1-2. 使用SyncConsumer
相反地,當應用需要調用傳統的同步操作,如 Django ORM 或其他同步代碼,應考慮使用 `SyncConsumer`。`SyncConsumer` 在獨立執行緒中運行,這讓它能夠有效地避免同步操作(如 ORM 查詢)造成的阻塞影響。在預設情況下,尤其是大多數處理過程中,選擇 `SyncConsumer` 可確保系統的穩定性和效率。這是因為大部分同步代碼需要簡單地運行在其設計的線程內而不是事件循環中,特別是當你的應用並未經常需要可平行處理的長時間運行任務時。
因此,需要使用同步函式庫時,可以先採 SyncConsumer;當主要工作使用非同步介面、且確實能從並行等待受益時,再選擇 AsyncConsumer。從非同步程式呼叫同步 ORM,應使用 database_sync_to_async 或已提供的非同步 ORM 方法,而不是直接阻塞事件迴圈。
2. 關閉Consumers
當附加到您的消費者(consumer)的套接字或連接關閉時——無論是由您或是客戶端關閉——您很可能會收到一個事件通知(例如,`http.disconnect`或`websocket.disconnect`),並且您的應用實例會在短時間內執行相應操作。
完成斷開連接後的清理工作後,您需要引發`channels.exceptions.StopConsumer`例外,以清楚地停止ASGI應用並讓伺服器進行清理。如果您不引發此例外並讓系統持續執行的話,伺服器會在超出應用關閉超時時間後(Daphne預設為10秒)強制終止您的應用並發出警告。
下文將介紹通用消費者如何為您自動完成這項工作,因此這部分只有在您基於`AsyncConsumer`或`SyncConsumer`編寫自己的消費者類時才需要關注。然而,如果您重寫了它們的`__call__`方法,或阻止其調用的方法返回,您可能仍然會遇到此問題;如果您想獲取更多信息,可以查看其源代碼。
另外,如果您啟動了自己的背景協程,確保在連接結束時也將它們關閉,否則這些協程會滲漏到伺服器中。這樣會造成不必要的資源消耗與管理負擔。
連線清理需要和 Consumer 類型一起考慮:基底 Consumer 要自行結束事件處理,通用 Consumer 則已提供相關流程;另外啟動的背景協程與資源,也應在連線結束時安排清理。
3. Channel Layers
在 Django Channels 中,消費者(Consumers)是處理異步通信的核心組件之一。它們除了負責管理 WebSocket 連接或其他協議的邏輯外,還可以與 Channel 層進行交互,以支持消息的傳遞。
Channel 層允許不同的消費者之間進行點對點(one-to-one)的消息傳遞,或者通過群組(groups)這種廣播系統來分發消息。這意味著你可以設計你的應用,使之能夠將信息發送給特定的消費者,或者廣播給訂閱了某個群組的所有消費者。例如,在一個多人聊天室應用中,當某位用戶發送消息時,這條消息可以被廣播給該聊天室中的所有用戶。
預設情況下,消費者將使用默認的 channel layer,這是在設置中配置的。但如果在子類化(subclassing)任意提供的 Consumer 類時設置了 `channel_layer_alias` 屬性,你可以改變這個行為。`channel_layer_alias` 屬性允許你指定要使用的不同的 channel layer,這對於多環境設置或需要使用不同通訊策略的特殊情境中特別有用。
這種設計使 Django Channels 成為一個強大且靈活的工具,可以輕鬆實現複雜的實時通信功能。需要注意的是,設置和操作 Channel 層需要考慮並發與延遲等因素,以確保應用的性能和可靠性。
C. Scope
在 Django Channels 中,消費者(Consumers)在被調用時會接收到一個「作用域」(scope),這個作用域包含許多你在 Django 視圖中的 request 對象上可以找到的信息。在消費者的方法中,你可以透過 `self.scope` 來訪問這些信息。
作用域是 ASGI 規範的一部分,但以下是一些你可能會常用的項目:
1. `scope[“path”]`:這表示請求的路徑(用於 HTTP 和 WebSocket)。
2. `scope[“headers”]`:包含請求的原始名稱/值標頭對(用於 HTTP 和 WebSocket)。
3. `scope[“method”]`:表示請求所使用的方法名稱(僅適用於 HTTP)。
如果你啟用了像身份驗證這類功能,也能透過 `scope[“user”]` 來訪問 user 對象。例如,URLRouter 會將來自 URL 的捕獲群組放入 `scope[“url_route”]`。
總體來說,作用域是獲取連接信息的地方,並且中間件會將其想讓你訪問的屬性放在這裡(就像 Django 的中間件會新增一些屬性到 request 上一樣)。
D. Generic Consumers
以上所看到的是一個適用於任何協議的消費者(Consumer)的基本佈局。就像 Django 的generic view一樣,Channels 提供了通用消費者,它們將常見的功能封裝起來,讓你不需要重寫它,特別是針對 HTTP 和 WebSocket 處理。
1. WebsocketConsumer
channels.generic.websocket.WebsocketConsumer 包裝 WebSocket 的 ASGI 事件,讓 connect、receive 與 disconnect 處理文字或二進位資料。下面是 API 用法展示,accept、選擇子協定、close 及強制關閉是不同處理分支的選項,不應把同一方法內展示的每個選項當成實際流程依序執行。
from channels.generic.websocket import WebsocketConsumer
class MyConsumer(WebsocketConsumer):
groups = ["broadcast"]
def connect(self):
# Called on connection.
# To accept the connection call:
self.accept()
# Or accept the connection and specify a chosen subprotocol.
# A list of subprotocols specified by the connecting client
# will be available in self.scope['subprotocols']
self.accept("subprotocol")
# To reject the connection, call:
self.close()
def receive(self, text_data=None, bytes_data=None):
# Called with either text_data or bytes_data for each frame
# You can call:
self.send(text_data="Hello world!")
# Or, to send a binary frame:
self.send(bytes_data=b"Hello world!")
# Want to force-close the connection? Call:
self.close()
# Or add a custom WebSocket error code!
self.close(code=4123)
def disconnect(self, close_code):
# Called when the socket closes
pass
您還可以在 `connect` 方法內的任何地方拋出 `channels.exceptions.AcceptConnection` 或 `channels.exceptions.DenyConnection`,以接受或拒絕連接,這樣您就可以使用不需要混入類(mixins)即可重複使用的身份驗證或限速代碼。
一個 `WebsocketConsumer` 的通道會自動在連接時添加到其 `groups` 類屬性中提到的任何群組中,並在斷開連接時從這些群組中移除。`groups` 必須是可迭代的,並且作為通道後端設置的通道層必須支持群組功能(`channels.layers.InMemoryChannelLayer` 和 `channels_redis.core.RedisChannelLayer` 都支持群組)。如果未配置通道層或通道層不支持群組,則連接到具有非空 `groups` 屬性的 `WebsocketConsumer` 將會引發 `channels.exceptions.InvalidChannelLayerError`。
2. AsyncWebsocketConsumer
channels.generic.websocket.AsyncWebsocketConsumer 提供對應的非同步介面,事件方法以 async def 定義,accept、send、close 等操作以 await 呼叫。下面同樣是各 API 選項的展示,實際 connect 或 receive 應依條件選擇其中的分支。
from channels.generic.websocket import AsyncWebsocketConsumer
class MyConsumer(AsyncWebsocketConsumer):
groups = ["broadcast"]
async def connect(self):
# Called on connection.
# To accept the connection call:
await self.accept()
# Or accept the connection and specify a chosen subprotocol.
# A list of subprotocols specified by the connecting client
# will be available in self.scope['subprotocols']
await self.accept("subprotocol")
# To reject the connection, call:
await self.close()
async def receive(self, text_data=None, bytes_data=None):
# Called with either text_data or bytes_data for each frame
# You can call:
await self.send(text_data="Hello world!")
# Or, to send a binary frame:
await self.send(bytes_data=b"Hello world!")
# Want to force-close the connection? Call:
await self.close()
# Or add a custom WebSocket error code!
await self.close(code=4123)
async def disconnect(self, close_code):
# Called when the socket closes
pass
3. JsonWebsocketConsumer
JsonWebsocketConsumer 類別可以作為 channels.generic.websocket.JsonWebsocketConsumer 使用。這個類別的運作方式類似於 WebsocketConsumer,不過它會自動將發送和接收的 WebSocket 文本框架編碼和解碼為 JSON。
唯一的 API 差異有:
1. 你的 `receive_json` 方法必須接受一個參數 `content`,這個參數就是解碼後的 JSON 物件。
2. `self.send_json` 方法僅接受一個參數 `content`,系統會自動為你將此內容編碼為 JSON。
如果您想要自訂 JSON 的編碼和解碼,可以覆寫 `encode_json` 和 `decode_json` 類別方法。
4. AsyncJsonWebsocketConsumer
JsonWebsocketConsumer 的異步版本,可作為 channels.generic.websocket.AsyncJsonWebsocketConsumer 使用。請注意,甚至 encode_json 和 decode_json 也是異步函數。
5. AsyncHttpConsumer
作為 `channels.generic.http.AsyncHttpConsumer` 提供,這提供了用於實現 HTTP 端點的基本原語:
import asyncio
from channels.generic.http import AsyncHttpConsumer
class BasicHttpConsumer(AsyncHttpConsumer):
async def handle(self, body):
await asyncio.sleep(10)
await self.send_response(200, b"Your response bytes", headers=[
(b"Content-Type", b"text/plain"),
])
您需要實作您自己的 `handle` 方法。該方法接收整個請求體作為一個字節串(bytestring)。標頭可以作為元組列表或字典傳遞。回應體的內容預期為一個字節串。
如果您希望在斷開連接時執行一些代碼,您也可以實作一個 `disconnect` 方法。例如,用於關閉您啟動的任何協程。即使是在非正常斷開連接的情況下,這段代碼仍會運行,所以不要期望 handle 能夠乾淨地完成運行。
長輪詢會讓一次 HTTP 請求等待新訊息,收到事件後回傳 JSON 並結束回應;前端取得結果後,再發出下一次請求。下例提供一個 GET 端點,訂閱 chat-room 群組,最長等待 25 秒;逾時時回傳 {"text": null},讓前端可以重新發出請求。
import asyncio
import json
from contextlib import suppress
from channels.exceptions import StopConsumer
from channels.generic.http import AsyncHttpConsumer
class LongPollConsumer(AsyncHttpConsumer):
group_name = "chat-room"
timeout_seconds = 25
async def __call__(self, scope, receive, send):
self.subscribed = False
self.timeout_task = None
try:
await super().__call__(scope, receive, send)
finally:
await self.disconnect()
async def http_request(self, message):
self.body.append(message.get("body", b""))
if not message.get("more_body", False):
await self.handle(b"".join(self.body))
self.body.clear()
async def handle(self, body):
if self.scope["method"] != "GET":
await self.send_response(
405,
b"Method not allowed",
headers=[(b"Allow", b"GET")],
)
raise StopConsumer()
if self.channel_layer is None:
raise RuntimeError("Configure CHANNEL_LAYERS before using long polling")
await self.channel_layer.group_add(self.group_name, self.channel_name)
self.subscribed = True
await self.send_headers(headers=[
(b"Content-Type", b"application/json; charset=utf-8"),
(b"Cache-Control", b"no-store"),
])
await self.send_body(b"", more_body=True)
self.timeout_task = asyncio.create_task(self.send_timeout())
async def send_timeout(self):
await asyncio.sleep(self.timeout_seconds)
await self.channel_layer.send(self.channel_name, {"type": "poll.timeout"})
async def chat_message(self, event):
payload = json.dumps({"text": event["text"]}, ensure_ascii=False)
await self.send_body(payload.encode("utf-8"))
raise StopConsumer()
async def poll_timeout(self, event):
await self.send_body(b'{"text": null}')
raise StopConsumer()
async def disconnect(self):
task, self.timeout_task = self.timeout_task, None
try:
if task is not None:
task.cancel()
with suppress(asyncio.CancelledError):
await task
finally:
if self.subscribed:
self.subscribed = False
await self.channel_layer.group_discard(
self.group_name, self.channel_name
)
AsyncHttpConsumer 預設會在 handle() 返回後結束 Consumer,因此這個端點覆寫 http_request(),在讀完請求後維持事件派送,讓 chat_message() 或 poll_timeout() 完成回應。結束時以 StopConsumer 停止事件處理,並在 disconnect() 取消計時工作、移出群組;無論是正常回應、客戶端中斷或應用程式取消,都走相同的清理流程。
這個範例需要已設定且支援群組的 CHANNEL_LAYERS,可參考Channel Layers 的 Redis 配置。將 path("events/", LongPollConsumer.as_asgi()) 加入 HTTP 的 URLRouter,並保留專案既有的 Django HTTP 路由與 WebSocket 入口。以下群組用來示範公開聊天室;私人訊息應先驗證登入者與訂閱權限,再決定可加入的群組。
先開啟另一個終端機,向執行中的 ASGI 服務發出請求:
curl -N http://127.0.0.1:8000/events/
接著在 Django shell 或同步 view 中送出群組事件,等待中的請求就會取得訊息。從其他程序發送時必須使用 Redis 等共用後端,In-Memory Channel Layer 只能在同一個程序內傳遞訊息:
from asgiref.sync import async_to_sync
from channels.layers import get_channel_layer
channel_layer = get_channel_layer()
async_to_sync(channel_layer.group_send)(
"chat-room",
{"type": "chat.message", "text": "一則新的聊天室訊息"},
)
每次請求只回傳一則訊息,25 秒內沒有新事件時則回傳 text: null。前端可以在收到回應後重新發出請求,代理伺服器的讀取逾時也應大於這個等待時間。群組廣播不會保存歷史,兩次請求之間仍可能錯過事件;需要可靠補送時,應另以資料庫記錄及游標設計訊息讀取流程。
5-1. Server-sent events
Django Channels 可以透過 HTTP 串流實作 Server-Sent Events(SSE),讓伺服器在同一條連線中持續向瀏覽器推送事件。這適合進度或狀態更新,和需要雙向訊息的 WebSocket 用途不同;以下說明基本的實作步驟與範例。
以下是如何實現 SSE HTTP 端點的一些基本步驟和解釋:
a. 設置 Django Channels
確保您已經在專案中設置好 Django Channels。這通常包括在 settings.py 中配置 ASGI 應用及相關配置。
b. 創建消費者 (Consumer)
消費者是處理連接的地方。您可以創建一個 HTTP 消費者來處理 SSE 連接。這個消費者需要能夠保持連接並持續發送數據更新。
c. 編寫 SSE 消費者邏輯
SSE Consumer 使用 send_headers(headers=[...]) 設定回應的 Content-Type 與 Cache-Control,再透過 send_body 傳送以空行結束的事件,並以 more_body=True 保持回應開啟。scope 裡的 headers 是輸入的請求標頭,修改它並不會設定回應;下例每秒傳送固定測試資料,沒有實作資料庫訂閱或完整的斷線復原。
import asyncio
from channels.generic.http import AsyncHttpConsumer
class SSEConsumer(AsyncHttpConsumer):
async def handle(self, body):
await self.send_headers(headers=[
(b'Cache-Control', b'no-cache'),
(b'Content-Type', b'text/event-stream'),
])
while True:
# This loop can push data every so often, simulate it with asyncio.sleep
await self.send_body(b"data: The current time is 1234567890\n\n", more_body=True)
await asyncio.sleep(1)
d. 配置路由
配置 URL 路由以便不同的請求能夠正確地被分派到您的 SSE 消費者。您需要在 Django 的路由中添加相應的配置來處理這些 URL 請求。
e. 客戶端處理
在客戶端,使用 JavaScript 的 `EventSource` API 來接收 SSE 更新。像這樣:
const eventSource = new EventSource('/your-sse-endpoint-url/');
eventSource.onmessage = function(event) {
console.log(event.data);
};
eventSource.onerror = function(event) {
console.error("An error occurred: ", event);
};
SSE 的事件資料流由伺服器傳向客戶端,適合不斷更新狀態的介面;客戶端若要送出資料,仍可另外使用一般 HTTP 請求,並不是整個應用都不能回傳資料。相較之下,WebSocket 在同一連線中提供雙向訊息傳遞,應依互動需求選擇。
部署 SSE 時,除了非同步程式,也要確認反向代理的緩衝及逾時設定,並安排連線中止時的清理;使用 Channels 本身不會自動保證串流即時性或降低資源使用。
E. 總結
本篇依 Channels 官方 Consumer 文件整理並補充範例,涵蓋同步與非同步基底、scope、連線清理,以及 WebSocket、JSON、HTTP 與 SSE 的通用介面。實作時應先區分哪些片段是 API 展示、哪些需要專案路由、通道層或資源清理配合,再選擇對應的 Consumer 類別。
