mini-mqtt-bus/README.md

MQTT client wrapper with event bus for WeChat Mini Programs

# 📦 mini-mqtt-bus

> ✅ 一款专为微信小程序设计的 MQTT + 事件总线组合模块，基于 `mqtt.js` 封装，支持自动重连、主题订阅分发等功能。

---

## 🚀 安装

```bash
# 使用 npm
npm install mini-mqtt-bus

# 使用 pnpm / yarn 也可
pnpm add mini-mqtt-bus
```

---

## 📦 目录结构建议（建议这样组织）

```bash
your-miniapp/
├── utils/
│   ├── mqttClient.ts      # 引入并使用 mini-mqtt-bus
│   └── eventBus.ts        # 可选：你也可以使用自己的事件总线
```

---

## 🧱 模块功能

- ✅ MQTT 连接/断开/重连监听
- ✅ 支持动态传入连接参数（灵活复用）
- ✅ 支持按主题分发消息事件
- ✅ 自动跳过模拟器连接
- ✅ 提供 `subscribe / publish / unsubscribe / disconnect` 等接口
- ✅ 内部使用 `wx.connectSocket` 实现小程序环境 MQTT 支持

---

## ✨ 快速使用示例（微信小程序）

### `app.ts` 中初始化

```ts
import { mqttClient } from "mini-mqtt-bus";
import eventBus from "mini-mqtt-bus/eventBus"; // 内置事件总线，也可以用自己的

mqttClient.init({
  protocol: "wxs",
  host: "your-mqtt-host.com",
  port: 8084,
  path: "/mqtt",
  clientId: "wechat_" + Math.random().toString(16).substr(2, 8),
  username: "your-username",
  password: "your-password",
  keepalive: 60,
  clean: true,
  reconnectPeriod: 2000,
});

// 连接成功后订阅主题
eventBus.on("mqtt:connected", () => {
  mqttClient.subscribe("1a");
});

// 订阅成功后发送消息
eventBus.on("mqtt:subscribed:1a", () => {
  mqttClient.publish("1a", "小程序发送的一条测试消息");
});

// 接收消息
eventBus.on("mqtt:message:1a", (payload) => {
  console.log("收到消息:", payload);
});
```

---

## 📡 事件列表

| 事件名 | 说明 |
|--------|------|
| `mqtt:connected` | 成功建立 MQTT 连接 |
| `mqtt:message:<topic>` | 收到某个主题的消息 |
| `mqtt:message` | 收到任意消息，包含 `{ topic, payload }` |
| `mqtt:subscribed:<topic>` | 成功订阅某个主题 |
| `mqtt:unsubscribed:<topic>` | 成功取消订阅某个主题 |
| `mqtt:reconnecting` | 正在尝试重连 |
| `mqtt:closed` | 连接关闭 |
| `mqtt:error` | 连接或操作异常 |
| `mqtt:disconnected` | 主动断开连接 |

---

## 🧩 API 文档

### `mqttClient.init(options: MqttOptions)`

初始化连接，接收 mqtt.js 支持的连接参数对象（详见 [mqtt.js connect options](https://github.com/mqttjs/MQTT.js#connect)）。

### `mqttClient.subscribe(topic: string)`

订阅主题，支持监听 `mqtt:subscribed:<topic>` 事件。

### `mqttClient.publish(topic: string, payload: string)`

发布消息到指定主题。

### `mqttClient.unsubscribe(topic: string)`

取消订阅指定主题。

### `mqttClient.disconnect()`

主动断开连接。


---

## 🛡️ 注意事项

- 模块依赖 `mqtt.min.js`（请确保使用兼容微信小程序的版本）
- 若自定义事件总线，可自行替换 `eventBus.ts`
- 需在小程序配置中声明相关域名和安全连接权限

---

## 📃 License

MIT © Kaze