单片机与物联网 / 系统课时
模拟重复投递并验证幂等
模拟重复投递并验证幂等
QoS 1 允许同一消息被再次投递,消费者不能只靠协议确认避免重复执行。本课用 MQTT 5、Paho 与 SQLite 复现事件重复发布,以及提交后未确认就崩溃的场景,检查业务动作是否只记账一次。
学习目标
- 区分 MQTT 重传标记、Packet Identifier 与业务唯一标识。
- 用 SQLite 唯一约束和事务实现可重复消费的命令处理。
- 注入确认前崩溃,验证 QoS 1 补发不会重复提交业务动作。
明确两段 QoS 1 与去重边界
发布端到 Broker、Broker 到订阅端是两段分别确认的 QoS 1 传输。发布端可能因为没有收到 PUBACK 而重发;订阅端也可能在收到消息、完成处理但尚未确认时掉线,Broker 会在持久会话恢复后重投递。
业务去重不能依赖 MQTT Packet Identifier:它只在一段协议连接的未完成报文中有意义,也不能单靠 DUP 判断消息是否已经执行。应用应为同一业务动作始终使用相同的 eventId,例如 evt-001,并在执行副作用的同一事务内写入去重记录。

创建事务化的消息消费者
环境准备:本地运行的 Mosquitto 2.x(127.0.0.1:1883),Python 3、paho-mqtt 2.x 和标准库 sqlite3;发布端使用 mosquitto_pub。首次实验请用未出现过的 eventId,并确认当前目录没有上次实验遗留的同名 SQLite 数据库。
把代码保存为 consumer.py。这里用 SQLite 中的 open_count 代表关键业务动作的执行次数;去重插入与计数增加放在一个数据库事务中,事务成功后才手动确认 MQTT 消息。
import json
import os
import sqlite3
import paho.mqtt.client as mqtt
from paho.mqtt.packettypes import PacketTypes
from paho.mqtt.properties import Properties
DB = "mqtt_idempotent.db"
TOPIC = "lab/motor-07/commands"
def init_db():
with sqlite3.connect(DB) as db:
db.execute("CREATE TABLE IF NOT EXISTS processed (event_id TEXT PRIMARY KEY, device_id TEXT, action TEXT)")
db.execute("CREATE TABLE IF NOT EXISTS state (device_id TEXT PRIMARY KEY, open_count INTEGER NOT NULL)")
def on_connect(client, userdata, flags, reason_code, properties):
print(f"session_present={flags.session_present}", flush=True)
if reason_code == 0 and not flags.session_present:
client.subscribe(TOPIC, qos=1)
def on_message(client, userdata, msg):
event = json.loads(msg.payload)
if event["action"] != "OPEN":
raise ValueError("demo only accepts OPEN")
event_id, device_id = event["eventId"], event["deviceId"]
# 唯一键与业务效果在同一事务中提交。
with sqlite3.connect(DB) as db:
cursor = db.execute(
"INSERT INTO processed VALUES (?, ?, ?) "
"ON CONFLICT(event_id) DO NOTHING",
(event_id, device_id, event["action"]),
)
inserted = cursor.rowcount == 1
if inserted:
db.execute(
"INSERT INTO state VALUES (?, 1) "
"ON CONFLICT(device_id) DO UPDATE SET open_count=open_count+1",
(device_id,),
)
count = db.execute(
"SELECT open_count FROM state WHERE device_id=?", (device_id,)
).fetchone()[0]
print(
f"{'applied' if inserted else 'skipped'} "
f"eventId={event_id} open_count={count}", flush=True
)
# 故障注入:数据库已提交,模拟进程来不及发送 PUBACK。
if os.getenv("CRASH_BEFORE_ACK") == "1" and inserted:
os._exit(23)
# 仅在事务提交之后确认 QoS 1 消息。
client.ack(msg.mid, msg.qos)
init_db()
props = Properties(PacketTypes.CONNECT)
props.SessionExpiryInterval = 180
client = mqtt.Client(
mqtt.CallbackAPIVersion.VERSION2,
client_id="idem-consumer",
protocol=mqtt.MQTTv5,
manual_ack=True,
)
client.on_connect = on_connect
client.on_message = on_message
# 新进程也不清空 Broker 上仍有效的订阅会话。
client.connect("127.0.0.1", 1883, keepalive=15,
clean_start=False, properties=props)
client.loop_forever()预期结果:运行 python consumer.py 后,首次连接打印 session_present=False 并建立 QoS 1 订阅;程序持续等待消息。manual_ack=True 使确认发生在数据库事务提交之后。示例只处理合法的 OPEN 载荷;生产环境须对无效消息安排错误记录与死信处理,避免回调异常或无休止重试。
连续发布同一业务事件
保持消费者运行,在另一终端连续发送两次完全相同的业务事件;这是确定性的重复输入测试,不是假称 MQTT 已自动重传:
mosquitto_pub -V 5 -h 127.0.0.1 -q 1 -t lab/motor-07/commands \
-m '{"eventId":"evt-001","deviceId":"motor-07","action":"OPEN"}'
mosquitto_pub -V 5 -h 127.0.0.1 -q 1 -t lab/motor-07/commands \
-m '{"eventId":"evt-001","deviceId":"motor-07","action":"OPEN"}'预期结果:两个发布命令成功时通常不输出内容;消费者终端应依次打印:
applied eventId=evt-001 open_count=1
skipped eventId=evt-001 open_count=1首次 INSERT 成功才会增加 open_count;第二次被唯一约束拦截,即使 Broker 两次都成功交付,也不会再次执行数据库内的业务更新。
在提交后、确认前制造崩溃
先停止正常消费者,随后在 Bash 中启用故障开关重启。它只用于实验,会让进程在新事件首次提交后立即退出:
CRASH_BEFORE_ACK=1 python consumer.py预期结果:程序保持运行并等待下一条新事件。在另一个终端发布 evt-002:
mosquitto_pub -V 5 -h 127.0.0.1 -q 1 -t lab/motor-07/commands \
-m '{"eventId":"evt-002","deviceId":"motor-07","action":"OPEN"}'预期结果:消费者提交事务、打印下列内容,然后以退出码 23 结束,没有执行 client.ack():
applied eventId=evt-002 open_count=2在会话 180 秒有效期内,不带故障开关重新运行:
python consumer.py预期结果:Broker 保有该订阅者会话时,消费者收到未确认的 QoS 1 报文,并跳过重复动作:
session_present=True
skipped eventId=evt-002 open_count=2这次属于未确认消息在会话恢复后的真正重投递。若没有收到,先查是否复用了 idem-consumer、是否设置 clean_start=False、会话是否过期,以及 Broker 是否在实验期间重启或清空会话。DUP 是协议重发提示,不能替代 eventId。
检查幂等的适用范围
在另一个终端直接检查数据库,而不是只相信消费者日志:
python -c 'import sqlite3; db=sqlite3.connect("mqtt_idempotent.db"); print(db.execute("SELECT open_count FROM state WHERE device_id=?", ("motor-07",)).fetchone()[0])'预期输出:
2这个实验保证的是同一个 SQLite 数据库事务内部的去重记录和计数更新:eventId 必须稳定,去重表必须持久保留,且成功提交后再 ACK。若先 ACK 再提交,进程崩溃会漏执行;若先修改状态再另行插入去重键,两个操作之间崩溃就可能重复执行。
真实的开门、扣款或远程设备指令不一定与 SQLite 处于同一事务。此时还需让最终执行方识别相同业务命令 ID,或采用事务发件箱等机制处理跨系统副作用;MQTT QoS 2 也不直接保证外部业务动作恰好执行一次。