django 5.0异步orm仅支持aget()、afilter()等带a前缀方法，须配asyncpg驱动及asgi部署，混用同步方法或驱动将静默降级为同步执行。
async def 视图里直接 await QuerySet
Django 5.0 的 ORM 原生支持异步查询，但仅限于 QuerySet 的 aget()、afirst()、alast()、acount()、aexists() 和 aiterator() 这些方法。你不能对普通 QuerySet 对象直接 await，也不能在 async def 视图里混用同步的 .filter().all()。
常见错误是写成这样：await MyModel.objects.filter(name="x") —— 这会抛出 TypeError: object QuerySet can't be used in 'await' expression。
- 必须用
await MyModel.objects.filter(name="x").afirst()或await MyModel.objects.filter(name="x").acount() -
.all()没有对应的aall()，要用.aiterator()配合async for - 聚合函数如
Sum不支持异步，await MyModel.objects.aaggregate(...)不存在，只能先await .values_list(...).aiterator()后在 Python 层计算
数据库连接必须启用 async_mode
Django 默认用的是同步数据库后端，即使你在视图里写了 await，底层仍会阻塞线程。必须在 settings.py 的 DATABASES 配置中显式启用异步支持：
DATABASES = {
"default": {
"ENGINE": "django.db.backends.postgresql",
"NAME": "mydb",
"USER": "user",
"PASSWORD": "pass",
"HOST": "localhost",
"PORT": "5432",
"OPTIONS": {
"connection_factory": "django.db.backends.postgresql.async_connection.AsyncConnection",
},
}
}
注意：MySQL 和 SQLite 的异步支持在 Django 5.0 中**不完整或不可用**；PostgreSQL 是目前唯一被官方稳定支持的异步后端。
- 忘记加
"connection_factory"会导致所有await查询退化为同步执行，且无任何警告 - 使用
psycopg3.x 是强制要求（psycopg[binary]>=3.1），psycopg2不支持 - 若用 Gunicorn + Uvicorn 组合部署，确保启动的是
uvicorn（不是gunicorn的 sync worker）
不要在 async 视图里调用同步 ORM 方法或第三方库
哪怕只有一行 MyModel.objects.get(id=1) 或 datetime.now()（看似无害），都会让整个协程被阻塞。Django 不会自动将同步调用“升格”为异步。
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
典型陷阱包括：
- 在
async def视图里调用自定义的同步 model method（比如instance.calculate_score()） - 混用
requests.get()（同步 HTTP 客户端）—— 必须换成httpx.AsyncClient或aiohttp - 对
QuerySet执行切片（如qs[0:10]）或list(qs)，这些操作无法异步化，会触发同步求值 - 使用
select_related()或prefetch_related()的异步版本尚未实现（Django 5.0 中仍无aselect_related），关联查询需拆解为多个await调用
性能瓶颈往往不在 ORM 层，而在连接池和并发模型
异步 ORM 并不等于自动高性能。如果你的 PostgreSQL 连接数配置过小（比如 MAX_CONNS=5），而并发请求达到 50，大量协程会在连接获取阶段排队等待，实际吞吐反而不如同步模型。
关键配置点：
- PostgreSQL 的
max_connections和 Django 的CONN_MAX_AGE要协同调优；设为0表示每次请求新建连接，适合短时高并发；设为非零值需配合连接池（如pgbouncer） -
aiterator(chunk_size=2000)比默认 chunk 小更省内存，但 chunk 太大会导致单次 await 延迟升高 - 异步视图中嵌套多层
await（如查用户 → 查其订单 → 查每个订单商品）容易引发 N+1，应提前用await Order.objects.filter(user_id__in=user_ids).aiterator()批量拉取
真正决定异步收益的，常常是数据库连接管理、网络 I/O 分布，而不是 ORM 方法本身是否带 a 前缀。漏掉连接池或错配 psycopg 版本，会让所有异步代码跑在假异步上。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
