SleekXMPP 定时任务教程:Scheduler 调度器实现周期性消息与心跳的完整指南
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 秒无响应判定为断线
其内部逻辑是:
- 每
interval秒向服务器发送一次 Ping 请求; - 若在
timeout秒内没有收到 Pong 回复,则判定连接已丢失,自动调用reconnect()重建连接(ping.py#L106-L115); - 会话结束时自动清理任务:
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后触发重连)。 - 别在回调里做阻塞操作:回调在事件队列线程中运行,耗时应尽量短,长耗时逻辑可另起线程。
相关文档与源码导读
如果你想进一步深入,建议按以下顺序阅读项目内的资料:
- 调度器 API 参考:docs/api/xmlstream/scheduler.rst
- 定时任务入门示例:docs/getting_started/scheduler.rst
- Scheduler 核心源码:sleekxmpp/xmlstream/scheduler.py(
Task与Scheduler两个类,代码量小,适合通读) - 心跳保活插件:sleekxmpp/plugins/xep_0199/ping.py
- 官方 Ping 客户端示例:examples/ping.py
掌握 schedule() + repeat=True 这个组合,再加上 scheduler.remove() 的清理习惯,你就能在 SleekXMPP 中自如地实现周期性消息推送、心跳保活、定时清理等各种自动化任务了。⏱️