RQ任务队列核心功能详解：从入门到实战-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01048/article/details/148416055

RQ任务队列核心功能详解：从入门到实战

rq Simple job queues for Python 项目地址: https://gitcode.com/gh_mirrors/rq1/rq

什么是RQ任务队列

RQ(Redis Queue)是一个基于Redis的轻量级Python任务队列系统，它允许开发者将耗时的Python函数调用转移到后台工作进程中异步执行。与Celery等重量级任务队列相比，RQ以其简单易用、零配置的特点受到开发者青睐。

核心概念解析

任务(Job)的本质

在RQ中，一个任务本质上就是一个普通的Python函数及其参数的组合。RQ的创新之处在于，它不需要你对函数做任何特殊处理——任何Python函数都可以通过RQ转换为异步任务。

def count_words_at_url(url):
    """统计网页字数"""
    resp = requests.get(url)
    return len(resp.text.split())

如上所示，这个统计网页字数的函数就是一个完全普通的Python函数，没有任何RQ特有的装饰或修改。

任务入队实战

基础入队操作

要将函数转为后台任务，只需几行代码：

from rq import Queue
from redis import Redis

# 1. 建立Redis连接
redis_conn = Redis()

# 2. 创建队列实例(默认队列)
q = Queue(connection=redis_conn)  

# 3. 将任务加入队列
job = q.enqueue(count_words_at_url, 'http://example.com')

多队列管理

RQ支持创建多个优先级队列，这是生产环境中的常见做法：

high_priority = Queue('high', connection=redis_conn)
medium_priority = Queue('medium', connection=redis_conn)
low_priority = Queue('low', connection=redis_conn)

# 将重要任务放入高优先级队列
high_priority.enqueue(process_payment, order_id)

高级任务控制

任务参数详解

RQ提供了丰富的任务控制参数：

job = q.enqueue(
    process_data,
    args=(data_id,),
    kwargs={'verbose': True},
    job_timeout='30m',  # 任务超时时间(30分钟)
    result_ttl=3600,    # 结果保留1小时
    ttl='1h',           # 任务最长排队1小时
    depends_on=previous_job,  # 依赖其他任务
    at_front=True       # 插队到队列前端
)

任务依赖处理

复杂的工作流可以通过任务依赖实现：

# 创建任务链: A → B → C
job_a = q.enqueue(task_a)
job_b = q.enqueue(task_b, depends_on=job_a)
job_c = q.enqueue(task_c, depends_on=job_b)

RQ 1.11.0+支持更灵活的依赖控制：

from rq.job import Dependency

# 即使依赖任务失败也继续执行
dependency = Dependency(jobs=[job_a], allow_failure=True)
q.enqueue(task_b, depends_on=dependency)

批量任务处理

批量入队操作

1.9.0版本引入了批量任务入队功能，大幅提升性能：

jobs_data = [
    Queue.prepare_data(task1, args=(1,), job_id='job1'),
    Queue.prepare_data(task2, args=(2,), job_id='job2')
]

# 原子性批量入队
jobs = q.enqueue_many(jobs_data)

任务分组管理

2.0版本新增的任务分组功能：

from rq.group import Group

# 创建任务组
group = Group.create(connection=redis_conn)
jobs = group.enqueue_many(
    queue='high',
    jobs_data=[
        Queue.prepare_data(task1, args=(1,)),
        Queue.prepare_data(task2, args=(2,))
    ]
)

# 获取组内所有任务
print(group.get_jobs())

回调机制详解

回调函数类型

RQ支持三种回调函数：

成功回调 - 任务完成后执行
失败回调 - 任务失败后执行
停止回调 - 任务被手动停止时执行

def success_cb(job, conn, result, *args, **kwargs):
    logging.info(f"任务 {job.id} 完成，结果: {result}")

def failure_cb(job, conn, exc_type, exc_value, traceback):
    logging.error(f"任务 {job.id} 失败: {exc_value}")

q.enqueue(
    critical_task,
    on_success=success_cb,
    on_failure=failure_cb
)

回调超时控制

1.14.0版本引入了回调超时配置：

from rq import Callback

q.enqueue(
    process_data,
    on_success=Callback(success_cb, timeout=120),  # 2分钟超时
    on_failure=Callback(failure_cb, timeout=30)    # 30秒超时
)

命令行操作指南

命令行任务入队

1.10.0版本新增了CLI任务入队功能：

# 基本用法
rq enqueue module.function arg1 arg2

# 带参数的高级用法
rq enqueue -q high --timeout 5m module.task key1:=value1 key2:={"json":"data"}

参数支持多种格式：

普通文本：key=value
JSON格式：key:=value
Python字面量：key%=value

队列管理技巧

队列状态监控

q = Queue('high', connection=redis_conn)

# 获取队列长度
print(len(q))

# 获取所有任务ID
print(q.job_ids)

# 获取特定任务
job = q.fetch_job('some_id')

# 清空队列
q.empty()

# 删除队列
q.delete(delete_jobs=True)

系统维护操作

暂停和恢复任务处理：

# 暂停所有队列5分钟
rq suspend --duration 300

# 手动恢复
rq resume

设计哲学与限制

RQ的设计遵循"简单至上"原则：

无需预先配置队列
动态创建队列
仅依赖Redis和Python pickle协议

需要注意的是：

由于使用pickle序列化，RQ是Python专属系统
不适用于需要复杂消息路由的场景
适合中小规模异步任务处理

开发调试技巧

同步测试模式

在测试环境下可以启用同步模式：

q = Queue(is_async=False, connection=redis_conn)
job = q.enqueue(task)  # 同步执行
print(job.result)      # 立即获取结果

@job装饰器

类似Celery的task装饰器：

from rq.decorators import job

@job('low', timeout='1h')
def long_running_task(data):
    # 耗时处理...
    return result

# 异步调用
job = long_running_task.delay(large_data)