欢迎光临
我们一直在努力

fastapi-APscheduler

📚 APScheduler 定时任务详解

🎯 1. APScheduler 核心概念

APScheduler(Advanced Python Scheduler)是一个强大的任务调度框架,包含 4 个核心组件:

┌─────────────────────────────────────────────────────┐
│ APScheduler 架构 │
├─────────────────────────────────────────────────────┤
│ │
│ 📅 Scheduler (调度器) │
│ └─ 负责管理所有任务的调度和执行 │
│ │
│ ⏰ Trigger (触发器) │
│ └─ 定义任务何时执行(间隔、定时、Cron) │
│ │
│ 🎯 Job (任务) │
│ └─ 要执行的具体函数 │
│ │
│ 📦 JobStore (任务存储) │
│ └─ 持久化任务信息(内存、数据库、Redis) │
│ │
└─────────────────────────────────────────────────────┘


🎯 2. 调度器类型(Scheduler Types)

你的项目使用 BackgroundScheduler,让我对比不同类型:

from apscheduler.schedulers.background import BackgroundScheduler

调度器类型对比

调度器类型适用场景运行方式你的项目
BackgroundScheduler Web应用、长时间运行的程序 后台线程运行,不阻塞主线程 ✅ 使用
BlockingScheduler 独立脚本、主要功能是定时任务 阻塞主线程,独占程序 ❌ 不适合
AsyncIOScheduler asyncio异步应用 与asyncio事件循环集成 ❌ 未使用
GeventScheduler Gevent协程应用 与Gevent集成 ❌ 未使用

为什么选择 BackgroundScheduler?

# 你的项目使用场景
scheduler = BackgroundScheduler() # ⭐ 后台运行
scheduler.start() # 不阻塞

# FastAPI 主线程继续处理 HTTP 请求
app = FastAPI() # 主线程处理 Web 请求
# 调度器在后台线程自动执行定时任务

优点:

  • ✅ 不阻塞主线程(FastAPI 可以继续处理请求)
  • ✅ 自动在后台线程运行
  • ✅ 适合 Web 应用

🎯 3. 调度器配置详解

def init_scheduler():
"""初始化调度器"""
global scheduler

if scheduler is not None:
logger.warning("调度器已经初始化,跳过")
return scheduler

logger.info("🔧 初始化定时任务调度器…")

scheduler = BackgroundScheduler(
job_defaults={
'coalesce': True, # 合并错过的任务
'max_instances': 1, # 每个任务最多一个实例
'misfire_grace_time': 60 # 错过任务的宽限时间(秒)
}
)

参数详解

1️⃣ coalesce=True – 任务合并

场景:服务器重启后,错过了多次任务执行

# 假设每10分钟执行一次,服务器停机了1小时
# coalesce=True: 只执行1次(合并所有错过的任务)
# coalesce=False: 执行6次(补上所有错过的任务)

# 你的项目:每55.5小时同步一次
# 如果停机3天,重启后:
# coalesce=True → 只执行1次同步 ✅ 合理
# coalesce=False → 执行多次同步 ❌ 浪费资源

2️⃣ max_instances=1 – 任务实例数

场景:防止任务重复执行

# 假设同步任务执行需要2小时,但每1小时触发一次
# max_instances=1: 如果上一次还在执行,跳过本次
# max_instances=2: 允许2个任务同时执行

# 你的项目:
# 华为云同步可能需要1小时
# max_instances=1 → 防止多个同步任务同时运行 ✅

实际效果:

时间轴:
0分 – 任务开始
60分 – 任务触发(因为上次还在执行,跳过)
120分 – 任务结束
180分 – 任务开始(上次已结束,可以执行)

3️⃣ misfire_grace_time=60 – 错过宽限时间

场景:任务错过预定时间后的容忍度

# 预定10:00执行,但调度器在10:01才检查
# misfire_grace_time=60: 10:01仍然执行(在宽限时间内)
# misfire_grace_time=30: 10:01不执行(超过宽限时间)

# 你的项目:
# 允许60秒的延迟容忍度


🎯 4. 触发器(Trigger)详解

IntervalTrigger – 间隔触发器

# 添加华为云同步任务
scheduler.add_job(
sync_huawei_resources_job,
trigger=IntervalTrigger(minutes=huawei_interval),
id="huawei_resource_sync",
name="华为云资源到期信息同步",
replace_existing=True
)

触发器类型对比

触发器类型使用场景示例你的项目
IntervalTrigger 固定间隔执行 每30分钟、每2小时 ✅ 使用
CronTrigger 特定时间执行 每天凌晨2点、每周一 ❌ 未使用
DateTrigger 一次性任务 2025-01-20 10:00 ❌ 未使用

IntervalTrigger 参数

# 你的项目使用方式
IntervalTrigger(minutes=3330) # 每55.5小时

# 其他使用方式
IntervalTrigger(seconds=30) # 每30秒
IntervalTrigger(minutes=10) # 每10分钟
IntervalTrigger(hours=2) # 每2小时
IntervalTrigger(days=1) # 每1天
IntervalTrigger(weeks=1) # 每1周
IntervalTrigger(hours=1, minutes=30) # 每1.5小时

如果使用 CronTrigger(举例)

from apscheduler.triggers.cron import CronTrigger

# 每天凌晨2点执行
scheduler.add_job(
sync_job,
trigger=CronTrigger(hour=2, minute=0),
id="daily_sync"
)

# 每周一早上9点执行
scheduler.add_job(
weekly_report,
trigger=CronTrigger(day_of_week='mon', hour=9, minute=0),
id="weekly_report"
)


🎯 5. 任务定义和添加

任务函数定义

def sync_huawei_resources_job():
"""华为云资源到期信息同步任务"""
start_time = datetime.now()
logger.info("🚀 [华为云] 开始同步到期资源…")

db = None
sync_log = None

try:
db = SessionLocal()

任务结构最佳实践

def your_job_function():
"""任务函数"""

# 1️⃣ 记录开始时间
start_time = datetime.now()
logger.info("任务开始")

# 2️⃣ 创建独立的数据库会话
db = SessionLocal() # ⚠️ 不能共享主线程的会话

try:
# 3️⃣ 创建日志记录
log = TaskLog(status="进行中", start_time=start_time)
db.add(log)
db.commit()

# 4️⃣ 执行业务逻辑
result = do_work()

# 5️⃣ 更新日志为成功
log.status = "成功"
log.end_time = datetime.now()
db.commit()

except Exception as e:
# 6️⃣ 错误处理
logger.error(f"任务失败: {e}")
log.status = "失败"
log.error_message = str(e)
db.commit()
raise # ⚠️ 重新抛出异常,让监听器捕获

finally:
# 7️⃣ 清理资源
db.close()

添加任务到调度器

scheduler.add_job(
func=sync_huawei_resources_job, # ⭐ 任务函数
trigger=IntervalTrigger(minutes=60), # ⭐ 触发器
id="huawei_sync", # ⭐ 唯一ID(用于管理)
name="华为云同步", # ⭐ 任务名称(显示用)
replace_existing=True, # ⭐ 如果ID重复,替换旧任务
misfire_grace_time=60, # 单个任务的错过宽限时间
max_instances=1 # 单个任务的最大实例数
)

参数说明:

  • func:要执行的函数
  • trigger:触发器对象
  • id:唯一标识符,用于后续管理(暂停、删除)
  • name:任务名称,用于显示
  • replace_existing:如果 ID 重复,是否替换(防止重复添加)

🎯 6. 事件监听器(Event Listeners)

任务执行监听器

def job_listener(event):
"""任务执行监听器"""
job_id = event.job_id

if event.exception:
logger.error(f"❌ 定时任务执行失败: {job_id}")
logger.error(f" 异常信息: {event.exception}")
else:
logger.info(f"✅ 定时任务执行完成: {job_id}")

def job_missed_listener(event):
"""任务错过监听器"""
logger.warning(f"⚠️ 定时任务错过执行: {event.job_id}")

添加监听器

# 添加监听器
scheduler.add_listener(job_listener, EVENT_JOB_ERROR | EVENT_JOB_EXECUTED)
scheduler.add_listener(job_missed_listener, EVENT_JOB_MISSED)

事件类型

事件类型触发时机你的项目
EVENT_JOB_EXECUTED 任务执行成功 ✅ 监听
EVENT_JOB_ERROR 任务执行失败 ✅ 监听
EVENT_JOB_MISSED 任务错过执行 ✅ 监听
EVENT_JOB_ADDED 任务添加 ❌ 未监听
EVENT_JOB_REMOVED 任务移除 ❌ 未监听

监听器的作用

# 实际运行效果:

# 1. 任务成功执行
✅ 定时任务执行完成: huawei_resource_sync

# 2. 任务执行失败
❌ 定时任务执行失败: huawei_resource_sync
异常信息: Connection timeout

# 3. 任务错过执行(系统繁忙)
⚠️ 定时任务错过执行: huawei_resource_sync


🎯 7. 任务管理(启动、停止、状态查询)

启动调度器

def start_scheduler():
"""启动调度器"""
global scheduler

if scheduler is None:
scheduler = init_scheduler()

if not scheduler.running:
scheduler.start()
logger.info("✅ 定时任务调度器已启动")
else:
logger.info("⚠️ 调度器已在运行中")

return scheduler

停止调度器

def stop_scheduler():
"""停止调度器"""
global scheduler

if scheduler and scheduler.running:
scheduler.shutdown(wait=False)
logger.info("🛑 定时任务调度器已停止")

scheduler = None

shutdown() 参数:

  • wait=False:立即停止,不等待正在执行的任务
  • wait=True:等待所有任务执行完毕再停止

获取调度器状态

def get_scheduler_status():
"""获取调度器状态"""
global scheduler

if scheduler is None:
return {"running": False, "jobs": []}

jobs = []
for job in scheduler.get_jobs():
jobs.append({
"id": job.id,
"name": job.name,
"next_run_time": job.next_run_time.isoformat() if job.next_run_time else None,
"trigger": str(job.trigger)
})

return {
"running": scheduler.running,
"jobs": jobs
}

返回示例:

{
"running": true,
"jobs": [
{
"id": "huawei_resource_sync",
"name": "华为云资源到期信息同步",
"next_run_time": "2026-01-26T15:30:00",
"trigger": "interval[0:55:30:00]"
},
{
"id": "alicloud_resource_sync",
"name": "阿里云资源到期信息同步",
"next_run_time": "2026-01-26T16:00:00",
"trigger": "interval[0:55:30:00]"
}
]
}


🎯 8. 与 FastAPI 集成

应用生命周期集成

@asynccontextmanager
async def lifespan(app: FastAPI):
"""应用生命周期管理"""
# 启动时
logger.info("🚀 资源过期订单查询平台启动…")

# 创建数据库表
try:
Base.metadata.create_all(bind=engine)
logger.info("✅ 数据库表创建/检查完成")
except Exception as e:
logger.error(f"❌ 数据库初始化失败: {e}")

# 打印同步时间间隔配置
logger.info("⏰ ========== 同步时间间隔配置 ==========")
huawei_interval = int(os.getenv("HUAWEI_SYNC_INTERVAL_MINUTES", 3330))
alicloud_interval = int(os.getenv("ALICLOUD_SYNC_INTERVAL_MINUTES", 3330))
aws_interval = int(os.getenv("AWS_SYNC_INTERVAL_MINUTES", 30))

logger.info(f" 📱 华为云同步间隔: {huawei_interval} 分钟 ({huawei_interval/60:.2f} 小时)")
logger.info(f" ☁️ 阿里云同步间隔: {alicloud_interval} 分钟 ({alicloud_interval/60:.2f} 小时)")
logger.info(f" 🌐 AWS同步间隔: {aws_interval} 分钟 ({aws_interval/60:.2f} 小时)")
logger.info("⏰ ====================================")

# 启动定时任务调度器
try:
start_scheduler()
logger.info("✅ 定时任务调度器启动成功")
except Exception as e:
logger.error(f"❌ 定时任务调度器启动失败: {e}")

yield

# 关闭时
logger.info("👋 资源过期订单查询平台关闭…")

# 停止定时任务调度器
try:
stop_scheduler()
logger.info("✅ 定时任务调度器已停止")
except Exception as e:
logger.error(f"❌ 停止定时任务调度器失败: {e}")

API 管理接口

@app.get("/api/scheduler/status")
async def scheduler_status():
"""获取定时任务调度器状态"""
return get_scheduler_status()

@app.post("/api/scheduler/start")
async def scheduler_start():
"""启动定时任务调度器"""
try:
start_scheduler()
return {"success": True, "message": "调度器已启动", "status": get_scheduler_status()}
except Exception as e:
raise HTTPException(status_code=500, detail=str(e))

@app.post("/api/scheduler/stop")
async def scheduler_stop():
"""停止定时任务调度器"""
try:
stop_scheduler()
return {"success": True, "message": "调度器已停止"}
except Exception as e:
raise HTTPException(status_code=500, detail=str(e))


🎯 9. 完整执行流程图

┌─────────────────────────────────────────────────────────────┐
│ 应用启动流程 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────┐
│ FastAPI 启动 │
│ lifespan() 执行 │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ start_scheduler() │ ← 启动调度器
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ init_scheduler() │ ← 初始化配置
└──────────┬──────────┘
│
├─→ 配置 job_defaults (coalesce, max_instances, …)
│
├─→ 添加监听器 (job_listener, job_missed_listener)
│
├─→ 添加华为云任务 (IntervalTrigger: 3330分钟)
│
└─→ 添加阿里云任务 (IntervalTrigger: 3330分钟)
│
▼
┌─────────────────────┐
│ scheduler.start() │ ← 调度器开始运行(后台线程)
└──────────┬──────────┘
│
▼
┌────────────────────────────────────────────────────────┐
│ 调度器运行中(后台线程) │
├────────────────────────────────────────────────────────┤
│ │
│ ⏰ 每 3330 分钟触发一次 │
│ │ │
│ ├─→ 检查是否有任务在执行 (max_instances=1) │
│ │ │
│ ├─→ 执行 sync_huawei_resources_job() │
│ │ │ │
│ │ ├─→ 创建数据库会话 │
│ │ ├─→ 创建同步日志(进行中) │
│ │ ├─→ 调用云API获取资源 │
│ │ ├─→ 保存到数据库 │
│ │ ├─→ 更新同步日志(成功/失败) │
│ │ └─→ 关闭数据库会话 │
│ │ │
│ └─→ 触发监听器 │
│ ├─→ job_listener (记录成功/失败) │
│ └─→ job_missed_listener (记录错过) │
│ │
└────────────────────────────────────────────────────────┘
│
│ (应用关闭)
▼
┌─────────────────────┐
│ stop_scheduler() │ ← 停止调度器
└─────────────────────┘


🎯 10. 最佳实践总结

✅ 你的项目做得好的地方

  • 独立数据库会话

    db = SessionLocal() # ✅ 每个任务创建独立会话

  • 完整的错误处理

    try:
    # 任务逻辑
    except Exception as e:
    # 记录错误
    finally:
    db.close() # ✅ 确保资源释放

  • 任务日志记录

    sync_log = ResourceSyncLog(
    status="进行中",
    start_time=datetime.now()
    ) # ✅ 记录执行历史

  • 单例模式

    global scheduler
    if scheduler is not None:
    return scheduler # ✅ 防止重复初始化

  • 事件监听

    scheduler.add_listener(job_listener, EVENT_JOB_ERROR | EVENT_JOB_EXECUTED)
    # ✅ 监控任务执行状态

  • ⚠️ 可以改进的地方

  • 任务持久化(可选)

    # 当前:任务存储在内存中,重启后丢失
    # 改进:使用数据库存储任务
    from apscheduler.jobstores.sqlalchemy import SQLAlchemyJobStore

    jobstores = {
    'default': SQLAlchemyJobStore(url='sqlite:///jobs.db')
    }
    scheduler = BackgroundScheduler(jobstores=jobstores)

  • 任务超时控制(可选)

    # 当前:没有超时限制
    # 改进:使用信号或线程超时
    import signal

    def timeout_handler(signum, frame):
    raise TimeoutError("任务超时")

    signal.signal(signal.SIGALRM, timeout_handler)
    signal.alarm(3600) # 1小时超时


  • 📊 知识点总结表

    知识点说明你的项目重要性
    BackgroundScheduler 后台线程调度器 ✅ 使用 ⭐⭐⭐⭐⭐
    IntervalTrigger 间隔触发器 ✅ 使用 ⭐⭐⭐⭐⭐
    coalesce 合并错过的任务 ✅ True ⭐⭐⭐⭐
    max_instances 最大任务实例数 ✅ 1 ⭐⭐⭐⭐⭐
    misfire_grace_time 错过宽限时间 ✅ 60秒 ⭐⭐⭐
    事件监听器 监控任务执行 ✅ 使用 ⭐⭐⭐⭐
    独立数据库会话 避免会话冲突 ✅ 使用 ⭐⭐⭐⭐⭐
    任务日志 记录执行历史 ✅ 使用 ⭐⭐⭐⭐
    API管理接口 启动/停止/状态查询 ✅ 使用 ⭐⭐⭐⭐

    🎓 实际运行效果

    当你启动应用时,日志输出:

    🚀 资源过期订单查询平台启动…
    ✅ 数据库表创建/检查完成
    ⏰ ========== 同步时间间隔配置 ==========
    📱 华为云同步间隔: 3330 分钟 (55.50 小时)
    ☁️ 阿里云同步间隔: 3330 分钟 (55.50 小时)
    🌐 AWS同步间隔: 30 分钟 (0.50 小时)
    ⏰ ====================================
    🔧 初始化定时任务调度器…
    📅 华为云资源同步任务已添加,间隔 3330 分钟
    📅 阿里云资源同步任务已添加,间隔 3330 分钟
    ✅ 定时任务调度器已启动
    ✅ 定时任务调度器启动成功

    # 55.5小时后…
    🚀 [华为云] 开始同步到期资源…
    📡 正在从华为云BSS API获取资源列表…
    ✅ 成功获取 1234 个资源,开始保存到数据库…
    💾 开始保存资源到数据库 (共 1234 个)…
    ✅ 资源保存完成
    ✅ [华为云] 资源同步完成,共 1234 个资源,耗时 45.2秒
    ✅ 定时任务执行完成: huawei_resource_sync


    你的 APScheduler 实现非常规范和完整!💯

    还有什么想深入了解的吗?比如:

    • 如何添加 Cron 定时任务(每天凌晨执行)?
    • 如何实现任务优先级?
    • 如何监控任务执行时间和性能?
    赞(0)
    未经允许不得转载:171主机测评 » fastapi-APscheduler
    分享到: 更多 (0)

    评论 抢沙发

    • 昵称 (必填)
    • 邮箱 (必填)
    • 网址