文章目录
- 玩转物联网只需十行代码，可它为何悄悄停止维护
-
- [1 背景：MQTT 遇上 asyncio，为什么选 hbmqtt？](#1 背景：MQTT 遇上 asyncio，为什么选 hbmqtt？)
- [2 hbmqtt 是什么？](#2 hbmqtt 是什么？)
- [3 安装：一行命令，但别装最新](#3 安装：一行命令，但别装最新)
- [4 五大核心 API：10 行代码跑通发布订阅](#4 五大核心 API：10 行代码跑通发布订阅)
- [5 实战五连击：代码复制即可跑](#5 实战五连击：代码复制即可跑)
-
- [5.1 万级消息吞吐------异步批量发布](#5.1 万级消息吞吐——异步批量发布)
- [5.2 断网自恢复------监听重连事件](#5.2 断网自恢复——监听重连事件)
- [5.3 本地 Broker------单元测试不依赖外网](#5.3 本地 Broker——单元测试不依赖外网)
- [5.4 WebSocket 直播------网页秒级订阅](#5.4 WebSocket 直播——网页秒级订阅)
- [5.5 SSL 上云------一参开启加密](#5.5 SSL 上云——一参开启加密)
- [6 三大常见坑：报错 + 原因 + 急救方案](#6 三大常见坑：报错 + 原因 + 急救方案)
- [7 总结：遗产代码安全驾驶指南](#7 总结：遗产代码安全驾驶指南)
玩转物联网只需十行代码，可它为何悄悄停止维护
本文带你速通 Python 老牌异步 MQTT 库 hbmqtt------从安装到踩坑，从入门到放弃（以及平滑迁移）。读完你将明白：
它为何曾是"高并发 IoT 第一神器"，又为何在 2023 年正式谢幕；如何在遗留项目里继续安全驾驶；新项目又该投奔谁。
1 背景：MQTT 遇上 asyncio，为什么选 hbmqtt？
- 物联网场景动辄万级长连接 、低带宽 、高延迟，MQTT 凭借"轻量级发布/订阅"成为事实标准。
- Python 侧早期全是同步阻塞客户端（Paho），一条网络抖动就卡死整个线程。
- hbmqtt 率先100% 协程化 ，单进程轻松撑住10k 并发 ；还自带Broker 实现，本地测试一条龙。
- 但！官方已宣布停止维护 ，社区分叉出继任者 amqtt。
⇒ 老项目 仍可用，新项目建议直接上 amqtt 或 gmqtt。
2 hbmqtt 是什么？
一句话：纯 Python 写的异步 MQTT 3.1.1 客户端 + 代理双角色库，基于 asyncio，支持 QoS0-2、WS/WSS、自动重连、插件鉴权。
3 安装：一行命令，但别装最新
bash
# 官方最终稳定版
python -m pip install "hbmqtt==0.9.6"⚠️ 不指定版本会拉到 0.10+ 预发行版，API 已变且含未修复 Bug。
4 五大核心 API：10 行代码跑通发布订阅
python
import asyncio
from hbmqtt.client import MQTTClient
async def demo():
client = MQTTClient() # 1. 创建客户端
await client.connect('mqtt://broker.emqx.io:1883') # 2. 连接
await client.subscribe([('demo/hi', 1)]) # 3. 订阅
await client.publish('demo/hi', b'hello', qos=1) # 4. 发布
msg = await client.deliver_message() # 5. 收消息
print('Got:', msg.publish_packet.payload.data)
await client.disconnect() # 6. 优雅断开
asyncio.run(demo())| 行 | 作用 |
|---|---|
| 1 | 事件循环入口 |
| 3 | 生成异步客户端实例 |
| 4 | TCP 连接公网免费 broker |
| 5 | 订阅列表，支持通配符 +/ # |
| 6 | 发布字节串，必须 bytes |
| 7 | 阻塞等待下一条消息（协程不会卡线程） |
| 9 | 释放 TCP / 会话资源 |
5 实战五连击：代码复制即可跑
5.1 万级消息吞吐------异步批量发布
python
async def bulk_publish(n=10_000):
cli = MQTTClient()
await cli.connect('mqtt://127.0.0.1:1883')
# 使用 asyncio.gather 把发布变成"并发烟花"
await asyncio.gather(
*(cli.publish('load/test', f'pkt{i}'.encode(), qos=0) for i in range(n))
)
await cli.disconnect()5.2 断网自恢复------监听重连事件
python
client = MQTTClient(config={'auto_reconnect': True, 'reconnect_max_interval': 5})
# 网络抖动后自动重连，QoS1/2 消息不丢5.3 本地 Broker------单元测试不依赖外网
python
from hbmqtt.broker import Broker
import yaml, asyncio
async def start_local():
config = {'listeners': {'default': {'type': 'tcp', 'bind': '0.0.0.0:1883'}}}
broker = Broker(yaml.safe_dump(config))
await broker.start()
await asyncio.sleep(60) # 跑 1 min 示例
await broker.shutdown()5.4 WebSocket 直播------网页秒级订阅
python
# 只改 URL
await client.connect('ws://broker.emqx.io:8083/mqtt')5.5 SSL 上云------一参开启加密
python
await client.connect('mqtts://broker.emqx.io:8883', cafile='/path/ca.pem')6 三大常见坑：报错 + 原因 + 急救方案
| # | 错误信息 | 根本原因 | 现成解药 |
|---|---|---|---|
| 1 | NoDataException: No more data 频繁出现 |
0.9.6 心跳线程 Bug，长时间空闲会自行断链 | 升级至社区 fork amqtt==0.11.x；或手动 await client.ping() 每 30 s |
| 2 | publish 返回 0，但订阅端收不到 |
QoS0 不存储、不重发；网络闪断即丢包 | 业务关键消息改用 qos=1 及以上 |
| 3 | OSError: [Errno 24] Too many open files |
单进程文件描述符默认 1024，万连接瞬间打爆 | ulimit -n 65535 + 使用连接池复用客户端 |
7 总结：遗产代码安全驾驶指南
- hbmqtt 0.9.6 仍能稳定服役 ，但不再修 Bug ；新项目请直接
pip install amqtt。 - 牢记"字节串、QoS、心跳"三大检查点，可避开 90% 的坑。
- 若需 MQTT 5.0、共享订阅等高级特性，转向 gmqtt 或 paho-mqtt v5。
把这篇 cheatsheet 贴在工位，下次 IoT 需求来袭，你能在 15 分钟内给出可扩展、可维护、不踩坑的异步 MQTT 方案。祝编码愉快，消息永不丢！
如果你觉得文章还不错，请大家 点赞、分享、留言 下，因为这将是我持续输出更多优质文章的最强动力！
