在 Django 项目中使用 Celery

Celery 先前的版本需要额外安装一个库才能与 Django 集成,但是自3.1版本开始,再也不需要了。现在 Celery 直接支持 Django 了,本文提供一个比较基本的方法将 Celery 集成到 Django 项目中。你将使用与非 Django 用户同样的API,所以在阅读本文之前最好看一下Celery 初步。当你完成一个可以正常运行的例子后,再看看Celery 进阶

为了在 Django 项目中使用 Celery,必须先定义一个 Celery 实例(也叫做 app)。

假如 Django 项目布局是这样的:

- proj/
  - proj/__init__.py
  - proj/settings.py
  - proj/urls.py
- manage.py

那么,推荐的做法是创建一个新的 proj/proj/celery.py 模块,然后在这个模块中定义 Celery 实例。

file: proj/proj/celery.py

from __future__ import absolute_import
import os
from celery import Celery
from django.conf import settings

# set the default Django settings module for the 'celery' program.
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'proj.settings')

app = Celery('proj')

# Using a string here means the worker will not have to
# pickle the object when using Windows.
app.config_from_object('django.conf:settings')
app.autodiscover_tasks(lambda: settings.INSTALLED_APPS)

@app.task(bind=True)
def debug_task(self):
    print('Request: {0!r}'.format(self.request))

接着,需要在 proj/proj/__init__.py 模块中导入这个 Celery 实例(也就是 app)。这样可以确保当 Django 启动时可以加载这个 app,并且 @shared_task 装饰器(后面会提到)也能使用这个 app.

file: proj/proj/__init__.py

from __future__ import absolute_import

# This will make sure the app is always imported when
# Django starts so that shared_task will use this app.
from .celery import app as celery_app

需要注意的是,上述项目布局示例适合大型项目。对于简单的项目,你可以在一个模块中同时定义 Celery 实例和任务,就像Celery 初步里面那样。

我们看看在 proj/proj/celery.py 模块中到底做了什么事。首先,从 future 模块导入 absolute_import,这样,celery.py 模块就不会与 Celery 库相冲突:

from __future__ import absolute_import

然后,为 celery 命令行程序设置环境变量 DJANGO_SETTINGS_MODULE 的默认值:

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'proj.settings')

设置这个环境变量是为了让 celery 命令能找到 Django 项目。这条语句必须出现在 Celery 实例创建之前,也就是接下来要做的:

app = Celery('proj')

这个 app 就是 Celery 实例。可以有很多 Celery 实例,但是当使用 Django 时,似乎没有必要。

我们也将 Django settings 模块作为 Celery 的配置来源。也就是说,不需要使用多个配置文件,直接在 Django settings 里面配置 Celery.

可以将 settings 对象作为参数传入,但是更好的方式是使用字符串,因为当使用 Windows 系统或者 execv 时 celery worker 不需要序列化 settings 对象:

app.config_from_object('django.conf:settings')

为了重用 Django APP,通常是在单独的 tasks.py 模块中定义所有任务。Celery 会自动发现这些模块:

app.autodiscover_tasks(lambda: settings.INSTALLED_APPS)

加上上一句后,Celery 会自动发现 Django APP 中定义的任务,前提是遵循如下 tasks.py 约定:

- app1/
    - tasks.py
    - models.py
- app2/
    - tasks.py
    - models.py

这样就不需要手动把一个个模块加到 CELERY_IMPORTS 配置中。传入的 lambda 函数有如下好处:只在需要的时候才自动发现任务,以及当导入模块时不需要立即对 settings 对象求值。

最后,debug_task 是一个打印本身 request 信息的任务。它使用了在 Celery 3.1引入的任务选项 bind=True,使得引用当前任务实例变得很容易。

使用 @shared_task 装饰器

你很可能在可重用的 Django APP 中编写了一些任务,但是 Django APP 不能依赖于具体的 Django 项目,所以你无法直接导入 Celery 实例。

@shared_task 装饰器能让你在没有具体的 Celery 实例时创建任务:

file: demoapp/tasks.py:

from __future__ import absolute_import
from celery import shared_task

@shared_task
def add(x, y):
    return x + y

@shared_task
def mul(x, y):
    return x * y

@shared_task
def xsum(numbers):
    return sum(numbers)

另请参阅

你可以在这里找到这个 Django 示例项目的完整源码。

使用 Django ORM/Cache 作为结果存储后端(result backend)

如果想在 Django 数据库中保存任务执行结果,还需要安装 django-celery 库(或者使用 SQLAlchemy 结果存储后端)。

django-celery 库基于 Django ORM和缓存框架实现了结果存储后端.

为了在项目中使用该扩展,遵循如下四步:

  1. 安装 django-celery 库

    <pre class=”brush: bash; gutter: false;”>
    $ pip install django-celery
    </pre>

  2. 把 djcelery 加到 INSTALLED_APPS 中

  3. 创建 celery 用到的数据库表

    当使用数据库作为结果存储后端时,这一步会创建用来保存任务结果的相关数据库表,以及周期任务调度器需要使用的数据库表。如果不使用周期任务和任务结果,可以跳过这一步。

    如果使用 south 来做模式迁移,执行:

    <pre class=”brush: bash; gutter: false;”>
    $ python manage.py migrate djcelery
    </pre>

    如果不使用 south,执行:

    <pre class=”brush: bash; gutter: false;”>
    $ python manage.py syncdb
    </pre>

  4. 配置 celery 使用 django-celery 结果存储后端

    对于数据库后端,使用:

    <pre class=”brush: python; gutter: false;”>
    app.conf.update(
    CELERY_RESULT_BACKEND='djcelery.backends.database:DatabaseBackend',
    )
    </pre>

    对于缓存后端,使用:

    <pre class=”brush: python; gutter: false;”>
    app.conf.update(
    CELERY_RESULT_BACKEND='djcelery.backends.cache:CacheBackend',
    )
    </pre>

    如果你将 Django settings 作为 Celery 的配置来源,可以直接在 settings 模块中加上 CELERY_RESULT_BACKEND 配置项,不需要 app.conf.update

相对导入

在导入任务模块时,必须保持一致性。也就是说,如果在 INSTALLED_APPS 中添加的是 project.app,那么需要以 from project.app 的方式导入任务,否则任务的名称将会不一样。
参见自动命名与相对导入

启动 worker 进程

在生产环境中,你希望在后台以守护进程的方式运行 worker(参见以守护进程运行 worker),但是在测试开发环境中,像 Django 的 runserver 那样使用 celery worker 管理命令来启动一个 worker 实例,就有用多了:

$ celery worker -A proj -l info

要查看 celery 的完整命令行选项,使用 help 命令:

$ celery help

接下来怎么办

如果你想学习更多东西,请参考Celery 进阶教程,然后你可以学习用户指南

推荐阅读更多精彩内容