FastAPI-XXLJob

English | 简体中文

fastapi-xxljob is a typed FastAPI adapter for the XXL-JOB 2.4.1 executor protocol. Version 0.1.0 supports FastAPI's asynchronous execution and ASGI lifespan model.

Features

• All five executor endpoints: /beat, /idleBeat, /run, /kill, and /log.
• Sync and async handlers, isolated per FastAPI application.
• Automatic registry renewal, deregistration, callbacks, retry, and failover.
• Bounded requests, constant-time token checks, sensitive-data filtering, and managed logs.
• Async-first API plus explicit *_sync methods for scripts and workers.

Install

Requires Python 3.8 or later and FastAPI 0.124.4 or later (before 1.0). Dependency resolution keeps Python 3.8 on FastAPI 0.124.4 while newer Python versions can use newer FastAPI releases.

pip install fastapi-xxljob==0.1.0

Quick start

from fastapi import FastAPI
from fastapi_xxljob import FastAPIXXLJob

app = FastAPI()
xxljob = FastAPIXXLJob(app, {
    "XXL_JOB_ADMIN_ADDRESSES": "http://127.0.0.1:8080/xxl-job-admin",
    "XXL_JOB_ACCESS_TOKEN": "default_token",
    "XXL_JOB_EXECUTOR_APP_NAME": "fastapi-xxljob-executor",
    "XXL_JOB_EXECUTOR_ADDRESS": "http://127.0.0.1:8000",
})

@xxljob.on_run("demoJobHandler")
async def demo(param):
    return f"processed: {param.executor_params}"

uvicorn app:app --host 0.0.0.0 --port 8000

The protocol routes default to the application root and are hidden from OpenAPI; use XXL_JOB_ROUTE_PREFIX when a prefix such as /xxl-job is required. Run, idle-beat, and kill handlers return XXLJobResponse; log handlers may also return LogResponse.

Callbacks are async-first:

await xxljob.callback_success(log_id=1, log_date_time=1730000000000)
xxljob.callback_failure_sync(log_id=2, log_date_time=1730000000000, message="failed")

Main configuration

See Getting started, configuration, API reference, and the examples.

Command line

fastapi-xxljob --app app:app register
fastapi-xxljob --app app:create_app --factory status
fastapi-xxljob --app app:app remove

Scope

This package adapts the executor protocol. It intentionally does not schedule business jobs, create a task queue, store task logs, provide a callback outbox, or retry forever.

Licensed under Apache-2.0. See LICENSE and NOTICE.