SleekXMPP 定时任务教程:Scheduler 调度器实现周期性消息与心跳的完整指南

原创2026-11-03 15:13:321,758 阅读

SleekXMPP 定时任务教程:Scheduler 调度器实现周期性消息与心跳的完整指南

SleekXMPP 是一款功能成熟的 Python XMPP 客户端/组件库,其内置的 Scheduler(调度器) 让"定时发送消息""周期性心跳保活"这类需求变得极其简单——只需调用一次 schedule() 方法,即可让任意回调函数在指定秒数后自动执行,并支持无限循环重复。本教程带你从零理解 SleekXMPP 定时任务的原理、写法与实战用法。

什么是 SleekXMPP 的 Scheduler?🧩

Scheduler 是 SleekXMPP 内部的一个独立线程调度器,源码位于 sleekxmpp/xmlstream/scheduler.py。它与 Python 标准库的 sched 模块不同:允许在任务执行过程中动态增删任务,且与 SleekXMPP 的线程模型(事件队列、发送队列、调度器线程)天然集成。

只要调用 xmpp.process() 启动流处理,调度器线程就会自动运行(参见 sleekxmpp/xmlstream/xmlstream.py#L1534-L1535),无需任何手动启动。

SleekXMPP 自身就依赖 Scheduler 完成了三件重要的"幕后工作":

内置定时任务 作用 源码位置
Whitespace Keepalive 每 300 秒发送一个空格字符,防止连接被中间设备断开 xmlstream.py#L1025-L1030
Session timeout check 45 秒内未完成会话建立则自动断开重连 xmlstream.py#L758-L760
Certificate Expiration 证书到期前自动触发重连,切换新证书 xmlstream.py#L1009-L1011

换句话说:你每发出一条消息、每次保持连接不掉线,背后都有 Scheduler 在工作。

核心用法:一行 schedule() 搞定定时任务

Scheduler 对外暴露的核心入口是 XMLStream.schedule() 方法,参数非常直观:

xmpp.schedule(name='my_task',      # 任务唯一名称
              seconds=300,         # 等待 300 秒后执行
              callback=func,       # 要执行的函数
              args=(a, b),         # 位置参数(可选)
              kwargs={'k': v},      # 关键字参数(可选)
              repeat=True)         # True = 循环重复;False = 只执行一次

几个关键行为值得注意:

  • repeat=True 实现周期性执行:任务执行一次后自动重置计时器,按固定间隔无限循环(见 scheduler.py#L89-L92)。
  • name 必须全局唯一:重复注册同名任务会抛出 ValueError: Key xxx already exists(scheduler.py#L216-L220)。
  • 回调会进入事件队列:通过 xmpp.schedule() 注册的回调默认被投递到事件队列中执行,因此天然线程安全,可以随意调用 send()、get_roster() 等流方法。

💡 小技巧:一次性定时任务(比如"30 秒后自动退出")设 repeat=False 即可;想中途取消任务,则按名称调用 xmpp.scheduler.remove('my_task') 提前移除。

实战一:每 5 分钟自动发送一条消息 📨

这是官方入门文档 docs/getting_started/scheduler.rst 中"Send a Message Every 5 Minutes"示例的写法,也是新手最常用的定时任务模式:

class Bot(sleekxmpp.ClientXMPP):

    def __init__(self, jid, password):
        sleekxmpp.ClientXMPP.__init__(self, jid, password)
        # 连接建立成功后,注册每 5 分钟执行的周期任务
        self.add_event_handler('session_start', self.start, threaded=True)

    def start(self, event):
        self.send_presence()
        self.get_roster()
        self.schedule('Send Message Task',
                      300,            # 5 分钟
                      self.send_msg,
                      repeat=True)    # 循环执行

    def send_msg(self):
        self.send_message(mtype='groupchat',
                          to='room@conference.example.org',
                          body='Hello, I am sent every 5 minutes!')

连接成功后(session_start 事件触发),机器人就会每隔 300 秒向群聊群发一条消息。把 seconds 换成任意数值,就能轻松实现"每小时推送状态""每 10 秒刷新数据"等各种周期任务。

实战二:用 XEP-0199 Ping 插件配置心跳保活 💓

长连接应用最怕"连接悄悄断了却不知道"。SleekXMPP 的 XEP-0199 Ping 插件 正是基于 Scheduler 实现心跳的:注册插件时开启 keepalive 选项,插件就会在会话建立后自动注册一个周期任务(ping.py#L98-L101):

xmpp.register_plugin('xep_0199',
                     {'keepalive': True,   # 开启心跳
                      'interval': 300,    # 每 300 秒 ping 一次服务器
                      'timeout': 30})    # 30 秒无响应判定为断线

其内部逻辑是:

  1. 每 interval 秒向服务器发送一次 Ping 请求;
  2. 若在 timeout 秒内没有收到 Pong 回复,则判定连接已丢失,自动调用 reconnect() 重建连接(ping.py#L106-L115);
  3. 会话结束时自动清理任务:xmpp.scheduler.remove('Ping keepalive')(ping.py#L103-L104)。

对于"服务必须 7×24 在线"的场景,这个机制配合 SleekXMPP 的自动重连能力,基本可以让掉线恢复完全透明。更多 Ping 用法可参考官方示例 examples/ping.py。

任务管理:删除、避免重复与常见陷阱

Scheduler 提供简单的任务生命周期管理,核心 API 一览:

操作 方法 说明
新增任务 xmpp.schedule(name, seconds, callback, ...) 注册到任务队列
删除任务 xmpp.scheduler.remove(name) 提前取消且不会执行
关闭调度器 xmpp.scheduler.quit() 停止调度线程,流关闭时自动调用

使用 Scheduler 时注意以下几点,可以避开大多数坑:

  • 任务名唯一:注册前先 remove 同名旧任务,或在逻辑上确保名称不冲突,否则抛 Key already exists。
  • 周期任务要记得清理:插件在 plugin_end / session_end 时主动 remove,防止断线重连后任务重复注册——官方 Ping 插件就是这么做的。
  • 回调保持幂等:周期任务无法保证两次执行之间不会出错,回调内部建议做好异常捕获(如 Ping 插件捕获 IqTimeout 后触发重连)。
  • 别在回调里做阻塞操作:回调在事件队列线程中运行,耗时应尽量短,长耗时逻辑可另起线程。

相关文档与源码导读

如果你想进一步深入,建议按以下顺序阅读项目内的资料:

掌握 schedule() + repeat=True 这个组合,再加上 scheduler.remove() 的清理习惯,你就能在 SleekXMPP 中自如地实现周期性消息推送、心跳保活、定时清理等各种自动化任务了。⏱️

登录后查看全文
SleekXMPP