在Django项目里处理涉及多张表写入的业务逻辑时，最让人头疼的就是部分成功部分失败留下的半成品数据。transaction.atomic装饰器是框架给出的标准解法，它把被装饰函数体内的数据库操作收敛成一个原子单元，要么全部生效，要么全部撤销。
一、transaction.atomic的基本用法
Django的django.db.transaction模块提供了atomic方法，既可以作为装饰器也可以作为上下文管理器。当它装饰一个函数时，进入函数会开启一个数据库事务，函数正常返回则提交，抛出未捕获异常则回滚。这种方式比早期手动调用commit和rollback直观得多，也避免了连接状态遗漏的问题。
下面示例展示用装饰器保护一个转账操作，保证扣款与入账同时成功或同时失败：
from django.db import transaction
from myapp.models import Account
@transaction.atomic
def transfer(from_id, to_id, amount):
# 取出转出账户并扣减余额
src = Account.objects.select_for_update().get(pk=from_id)
if src.balance < amount:
raise ValueError('余额不足')
src.balance -= amount
src.save()
# 取出转入账户并增加余额
dst = Account.objects.select_for_update().get(pk=to_id)
dst.balance += amount
dst.save()
return True
上例中select_for_update会在事务内对行加锁，防止并发请求同时修改同一账户。如果第二步save抛错，第一步的扣减也会随整体回滚，不会出现钱扣了没到账的情况。
二、底层原理与保存点机制
transaction.atomic并不是Django自己实现了一套原子协议，而是向数据库发送标准的事务指令。外层atomic对应数据库的BEGIN与COMMIT或ROLLBACK，而在已存在事务中再嵌套atomic时，Django会创建一个保存点（savepoint），内层异常只回滚到该保存点而非整个事务。
可以通过代码观察嵌套行为：
from django.db import transaction
@transaction.atomic
def outer():
create_log('outer start')
try:
with transaction.atomic():
create_log('inner do')
raise RuntimeError('inner fail')
except RuntimeError:
# 内层回滚，外层继续
pass
create_log('outer end')
这种基于保存点的设计让开发者可以在大事务里局部容忍某些子步骤失败，而不必让整个请求作废。需要注意的是，保存点依然运行在同一个数据库连接和事务生命周期内，过深的嵌套会增加数据库管理开销。
三、在视图与请求中的自动事务
除了显式使用atomic，Django在ATOMIC_REQUESTS配置为True时，会给每个请求函数自动包裹一层atomic。这意味着视图里任何未处理异常都会导致本次请求的所有写操作回滚，对一致性很友好，但也可能因长事务持有锁而过慢。
更灵活的做法是在视图内部只对核心段落加atomic，非关键查询放在外面：
from django.db import transaction
from django.http import JsonResponse
def order_view(request):
# 外部查询不占事务
product = get_product(request.POST['pid'])
with transaction.atomic():
decrease_stock(product)
create_order(product, request.user)
return JsonResponse({'ok': True})
把只读查询移出原子块，能缩短锁持有时间，提升并发能力。同时要注意，原子块内尽量不要调用会触发外部HTTP请求或耗时的任务，否则数据库连接被长期占用，容易拖垮连接池。
四、常见误区与避坑建议
一个典型误区是在atomic内部捕获了所有异常却不重新抛出，导致错误被静默吞掉，事务正常提交，数据实际处于错误状态。另一个误区是在原子块里使用transaction.autocommit相关旧式写法，和atomic混用会造成连接状态混乱。
推荐做法是将原子粒度控制在最小必要范围，并在块外处理业务校验。如下方代码先校验再进事务：
from django.db import transaction
def reward_user(uid, score):
user = User.objects.get(pk=uid)
if user.banned:
return False
with transaction.atomic():
user.point += score
user.save()
PointLog.objects.create(uid=uid, delta=score)
return True
这样既能保证积分与日志一致，又避免了在事务里做不必要的查询判断。掌握这些细节后，transaction.atomic就能成为你维护Django数据一致性的可靠工具。
Djangotransaction_atomic数据一致性修改时间：2026-08-06 18:06:35