异步支持¶

装饰器¶

以下装饰器可同时用于同步和异步视图函数

• cache_control()

• never_cache()

• no_append_slash()

• csp_override()

• csp_report_only_override()

• 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() 调用它。

通过 CONN_MAX_AGE 设置的 持久数据库连接 也应在异步模式下禁用。如果可用，请改用数据库后端内置的连接池，或者根据需要调查第三方连接池选项。

性能¶

当运行模式与视图不匹配时（例如 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() 调用，而无需依赖调用代码中的连接对象。