裝飾器¶

下列裝飾器可用於同步和非同步視圖函式

• cache_control()

• never_cache()

• no_append_slash()

• csrf_exempt()

• csrf_protect()

• ensure_csrf_cookie()

• requires_csrf_token()

• sensitive_variables()

• sensitive_post_parameters()

• gzip_page()

• condition()

• conditional_page()

• etag()

• last_modified()

• require_http_methods()

• require_GET()

• require_POST()

• require_safe()

• vary_on_cookie()

• vary_on_headers()

• xframe_options_deny()

• xframe_options_sameorigin()

• xframe_options_exempt()

例如

from django.views.decorators.cache import never_cache


@never_cache
def my_sync_view(request): ...


@never_cache
async def my_async_view(request): ...

查詢與 ORM¶

除了一些例外情況外，Django 也可以非同步執行 ORM 查詢

async for author in Author.objects.filter(name__startswith="A"):
    book = await author.books.afirst()

詳細說明可以在 非同步查詢 中找到，但簡而言之

• 所有會導致發生 SQL 查詢的 QuerySet 方法都有一個以 a 為前綴的非同步變體。

• 所有 QuerySet（包括 values() 和 values_list() 的輸出）都支援 async for。

Django 也支援一些使用資料庫的非同步模型方法

async def make_book(*args, **kwargs):
    book = Book(...)
    await book.asave(using="secondary")


async def make_book_with_tags(tags, *args, **kwargs):
    book = await Book.objects.acreate(...)
    await book.tags.aset(tags)

交易尚未在非同步模式下運作。如果您有一段程式碼需要交易行為，我們建議您將該段程式碼寫成單一同步函式，並使用 sync_to_async() 呼叫它。

效能¶

當在與視圖不符的模式下執行時（例如，在 WSGI 下的非同步視圖，或在 ASGI 下的傳統同步視圖），Django 必須模擬其他呼叫樣式以允許您的程式碼執行。這種內容切換會導致大約一毫秒的效能損失。

中介軟體也是如此。Django 將嘗試最小化同步和非同步之間的內容切換次數。如果您有一個 ASGI 伺服器，但您的所有中介軟體和視圖都是同步的，則它只會在進入中介軟體堆疊之前切換一次。

但是，如果您在 ASGI 伺服器和非同步視圖之間放置同步中介軟體，則它必須為中介軟體切換到同步模式，然後再為視圖切換回非同步模式。Django 也會保持同步執行緒開啟，以進行中介軟體例外狀況傳播。這可能一開始不會注意到，但是為每個請求新增這個執行緒損失可能會消除任何非同步效能優勢。

您應該進行自己的效能測試，以了解 ASGI 相對於 WSGI 對您的程式碼有何影響。在某些情況下，即使在 ASGI 下的純同步程式碼庫中，也可能會出現效能提升，因為請求處理程式碼仍然全部非同步執行。一般來說，只有在您的專案中有非同步程式碼時，才會想要啟用 ASGI 模式。

處理斷線¶

對於長時間執行的請求，用戶端可能會在視圖傳回回應之前斷線。在這種情況下，視圖中將引發 asyncio.CancelledError。您可以捕獲此錯誤並在需要執行任何清理時處理它

async def my_view(request):
    try:
        # Do some work
        ...
    except asyncio.CancelledError:
        # Handle disconnect
        raise

您也可以 在串流回應中處理用戶端斷線。

async_to_sync()¶

async_to_sync(async_function, force_new_loop=False)¶

接收一個非同步函式，並返回一個包裹它的同步函式。可以用作直接包裝器或裝飾器。

from asgiref.sync import async_to_sync


async def get_data(): ...


sync_get_data = async_to_sync(get_data)


@async_to_sync
async def get_other_data(): ...

如果當前執行緒存在事件迴圈，則非同步函式會在該事件迴圈中執行。如果沒有當前事件迴圈，則會專門為單個非同步調用啟動一個新的事件迴圈，並在完成後再次關閉。在任何情況下，非同步函式都將在與呼叫程式碼不同的執行緒上執行。

Threadlocals 和 contextvars 值在兩個方向上都會跨邊界保留。

async_to_sync() 本質上是 Python 標準函式庫中 asyncio.run() 函式的更強大版本。除了確保 threadlocals 正常工作外，當在它之下使用包裝器時，它還啟用了 sync_to_async() 的 thread_sensitive 模式。

sync_to_async()¶

sync_to_async(sync_function, thread_sensitive=True)¶

接收一個同步函式，並返回一個包裹它的非同步函式。可以用作直接包裝器或裝飾器。

from asgiref.sync import sync_to_async

async_function = sync_to_async(sync_function, thread_sensitive=False)
async_function = sync_to_async(sensitive_sync_function, thread_sensitive=True)


@sync_to_async
def sync_function(): ...

Threadlocals 和 contextvars 值在兩個方向上都會跨邊界保留。

同步函式在編寫時通常會假設它們都在主執行緒中執行，因此 sync_to_async() 有兩種執行緒模式。

• thread_sensitive=True (預設)：同步函式將在與所有其他 thread_sensitive 函式相同的執行緒中執行。如果主執行緒是同步的，並且您正在使用 async_to_sync() 包裝器，則這將是主執行緒。

• thread_sensitive=False：同步函式將在一個全新的執行緒中執行，該執行緒在調用完成後關閉。

執行緒敏感模式非常特殊，並且需要執行大量工作才能在同一執行緒中執行所有函式。但是請注意，它依賴於堆疊上方使用 async_to_sync()，才能在主執行緒上正確執行操作。如果您使用 asyncio.run() 或類似的東西，它將會退回在單個共享執行緒中執行執行緒敏感函式，但這將不是主執行緒。

在 Django 中需要這樣做的原因是，許多函式庫（特別是資料庫轉接器）要求它們在其建立所在的同一執行緒中被存取。此外，許多現有的 Django 程式碼都假設它們都在同一執行緒中執行，例如，中間件會將內容添加到請求中，以供稍後在視圖中使用。

我們沒有引入此程式碼的潛在相容性問題，而是選擇添加此模式，以便所有現有的 Django 同步程式碼都在同一執行緒中執行，從而與非同步模式完全相容。請注意，同步程式碼始終會在與呼叫它的任何非同步程式碼不同的執行緒中執行，因此您應避免傳遞原始資料庫句柄或其他執行緒敏感的參考。

在實踐中，這種限制意味著您在呼叫 sync_to_async() 時，不應傳遞資料庫 connection 物件的功能。這樣做會觸發執行緒安全性檢查。

# DJANGO_SETTINGS_MODULE=settings.py python -m asyncio
>>> import asyncio
>>> from asgiref.sync import sync_to_async
>>> from django.db import connection
>>> # In an async context so you cannot use the database directly:
>>> connection.cursor()
django.core.exceptions.SynchronousOnlyOperation: You cannot call this from
an async context - use a thread or sync_to_async.
>>> # Nor can you pass resolved connection attributes across threads:
>>> await sync_to_async(connection.cursor)()
django.db.utils.DatabaseError: DatabaseWrapper objects created in a thread
can only be used in that same thread. The object with alias 'default' was
created in thread id 4371465600 and this is thread id 6131478528.

相反，您應該將所有資料庫存取封裝在一個輔助函式中，該函式可以使用 sync_to_async() 呼叫，而無需依賴呼叫程式碼中的連線物件。