异步支持

装饰器

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

• 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): ...

method_decorator() 可以用于异步方法，包括用 async def 定义的视图处理方法。不过，如果 View 的处理方法为异步，并且装饰的是 dispatch()，那么还需要重写 dispatch，把它也定义成 async def：

class MyClass(View):
    @method_decorator(never_cache)
    async def dispatch(self, *args, **kwargs):
        return super().dispatch(*args, **kwargs)

    async def get(self, request): ...

    async def post(self, request): ...

这里装饰的是 dispatch，而不是各个处理方法，因此需要让 dispatch 也成为异步方法，以便 method_decorator 正确地将结果标记为协程函数。

查询与 ORM

With some exceptions, Django can run ORM queries asynchronously:

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

详细的说明可以在 异步查询 中找到，简而言之：

• 所有引发 SQL 查询的 QuerySet 方法都有一个以 a 为前缀的异步变体。

• async for 在所有的查询集上都得到支持（包括 values() 和 values_list() 的输出结果）。

使用数据库的异步模型方法同样受支持：

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 设置的持久数据库连接。如果数据库后端提供内置连接池，建议改用连接池；必要时也可以研究第三方连接池方案。与同步 Django 一样，同一进程中的并发请求共享这个池，因此应根据目标在途查询并发量确定连接池大小。

性能

当运行模式与视图不匹配时，例如在 WSGI 下运行异步视图，或在 ASGI 下运行传统同步视图，Django 必须模拟另一种调用方式才能执行代码。单次适配的开销较小：在能够复用运行中事件循环的 ASGI 请求路径中，约为数十微秒；在管理命令、后台任务及脚本使用的冷启动路径中，约为数百微秒。相对于通常以毫秒计的请求耗时，这一开销本身很少明显可见；但随着活动线程增加，在 GIL 竞争下可能变得明显。

如果在紧密循环中为每一行或每次操作单独进行适配，请重构代码，让整个循环在一次 sync_to_async() 或 async_to_sync() 跨越中执行。这样，上下文切换的单次成本会分摊到整个循环，基本不再明显。

中间件也有相同的单次适配开销。Django 会尽量减少同步与异步之间的上下文切换。如果使用 ASGI 服务器，但所有中间件和视图都是同步的，那么只会在进入中间件处理链之前切换一次。

但是，如果在 ASGI 服务器和异步视图之间放置同步中间件，Django 就需要先切换到同步模式执行中间件，再切回异步模式执行视图，同时还要保留同步线程，以便传播中间件异常。对于访问 ORM 后立即返回的请求／响应视图，这通常不会产生明显影响。如果使用 ASGI 在单进程中为非 ORM 的 I/O 提供高并发，例如并行向上游发送 HTTP 请求、服务器发送事件或其他长期请求，这种开销就更重要，因为每个请求额外占用的线程会限制并发量。

你应该执行性能测试来观察 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() 的增强版本。除了保证线程局部变量正常工作外，当 sync_to_async() 包装器在其下层使用时，它还会启用该包装器的 thread_sensitive 模式。在没有运行中事件循环的冷路径中，它与 asyncio.run() 一样需要承担启动新事件循环的成本；已有事件循环运行时，例如 ASGI 请求内部，则会复用现有循环，开销相应降低。

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：同步函数将在一个全新的线程中运行，该线程一旦完成，将会关闭。

Thread-sensitive(线程敏感)模式非常特殊，在同一个线程中运行所有函数需要做很多工作。但是请注意，它依赖于堆栈中它上面的 async_to_sync() 的使用，以便在主线程上正确运行。如果你使用 asyncio.run() 或类似，它将退回到单独共享线程（但不是主线程）中运行 thread-sensitive 函数。

在 Django 中需要这么做的原因是许多库，特别是数据库适配器，要求它们在创建时所在的同一个线程里对其进行访问。许多现有的 Django 代码也假设它都在同一进程中运行（比如中间件将内容添加到请求中以供稍后在视图中使用）。

我们没有引入代码潜在的兼容性问题，而是选择了添加这种模式，以便所有现有的 Django 同步代码都在同一个线程中运行，从而完全兼容异步模式。注意，同步代码始终要与调用它的异步代码保持在不同线程中，所以你应该避免传递原始数据库句柄(handles)或者其他 thread-sensitive 引用。

在同一个请求内部，多次 thread_sensitive 调用会在该请求的工作线程上串行执行。但每个请求都有自己按上下文分配的工作线程，因此并发请求之间不会彼此串行化。这与 Django 的每线程连接模型一致；其他异步数据库库也有相同约束，即同一连接上的并发查询会通过锁串行执行。要支持更多并发请求，应相应增大连接池，而不是禁用 thread_sensitive。

在实际应用中，这意味着在调用 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() 调用，而不依赖于调用代码中的连接对象。