RQ任务队列系统核心功能详解

RQ任务队列系统核心功能详解

rq 项目地址: https://gitcode.com/gh_mirrors/rq/rq

什么是RQ任务队列

RQ(Redis Queue)是一个基于Redis的轻量级Python任务队列系统，它允许开发者将耗时的Python函数调用异步化处理。与Celery等重量级任务队列相比，RQ设计更加简洁，特别适合中小型项目的异步任务处理需求。

核心概念解析

任务(Job)的本质

在RQ中，一个任务本质上是：

• 一个Python函数的引用
• 该函数所需的参数
• 执行该函数所需的各种配置选项

任何普通的Python函数都可以被转换为异步任务，无需对函数本身做任何特殊修改。这种设计使得现有代码可以非常容易地迁移到异步处理模式。

任务入队详解

基本入队流程

1. 定义一个普通Python函数：

def count_words_at_url(url):
    resp = requests.get(url)
    return len(resp.text.split())

2. 创建队列连接：

from rq import Queue
from redis import Redis

redis_conn = Redis()
q = Queue(connection=redis_conn)  # 默认队列

3. 将函数调用加入队列：

job = q.enqueue(count_words_at_url, 'http://example.com')

队列命名与优先级

RQ支持多队列模式，可以通过队列名称实现简单的优先级控制：

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

常见实践是使用high、medium、low等名称表示不同优先级的队列。

高级任务配置

RQ提供了丰富的任务控制选项：

| 参数名 | 说明 | 示例值 | |--------|------|--------| | job_timeout | 任务超时时间 | '30s', '5m', '2h' | | result_ttl | 成功结果保留时间 | 3600 (秒) | | ttl | 任务在队列中的最大等待时间 | 600 (秒) | | failure_ttl | 失败任务保留时间 | 86400 (秒) | | depends_on | 任务依赖 | job对象或列表 | | job_id | 自定义任务ID | 'my_task_123' | | at_front | 插队到队列前端 | True/False |

参数传递技巧

当函数参数名与RQ参数名冲突时，可以使用显式参数传递：

q.enqueue(my_func, 
          args=(常规参数,), 
          kwargs={'特殊参数': 值})

批量任务处理

RQ支持高效的任务批量入队：

jobs = q.enqueue_many([
    Queue.prepare_data(func1, args1),
    Queue.prepare_data(func2, args2)
])

批量操作使用Redis管道技术，大幅减少网络往返时间。

任务依赖管理

基础依赖

parent_job = q.enqueue(parent_task)
child_job = q.enqueue(child_task, depends_on=parent_job)

高级依赖控制

from rq.job import Dependency

dependency = Dependency(
    jobs=[job1, job2],
    allow_failure=True,  # 即使依赖任务失败也执行
    enqueue_at_front=True  # 优先执行
)

回调机制详解

RQ支持三种任务状态回调：

1. 成功回调(on_success)
2. 失败回调(on_failure)
3. 停止回调(on_stopped)

回调配置示例

from rq import Callback

q.enqueue(
    main_task,
    on_success=Callback(success_handler, timeout=30),
    on_failure=Callback(failure_handler, timeout=10),
    on_stopped=Callback(stopped_handler, timeout='2m')
)

命令行操作

RQ提供了便捷的命令行工具：

rq enqueue module.function arg1 arg2 --queue high --timeout 30s

支持多种参数格式：

• 普通参数：value
• JSON参数：:{"key": "value"}
• 文件内容：@file.txt

队列管理API

q = Queue('high')

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

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

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

# 清空队列
q.empty()

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

高级特性

@job装饰器

from rq.decorators import job

@job('low', timeout='1h')
def long_running_task(x):
    return x * x

task = long_running_task.delay(5)

同步测试模式

q = Queue(is_async=False)
job = q.enqueue(sync_task)  # 同步执行

系统暂停与恢复

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

# 恢复worker
rq resume

设计哲学与限制

1. 动态队列：无需预先配置，队列随任务自动创建
2. Python专属：依赖Python pickle协议，不跨语言
3. 轻量级：没有复杂的消息路由机制，简单直接

最佳实践建议

1. 为耗时操作设置合理的job_timeout
2. 根据业务重要性使用多队列优先级
3. 合理设置result_ttl避免Redis内存浪费
4. 生产环境建议使用专门的Redis实例
5. 监控关键任务的执行状态

RQ以其简洁的设计和易用性，成为Python生态中轻量级异步任务处理的优秀选择。通过合理利用其丰富的功能特性，可以构建出高效可靠的异步处理系统。

rq 项目地址: https://gitcode.com/gh_mirrors/rq/rq