mm_mqtt_client 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# MQTT 客户端（mm_mqtt_client）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## 说明
+基于 `mqtt.js` 封装的独立 MQTT 客户端，提供连接、订阅、发布与 RPC 请求能力。模块不依赖全局变量与原型扩展，可通过 `Admin` 按作用域缓存实例。
+
+## 功能特点
+
+- 支持连接、重连、断开
+- 支持主题订阅、取消订阅与多回调
+- 支持发布消息与 JSON 消息发送
+- 支持 RPC 请求：`req` 回调方式、`reqAsync` Promise 方式
+- 支持响应主题模板 `{topic}`
+- 请求超时自动回收，超时后回调错误信息
+- 服务端可调用客户端注册在 `methods` 中的方法
+
+## 依赖
+
+- `mm_helper`
+- `mqtt`
+
+## 安装
+
+```bash
+npm install mm_mqtt_client
+```
+
+## 快速开始
+
+```javascript
+const { MqttClient } = require('mm_mqtt_client');
+
+const client = new MqttClient({
+  host: '127.0.0.1',
+  port: '8083',
+  protocol: 'ws',
+  client_id: 'service123',
+  username: 'admin',
+  password: 'asd123'
+});
+
+await client.run();
+
+// 订阅主题
+client.subscribe('topic/demo', (msg) => {
+  console.log('收到消息:', msg);
+});
+
+// 发布 JSON 消息
+client.send('topic/demo', { id: 1, method: 'test', params: {} });
+
+// RPC 请求（回调方式）
+client.req('topic/demo', 'getUser', { id: 1 }, (res, error) => {
+  if (error) {
+    console.error(error);
+    return;
+  }
+  console.log('响应:', res);
+});
+
+// RPC 请求（Promise 方式）
+const res = await client.reqAsync('topic/demo', 'getUser', { id: 1 });
+```
+
+## API
+
+### 类 `MqttClient`
+
+| 方法 | 说明 | 参数 | 返回值 |
+|---|---|---|---|
+| run | 连接 MQTT 服务器 | - | Promise |
+| init | 重置配置与连接状态 | config | void |
+| reconnect | 重连，超过重试次数后重新初始化 | - | void |
+| end | 断开连接 | - | void |
+| on | 监听底层客户端事件 | event_name, func | void |
+| subscribe | 订阅主题 | topic, func, options | Number（订阅标识） |
+| unsubscribe | 取消订阅 | topic, key | void |
+| publish | 发布消息 | topic, message, options | void |
+| send | 发送 JSON 消息 | topic, msg, options | void |
+| req | 发起 RPC 请求 | topic, method, params, func, options | void |
+| reqAsync | 发起 RPC 请求并等待响应 | topic, method, params, options | Promise |
+| receive | 处理收到的消息（请求响应/方法调用/普通消息） | topic, body | Promise |
+| message | 触发主题订阅回调 | topic, msg | void |
+| getResTopic | 按模板生成响应主题 | topic | String |
+| getOptions | 合并发布/订阅选项 | options, type | Object |
+| getMessageId | 生成请求消息 ID | client_id, method | String |
+
+### 导出
+
+| 导出 | 说明 | 参数 | 返回值 |
+|---|---|---|---|
+| MqttClient | MQTT 客户端类 | config | MqttClient |
+| admin | 管理器实例 | - | Admin |
+| mqttAdmin | 获取指定作用域的客户端实例 | scope, config | MqttClient |
+
+## 配置项
+
+| 配置 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| host | String | `127.0.0.1` | 主机地址 |
+| port | String | `8083` | 端口号 |
+| protocol | String | `ws` | 协议类型 |
+| client_id | String | `service123` | 客户端 ID |
+| username | String | `admin` | 用户名 |
+| password | String | `asd123` | 密码 |
+| clean | Boolean | `false` | 是否清除会话 |
+| subscribe_topic | Array | `[]` | 订阅主题列表 |
+| response_topic | String | `{topic}_ack` | 响应主题模板 |
+| publish | Object | `{ qos: 0, retain: false }` | 发布选项 |
+| subscribe | Object | `{ qos: 0 }` | 订阅选项 |
+| timeout | Number | `3000` | 请求超时时间（毫秒） |
+| retry | Number | `5` | 重试次数 |
+
+## 目录结构
+
+```text
+mm_mqtt_client/
+├── lib/
+│   └── mqtt_client.js   # MqttClient 实现
+├── index.js             # 模块入口
+├── test.js              # 自包含测试（不连接外部 broker）
+└── package.json
+```

package/index.js

@@ -0,0 +1,20 @@
+/**
+ * mm_mqtt_client 模块入口
+ * @description 提供独立的 MQTT 客户端，支持连接、订阅、发布与 RPC 请求
+ */
+const MqttClient = require('./lib/mqtt_client');
+const Admin = require('mm_corejs').Admin;
+
+const admin = new Admin();
+admin.setClass(MqttClient);
+
+module.exports = {
+  MqttClient,
+  admin,
+  mqttAdmin(scope, config) {
+    if (!scope) {
+      scope = 'os';
+    }
+    return admin.get(scope, config);
+  }
+};

package/lib/mqtt_client.js

@@ -0,0 +1,479 @@
+const MQTT = require('mqtt');
+require('mm_helper');
+
+/**
+ * MQTT客户端类
+ * @class
+ */
+class MqttClient {
+	/**
+	 * 构造函数
+	 * @param {Object} config 配置参数
+	 */
+	constructor(config) {
+		/**
+		 * 配置参数
+		 */
+		this.config = Object.assign({
+			/**
+			 * 主机地址
+			 */
+			host: "127.0.0.1",
+			/**
+			 * 端口号
+			 */
+			port: "8083",
+			/**
+			 * 协议类型
+			 */
+			protocol: "ws",
+			/**
+			 * 客户端ID
+			 */
+			client_id: "service123",
+			/**
+			 * 用户名
+			 */
+			username: "admin",
+			/**
+			 * 密码
+			 */
+			password: "asd123",
+			/**
+			 * 是否清除会话
+			 */
+			clean: false,
+			/**
+			 * 订阅主题
+			 */
+			subscribe_topic: [
+				// "{topic}",
+				// "{topic}_ack"
+			],
+			/**
+			 * 响应主题
+			 */
+			response_topic: "{topic}_ack",
+			/**
+			 * 发布选项
+			 */
+			publish: {
+				/**
+				 * QoS等级
+				 */
+				qos: 0,
+				/**
+				 * 是否保留消息
+				 */
+				retain: false
+			},
+			/**
+			 * 订阅选项
+			 */
+			subscribe: {
+				/**
+				 * QoS等级
+				 */
+				qos: 0
+			},
+			/**
+			 * 超时时间
+			 */
+			timeout: 3000,
+			/**
+			 * 重试次数
+			 */
+			retry: 5
+		}, config);
+
+		// mqtt客户端服务器
+		this.client = null;
+
+		/**
+		 * 消息队列 (ID => 消息对象)
+		 */
+		this._queue = {};
+
+		/**
+		 * 订阅集合 (主题 => 函数列表)
+		 */
+		this._subs = {};
+
+		/**
+		 * 方法集合
+		 */
+		var _this = this;
+		this.methods = {
+			/**
+			 * 提供给服务端查看开放的函数数量
+			 * @returns {Array} 方法名称列表
+			 */
+			getMethod: function () {
+				return Object.keys(_this.methods)
+			}
+		};
+		/**
+		 * 重试次数
+		 */
+		this._retry = 0;
+		/**
+		 * 是否正在连接
+		 */
+		this._connecting = false;
+		/**
+		 * 消息ID计数器
+		 */
+		this._key_num = 0;
+
+		this._logger = console;
+	}
+}
+
+/**
+ * 日志记录
+ * @param {String} level 日志级别 (e.g., 'info', 'warn', 'error')
+ * @param {String} message 日志消息
+ * @param {...*} args 可选参数
+ */
+MqttClient.prototype.log = function (level, message, ...args) {
+	this._logger[level](`[${this.constructor.name}] ${message}`, ...args);
+}
+
+/**
+ * 重新连接
+ */
+MqttClient.prototype.reconnect = function () {
+	/**
+	 * 重试次数增加
+	 */
+	this._retry += 1;
+	if (this._retry > this.config.retry) {
+		try {
+			this.client.end();
+			this.init();
+		} catch (error) {
+			this.log('error', "Reconnect failed:", error);
+		}
+	}
+}
+
+/**
+ * 初始化
+ * @param {Object} config 配置参数
+ */
+MqttClient.prototype.init = function (config) {
+	Object.assign(this.config, config);
+	this.client = {
+		connected: false,
+	};
+	this._retry = 0;
+	this._connecting = false;
+};
+
+/**
+ * 获取响应主题
+ * @param {String} topic 主题
+ * @returns {String} 响应主题
+ */
+MqttClient.prototype.getResTopic = function (topic) {
+	return this.config.response_topic.replace('{topic}', topic);
+}
+
+/**
+ * 获取MQTT选项
+ * @param {Object} options 选项参数
+ * @param {String} options.qos QoS等级
+ * @param {Boolean} options.retain 是否保留消息
+ * @param {String} type 选项类型 (publish 或 subscribe)
+ * @returns {Object} MQTT选项
+ */
+MqttClient.prototype.getOptions = function (options, type = 'publish') {
+	return Object.assign({
+		qos: this.config[type].qos,
+		retain: this.config[type].retain || false
+	}, options || {});
+}
+
+/**
+ * 运行MQTT
+ * @returns {Promise} 连接结果
+ */
+MqttClient.prototype.run = function () {
+	this._connecting = true;
+	var err;
+	try {
+		var config = {
+			clientId: this.config.client_id,
+			username: this.config.username,
+			password: this.config.password,
+			clean: this.config.clean,
+		}
+		this.client = MQTT.connect(config);
+		if (this.client.on) {
+			return new Promise((resolve, reject) => {
+				this.client.on('connect', (packet, err) => {
+					this._connecting = false;
+					if (err) {
+						resolve(null);
+						reject(err);
+					} else {
+						this.client.on('message', async (topic, message) => {
+							await this.receive(topic, message.toString());
+						});
+						resolve(packet);
+					}
+				});
+				this.client.on("reconnect", this.reconnect.bind(this));
+				this.client.on("error", (error) => {
+					this.log('error', "Connection failed", error);
+				});
+			});
+		}
+	} catch (error) {
+		this._connecting = false;
+		err = error;
+	}
+	return new Promise((resolve, reject) => {
+		resolve(null);
+		reject(err);
+	});
+};
+
+/**
+ * 监听事件
+ * @param {String} event_name 事件名称
+ * @param {Function} func 回调函数
+ */
+MqttClient.prototype.on = function (event_name, func) {
+	this.client.on(event_name, func);
+};
+
+/**
+ * 接收消息
+ * @param {String} topic 订阅板块
+ * @param {Object} msg 消息主体
+ */
+MqttClient.prototype.message = function (topic, msg) {
+	if (this._subs[topic]) {
+		var list = this._subs[topic];
+		try {
+			for (var key in list) {
+				list[key](msg);
+			}
+		} catch (err) {
+			this.log('error', "Error in message callback:", err);
+		}
+	}
+}
+
+/**
+ * 接收消息
+ * @param {String} topic 订阅板块
+ * @param {Object} body 消息主体
+ */
+MqttClient.prototype.receive = async function (topic, body) {
+	var json;
+	if (body && (body.indexOf('[') === 0) || body.indexOf('{') === 0) {
+		try {
+			json = JSON.parse(body);
+		} catch { }
+	}
+	if (json) {
+		var id = json.id;
+		if (json.result && id) {
+			var lt = this._queue;
+			var has = false;
+			for (var key in lt) {
+				var o = lt[key];
+				if (id === o.id) {
+					o.has_res = true;
+					o.func(json.result);
+					delete lt[key];
+					has = true;
+					break;
+				}
+			}
+			if (has) {
+				return;
+			}
+		} else if (json.method) {
+			var func;
+			var method = this.methods;
+			var arr = json.method.split('.');
+			for (var i = 0; i < arr.length; i++) {
+				var m = method[arr[i]];
+				if (m) {
+					method = m;
+				}
+			}
+			if (method && typeof (method) == 'function') {
+				func = method;
+			}
+			if (func) {
+				var ret = await func(json.params);
+				if (ret) {
+					var res = {};
+					if (id) {
+						res.id = id
+					}
+					res.result = ret;
+					this.send(this.getResTopic(topic), res);
+				}
+				return;
+			}
+		}
+		this.message(topic, json);
+		return
+	}
+	this.message(topic, body);
+};
+
+
+/**
+ * 订阅主题
+ * @param {String} topic - 主题名称
+ * @param {Function} func - 回调函数
+ * @param {Object} options - 订阅选项
+ * @param {Number} options.qos - QoS等级，默认值为0
+ * @returns {Number} 订阅标识
+ */
+MqttClient.prototype.subscribe = function (topic, func, options) {
+	if (typeof topic !== 'string') throw new TypeError('topic must be string');
+	if (func && typeof func !== 'function') throw new TypeError('func must be function');
+	this.client.subscribe(topic, this.getOptions(options, 'subscribe'));
+	if (func) {
+		if (!this._subs[topic]) {
+			this._subs[topic] = {};
+		}
+		var key = this._key_num + 1;
+		this._subs[topic][key] = func;
+		return key;
+	}
+}
+
+/**
+ * 取消订阅
+ * @param {String} topic - 主题名称
+ * @param {Number} key - 订阅标识
+ */
+MqttClient.prototype.unsubscribe = function (topic, key) {
+	if (typeof topic !== 'string') throw new TypeError('topic must be string');
+
+	this.client.unsubscribe(topic);
+	if (key) {
+		if (this._subs[topic]) {
+			delete this._subs[topic][key];
+		}
+	} else {
+		this._subs[topic] = {};
+	}
+}
+
+/**
+ * 断开连接
+ */
+MqttClient.prototype.end = function () {
+	this.client.end();
+};
+
+/**
+ * 发布消息
+ * @param {String} topic - 主题名称
+ * @param {Object} message - 消息内容
+ * @param {Object} options - 发布选项
+ * @param {Number} options.qos - QoS等级，默认值为0
+ * @param {Boolean} options.retain - 是否保留消息，默认值为false
+ */
+MqttClient.prototype.publish = function (topic, message, options) {
+	if (typeof topic !== 'string') throw new TypeError('topic must be string');
+	if (!this.client || !this.client.publish) {
+		this.log('warn', 'MQTT client not connected, message not sent:', topic);
+		return;
+	}
+
+	this.client.publish(topic, message, this.getOptions(options));
+};
+
+/**
+ * 发送消息
+ * @param {String} topic - 主题名称
+ * @param {Object} msg - 消息对象
+ * @param {Object} options - 发布选项
+ * @param {Number} options.qos - QoS等级，默认值为0
+ * @param {Boolean} options.retain - 是否保留消息，默认值为false
+ */
+MqttClient.prototype.send = function (topic, msg, options) {
+	if (typeof topic !== 'string') throw new TypeError('topic must be string');
+
+	this.publish(topic, JSON.stringify(msg), this.getOptions(options));
+};
+
+/**
+ * 获取消息ID
+ * @param {String} client_id - 客户端ID
+ * @param {String} method - 方法名
+ * @returns {String} 消息ID
+ */
+MqttClient.prototype.getMessageId = function (client_id, method) {
+	return client_id + "_" + method + "_" + Date.now();
+}
+
+/**
+ * 发送请求
+ * @param {String} topic - 主题名称
+ * @param {String} method - 方法名
+ * @param {Object} params - 参数
+ * @param {Function} func - 回调函数
+ * @param {Object} options - 请求选项
+ * @param {Number} options.qos - QoS等级，默认值为0
+ * @param {Boolean} options.retain - 是否保留消息，默认值为false
+ */
+MqttClient.prototype.req = function (topic, method, params, func, options) {
+	if (typeof topic !== 'string') throw new TypeError('topic must be string');
+	if (typeof method !== 'string') throw new TypeError('method must be string');
+	if (func && typeof func !== 'function') throw new TypeError('func must be function');
+	var id = this.getMessageId(this.config.client_id, method);
+	var msg = {
+		id,
+		method,
+		params
+	};
+
+	if (func) {
+		msg.func = func;
+		this._queue[id] = msg;
+		setTimeout(() => {
+			if (!msg.has_res) {
+				msg.func(null, "request timeout!");
+			}
+			for (var key in this._queue) {
+				var o = this._queue[key];
+				if (id === o.id) {
+					delete this._queue[key];
+					break;
+				}
+			}
+		}, this.config.timeout);
+	}
+	this.send(topic, msg, this.getOptions(options));
+};
+
+/**
+ * @description 发送请求并等待响应，超时时间为3秒。
+ * @param {String} topic - 主题名称
+ * @param {String} method 请求方法
+ * @param {Object} params 传递参数
+ * @param {Object} options 请求选项
+ * @returns {Object} 返回响应结果
+ */
+MqttClient.prototype.reqAsync = function (topic, method, params, options) {
+	var _this = this;
+	return new Promise((resolve, reject) => {
+		_this.req(topic, method, params, (res, error) => {
+			resolve(res);
+			reject(error);
+		}, this.getOptions(options));
+	});
+};
+
+module.exports = MqttClient;

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "mm_mqtt_client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "MQTT客户端模块，基于 mqtt.js 提供连接、订阅、发布与 RPC 请求能力（基于 mm_helper，无全局/原型扩展依赖）",
+  "main": "index.js",
+  "dependencies": {
+    "mm_helper": "^1.0.0",
+    "mqtt": "^5.15.2"
+  },
+  "scripts": {
+    "test": "node test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/qiuwenwu91/mm_mqtt_client.git"
+  },
+  "keywords": [
+    "mm_mod",
+    "mm_adapter",
+    "mm_mqtt_client",
+    "mqtt",
+    "client",
+    "Iot",
+    "app",
+    "game"
+  ],
+  "layer": "adapter",
+  "group": "in_adapter",
+  "author": "邱文武",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://gitee.com/qiuwenwu91/mm_mqtt_client/issues"
+  },
+  "homepage": "https://gitee.com/qiuwenwu91/mm_mqtt_client#readme"
+}

package/test.js

@@ -0,0 +1,56 @@
+/**
+ * mm_mqtt_client 模块自包含测试
+ * @description 仅验证 MqttClient 类的实例化与核心 API 存在性，不连接外部 MQTT broker
+ */
+const { MqttClient } = require('./index.js');
+
+let pass_count = 0;
+let fail_count = 0;
+
+/**
+ * 断言测试结果
+ * @param {string} name 测试名称
+ * @param {boolean} cond 断言条件
+ * @param {string} detail 失败详情
+ */
+function assert(name, cond, detail) {
+  if (cond) {
+    pass_count++;
+    console.log('  [通过] ' + name);
+  } else {
+    fail_count++;
+    console.log('  [失败] ' + name + (detail ? ' => ' + detail : ''));
+  }
+}
+
+/**
+ * 主测试流程
+ */
+function main() {
+  console.log('== mm_mqtt_client 模块功能测试 ==');
+  const client = new MqttClient({
+    host: '127.0.0.1',
+    port: '8083',
+    protocol: 'ws',
+    client_id: 'test123',
+    username: 'admin',
+    password: 'asd123',
+    clean: false
+  });
+
+  assert('MqttClient 是构造函数', typeof MqttClient === 'function');
+  assert('MqttClient 实例化成功', client instanceof MqttClient);
+  assert('存在 subscribe 方法', typeof client.subscribe === 'function');
+  assert('存在 publish 方法', typeof client.publish === 'function');
+  assert('存在 send 方法', typeof client.send === 'function');
+  assert('存在 req 方法', typeof client.req === 'function');
+  assert('存在 reqAsync 方法', typeof client.reqAsync === 'function');
+  assert('存在 methods 对象', !!client.methods);
+
+  console.log('\n== 测试结果: 通过 ' + pass_count + ', 失败 ' + fail_count + ' ==');
+  if (fail_count > 0) {
+    process.exitCode = 1;
+  }
+}
+
+main();