xxl-jobs的python客户端实现

使用pyxxl可以将Python编写的方法注册到XXL-JOB中，使用XXL-JOB-ADMIN管理Python定时任务和周期任务

实现原理：通过XXL-JOB提供的RESTful API接口进行对接

注意！！！如果使用同步方法，请查看以下同步任务注意事项。

已支持的功能

• 执行器注册到job-admin
• 任务注册，类似于flask路由装饰器的用法
• 任务管理（支持在界面上取消、启动等操作，任务完成后会回调admin）
• 支持所有阻塞策略
• 异步支持（推荐）
• job-admin上查看日志

适配的XXL-JOB版本

2.4.0,2.3.0,2.2.0

如遇到不兼容的情况，请通过issue告诉我XXL-JOB版本和对应的问题，我会尽量适配

如何使用

pip install pyxxl

# 如果日志需要写入redis
pip install "pyxxl[redis]"

# 如果需要从.env加载配置
pip install "pyxxl[dotenv]"

# 安装所有功能
pip install "pyxxl[all]"

import asyncio

from pyxxl import ExecutorConfig, PyxxlRunner

config = ExecutorConfig(
    xxl_admin_baseurl="http://localhost:8080/xxl-job-admin/api/",
    executor_app_name="xxl-job-executor-sample",
    executor_host="172.17.0.1",
)

app = PyxxlRunner(config)

@app.register(name="demoJobHandler")
async def test_task():
    await asyncio.sleep(5)
    return "成功..."

# 如果你代码里面没有实现全异步，请使用同步函数，不然会阻塞其他任务
@app.register(name="xxxxx")
def test_task3():
    return "成功3"


app.run_executor()

更多示例和接口文档请参考 PYXXL文档 ，具体代码在example文件夹下面

如果executor服务无法直接连接xxl-admin，请参考PYXXL配置修改executor_listen_host

监控指标

pip install "pyxxl[metrics]"

安装metrics扩展后，执行器会自动加载prometheus的指标监控功能

访问地址为: http://executor_listen_host:executor_listen_port/metrics

同步任务注意事项

同步任务会放入线程池中运行，无法正确接收cancel信号和timeout配置

如果需要使用同步任务并且无法控制（预料）里面执行时间，又需要进行超时和cancel功能的，需要接受pyxxl发出的cancel_event，当该cancel_event被设置时需要中断任务，下面是一个案例

...

@app.register(name="sync_func")
def sync_loop_demo():
    # 如果同步任务里面有循环，为了支持cancel操作，必须每次都判断g.cancel_event.
    task_params_list = []
    while not g.cancel_event.is_set() and task_parasm_list:
        params = task_params_list.pop()
        time.sleep(3)
    return "ok"

# 如下代码会造成线程池里的线程被永远占用，timeout cancel全部不生效
@app.register(name="sync_func2")
def sync_loop_demo2():
    while True:
        time.sleep(3) # 模拟你运行的任务
    return "ok"

其他

• 由于3.9之后加入的许多语法与特性，为减少开发与适配成本，计划后续版本不再适配Python3.9以下版本，0.3.0最后一个支持Python3.8的版本

已知问题

1. 界面上显示的执行时间实际上是任务回调的时间，而不是真正开始的时间。这是XXL-JOB的bug，pyxxl这边已经传了正确的执行时间过去，XXL-JOB没有按预期解析直接取了当前时间

开发人员

以下是如何快速搭建开发调试环境的步骤

启动xxl调度中心

./init_dev_env.sh

启动执行器

# if you need. set venv in project.
# poetry config virtualenvs.in-project true
poetry install --all-extras
# 修改app.py中相关的配置信息,然后启动
poetry run python example/executor_app.py