Django 6.1 异步任务怎么做：Tasks API 与 Celery 的边界

Django 6.0 在 2025 年加入了 Tasks 框架，Django 6.1 的稳定版文档继续提供这套 API。它让项目可以用统一接口定义和入队后台任务，但它本身不启动 worker，也不提供可用于生产的持久队列实现。把 @task 加到函数上，不代表任务已经异步执行。选择之前，先确认 Django 版本、任务后端、worker、队列持久性和失败处理分别由谁负责。

本文以 Django 6.1 官方文档和 Celery 5.6 文档为准，适合正在设计 Django 后台任务，或评估是否从 Celery 迁移的开发者。Django 5.2 项目没有内置的 django.tasks API；Django 文档提到可使用 django-tasks backport，但需要单独核实其维护状态、API 兼容性和后端支持。本文不会假设升级版本就能自动替换现有 worker。

一、先把三个组成部分分开

后台任务系统至少包含三个职责：

1. 任务定义和入队 API：应用如何声明任务、传入参数并请求执行。
2. 队列和结果后端：任务如何存储、如何被 worker 领取，结果和错误保存在哪里。
3. Worker 运行设施：独立进程或服务如何持续消费队列、扩缩容、重启和告警。

Django Tasks 主要统一第一部分，并定义后端扩展接口。具体队列与 worker 能力取决于所选的第三方 backend。Celery 则提供任务分发、worker、重试、路由和周期任务等成熟能力，并与 Django 集成。两者不是简单的“新版替代旧版”关系。

如果当前项目用 Django 5.2 且 Celery 工作正常，单为使用 Tasks API 升级框架并迁移任务，未必会减少系统复杂度。先定义要解决的实际问题，再比较运维和迁移成本。

二、Django Tasks API 的基本写法

Django 6.0 及后续文档中，任务可用 django.tasks.task 装饰器定义，并用 .enqueue() 入队：

from django.tasks import task


@task
def send_order_notice(order_id: int) -> None:
    order = Order.objects.get(pk=order_id)
    send_confirmation_email(order)


result = send_order_notice.enqueue(order_id=42)

enqueue() 返回 TaskResult。它表达本次任务运行的状态和结果，不应与业务订单状态混为一谈。能否在之后通过 ID 查询结果、结果保留多久以及失败信息如何持久化，取决于后端能力和配置。Django 文档指出，诸如 ImmediateBackend 的后端不支持 get_result()。

默认后端不是异步 worker

这是最容易在示例代码中被忽略的点。Django 默认的 ImmediateBackend 会在调用 .enqueue() 时立即运行任务，通常仍在当前进程中；它便于逐步接入 API 或编写测试，不会自动把耗时操作移出 HTTP 请求。DummyBackend 不执行任务，只用于开发和测试。Django 官方文档将内置后端定位为开发、测试用途，生产环境要选择提供实际 worker 和耐久队列的后端。

因此，在没有配置第三方 backend 时，前面的代码只是 API 示例，不能被当成“生产任务已经异步运行”。部署前应明确写下 backend 的 Python 路径、队列服务、worker 启动方式和故障告警，并从后台进程实际消费一条任务来验收。

入队参数要能安全序列化

Django Tasks 会将参数和返回值按 JSON 约束处理。传模型对象、datetime、Decimal、自定义类或依赖元组键语义的数据，可能无法序列化，或在 JSON 往返后改变类型。通常传数据库主键和简单字符串、数字、布尔值、列表、字典更清楚；任务运行时重新读取最新业务数据，并检查记录是否仍然存在、状态是否仍允许执行。

不要把密码、支付凭证、完整个人信息或长期有效 Token 塞进队列参数。消息可能会被 broker 管理员、监控界面或日志访问者看到；敏感数据应按最小必要原则通过受控存储读取，并设置访问权限和保留策略。

三、数据库事务与任务入队的顺序

如果 worker 在数据库事务提交之前就开始工作，它可能读不到刚创建的记录。Django 文档建议在 transaction.on_commit() 中安排入队：

from functools import partial

from django.db import transaction


with transaction.atomic():
    order = Order.objects.create(status="pending")
    transaction.on_commit(
        partial(send_order_notice.enqueue, order_id=order.pk)
    )

这样可以避免任务先于订单提交而运行。可是，数据库提交与向外部 broker 发布不是一个原子事务。如果数据库提交后，进程在回调发消息前崩溃，订单已经存在，而通知任务可能没有入队。对丢失消息有严格要求的业务，需要进一步考虑 transactional outbox：在同一数据库事务中写业务记录和 outbox 事件，再由独立 dispatcher 重试发布。即使如此，重复投递仍应按预期处理；outbox 解决的是事件不会因提交边界而无声丢失，不是“只执行一次”的保证。

如果任务只是允许偶尔丢失的非关键通知，on_commit() 可能足够。若涉及账单、权益、支付后处理或重要数据同步，应先定义消息丢失、重复和人工补偿的业务后果，再选择队列设计。

四、Celery 与 Django Tasks 的职责比较

Celery 通过 Django 集成配置应用，任务常用 shared_task 声明，worker 由单独命令启动。它长期提供 broker 集成、任务确认、重试、路由、周期调度和 worker 管理等生态能力。Celery 文档建议任务尽可能具备幂等性，并说明确认、重投和 worker 丢失等场景会影响重复执行行为。

上表不代表任何方案对所有项目都更快、更可靠。队列耐久性、至少一次投递、确认语义和恢复能力都要以实际 backend 或 broker 的文档和测试为准。

哪些情况适合继续用 Celery

• 已有生产任务、监控和 worker 部署稳定，迁移没有明确的故障或维护收益；
• 依赖成熟的周期任务、任务路由、并发池或复杂重试策略；
• 团队已经有 Celery 运维经验，Django 6 后端尚未覆盖所需能力；
• 后端或任务语义不兼容，迁移会要求同时改业务和运营流程。

哪些情况值得评估 Django Tasks

• 项目已经升级到 Django 6.0 或 6.1；
• 所选第三方 backend 有清晰的 worker、持久化、重试、结果、升级和监控说明；
• 希望应用代码依赖 Django 的任务抽象，而不是直接依赖某个队列库；
• 新功能可以先用一条非关键任务验证入队、执行、错误和部署流程。

不要把“统一 API”误解为“后端可以随时互换”。不同 backend 可能支持不同参数、队列、重试和结果功能。迁移前先列出依赖的行为，建立兼容矩阵，再决定任务是否可以逐个切换。

五、生产任务的可靠性检查

1. 让任务可幂等

worker 崩溃、消息重试、运营人员手动补跑都会造成同一任务执行多次的可能。对发放权益、扣款、同步第三方状态等操作，给业务事件一个稳定唯一标识，并在数据库事务中检查是否处理过。不要只依赖队列消息 ID 防重，因为业务重试可能产生新的消息 ID。

2. 对外部 I/O 设置超时

网络请求、邮件服务、对象存储和第三方 API 都应有连接与读取超时。没有超时的任务会长时间占住 worker；超时后是否重试也要区分临时故障、永久错误和用户数据错误。只对可恢复异常使用有限次数的指数退避或明确的间隔，不要无限重试。

3. 确定任务状态和补偿路径

明确任务何时算成功、失败后能否人工重跑、需要从什么业务状态恢复，以及部分完成时如何补偿。队列状态不等于业务状态，用户界面应呈现真实业务状态，不要把“消息成功投递”显示成“处理完成”。

4. 监控队列积压而不只看进程存活

至少观察 worker 心跳、待处理数量、最老任务等待时间、成功和失败率、重试次数、任务执行时长和 broker 错误。进程存在并不表示任务在前进；若可用后端没有这些指标，需要另外设计巡检或选择有运维观测能力的实现。

5. 控制结果和敏感信息的保留

任务结果、异常文本和参数有可能持久化。约定结果保留期、访问权限、脱敏规则和清理任务。将日志接到统一监控时，不要无意把邮件内容、用户数据或密钥复制到通用日志系统。

六、Django 5.2 项目的升级和迁移顺序

Django 6.0 于 2025-12-03 发布，Tasks 框架从 Django 6.0 开始提供；Django 6.1 于 2026-08-05 发布，当前官方稳定文档为 6.1。升级前仍要核对 Python 版本、第三方包、数据库、部署平台和支持周期。升级到新框架并不会替你提供 worker。

建议按以下次序做评估：

1. 盘点现有任务：列出触发来源、参数、最长执行时间、重试、周期计划、业务副作用和补偿方式。
2. 记录现有 Celery 语义：使用的 broker、acks、路由、重试、结果后端、beat、worker 数和告警。
3. 确认目标 backend：检查其 Django 版本兼容性、耐久存储、进程部署、任务恢复、结果查询和升级策略。
4. 做单任务 POC：先挑非关键、可幂等的任务，模拟 broker 不可用、worker 被终止、数据库事务回滚和重复投递。
5. 准备回退和观测：比较新旧队列积压、成功率和延迟。不要让新旧 worker 同时消费同一条消息，除非后端和路由明确支持这种迁移方式。
6. 再逐类切换：迁移一类任务并观察后再继续，保留旧实现直到所有待处理消息完成或已按规则转移。

官方 Django 文档指出，较旧 Django 版本可使用 django-tasks backport。实际使用前要核对包的当前维护状态、对当前 Django 和 Python 版本的支持、backend 生态和升级方案。不要仅凭包名相似就认定它与 Django 6.1 的实现、API 或后端完全等同。

站内Django 异步任务实战：Celery 整合与生产级最佳实践仍适合了解 Celery 接入和任务处理；本文补充的是 Django 6 Tasks 的职责边界与迁移评估。系统开发阶段如何把功能、异常和验收连接起来，可参考软件开发流程实战；运行后的日志与故障定位，可参考Django 部署后的日志排查与性能监控。

发布前检查清单

• [ ] 记录 Django、Python、backend、broker 和 worker 的实际版本。
• [ ] 确认当前配置不会让生产任务退化为同步 ImmediateBackend。
• [ ] 任务参数使用最小、可 JSON 往返的数据，不直接传模型实例和秘密。
• [ ] 入队发生在必要的数据库事务提交之后。
• [ ] 对重要业务评估 outbox、重复投递和补偿策略。
• [ ] 任务具有明确幂等键、有限重试、网络超时和失败告警。
• [ ] 监控队列积压与任务延迟，并定义人工重跑流程。
• [ ] 迁移 POC 覆盖 worker 崩溃、broker 故障和数据库回滚。

参考资料

• Django 6.1 Tasks framework
• Django 6.0 release notes
• Django 6.1 release notes
• Celery：First steps with Django
• Celery：Tasks 与幂等、确认和重试
• Django 异步任务实战：Celery 整合与生产级最佳实践
• Django 部署后的日志排查与性能监控
• 软件开发流程实战：从需求分析、技术设计到上线验收

Django Tasks 统一了任务声明和入队接口，但可靠的异步执行仍依赖后端、worker 和业务层的失败设计。选择时要逐项验证实际能力；有稳定 Celery 系统的项目，应先找出明确的迁移收益，再决定是否改造。