mm_redis 2.1.7 → 2.3.0

package/lib/tools/redis_lock/index.js

@@ -0,0 +1,210 @@
+/**
+ * Redis 分布式锁管理器
+ * 基于 Redis SET NX + TTL，使用 WATCH/MULTI/EXEC 实现原子释放和续期
+ * 防止锁过期后被误删：每次获取锁生成唯一 uuid，释放时验证 uuid 匹配
+ * 依赖: redis (v4+，与 mm_redis 共用同一个底层库)
+ */
+
+/**
+ * 生成唯一锁标识
+ * @returns {string} 唯一锁值
+ */
+function _genLockValue() {
+  return Date.now().toString(36) + '-' + Math.random().toString(36).substr(2, 9);
+}
+
+/**
+ * 获取 Redis 客户端（复用 mm_redis 连接池，不可用时自建独立连接）
+ * @param {object} opts 配置选项
+ * @returns {object} { client, release } 或 null
+ */
+async function _getClient(opts) {
+  var redis_admin = null;
+  try {
+    var { redisAdmin } = require('mm_redis');
+    if (redisAdmin) {
+      redis_admin = redisAdmin('os', opts);
+    }
+  } catch (e) {
+    // mm_redis 不可用时使用传入的 opts
+  }
+
+  // 优先复用 mm_redis 连接池，保证配置一致且不新建独立连接
+  if (redis_admin && typeof redis_admin._getConnection === 'function') {
+    var conn = await redis_admin._getConnection();
+    return {
+      client: conn,
+      release: function () {
+        try {
+          redis_admin._releaseConnection(conn);
+        } catch (e) {
+          void e;
+        }
+      }
+    };
+  }
+
+  // 回退: mm_redis 不可用，自建独立连接
+  var redis_mod = require('redis');
+  if (!redis_mod || !redis_mod.createClient) {
+    return null;
+  }
+  var createClient = redis_mod.createClient;
+  var client = createClient({
+    socket: {
+      host: opts.host || 'localhost',
+      port: opts.port || 6379,
+      connectTimeout: 5000
+    },
+    password: opts.password || '',
+    database: opts.db || 0
+  });
+  await client.connect();
+  return {
+    client: client,
+    release: function () {
+      try {
+        client.quit();
+      } catch (e) {
+        void e;
+      }
+    }
+  };
+}
+
+/**
+ * 获取分布式锁
+ * @param {object} client Redis 客户端
+ * @param {string} lock_key 锁键名
+ * @param {number} ttl 锁过期时间(秒)
+ * @returns {object} 获取结果
+ */
+async function _acquire(client, lock_key, ttl) {
+  var lock_value = _genLockValue();
+  var ttl_sec = ttl || 30;
+  var result = await client.set(lock_key, lock_value, { EX: ttl_sec, NX: true });
+  if (result === 'OK') {
+    return { acquired: true, lock_key: lock_key, lock_value: lock_value, ttl: ttl_sec };
+  }
+  return { acquired: false, lock_key: lock_key, msg: '锁已被占用' };
+}
+
+/**
+ * 释放分布式锁(WATCH/MULTI/EXEC 原子操作)
+ * 原理: WATCH 监控键 → 验证持有者 → MULTI 事务删除 → EXEC 提交
+ * 如果 EXEC 返回 null 说明 WATCH 期间键被修改(锁已被他人持有或过期后重新获取)，放弃删除
+ * @param {object} client Redis 客户端
+ * @param {string} lock_key 锁键名
+ * @param {string} lock_value 锁值(需与获取时一致)
+ * @returns {object} 释放结果
+ */
+async function _release(client, lock_key, lock_value) {
+  if (!lock_value) {
+    return { released: false, msg: '缺少 lock_value，无法安全释放锁' };
+  }
+  await client.watch(lock_key);
+  var current = await client.get(lock_key);
+  if (current !== lock_value) {
+    await client.unwatch();
+    return { released: false, lock_key: lock_key, msg: '锁已被他人持有或已过期' };
+  }
+  var exec_result = await client.multi().del(lock_key).exec();
+  if (exec_result === null) {
+    return { released: false, lock_key: lock_key, msg: '锁在释放过程中被修改，放弃删除' };
+  }
+  return { released: true, lock_key: lock_key };
+}
+
+/**
+ * 锁续期(WATCH/MULTI/EXEC 原子操作)
+ * 原理: 同释放，将 DEL 替换为 EXPIRE
+ * @param {object} client Redis 客户端
+ * @param {string} lock_key 锁键名
+ * @param {string} lock_value 锁值(需与获取时一致)
+ * @param {number} ttl 续期时间(秒)
+ * @returns {object} 续期结果
+ */
+async function _renew(client, lock_key, lock_value, ttl) {
+  if (!lock_value) {
+    return { renewed: false, msg: '缺少 lock_value，无法续期' };
+  }
+  var ttl_sec = ttl || 30;
+  await client.watch(lock_key);
+  var current = await client.get(lock_key);
+  if (current !== lock_value) {
+    await client.unwatch();
+    return { renewed: false, lock_key: lock_key, msg: '锁已被他人持有或已过期' };
+  }
+  var exec_result = await client.multi().expire(lock_key, ttl_sec).exec();
+  if (exec_result === null) {
+    return { renewed: false, lock_key: lock_key, msg: '锁在续期过程中被修改' };
+  }
+  return { renewed: true, lock_key: lock_key, ttl: ttl_sec };
+}
+
+/**
+ * 主函数
+ * @param {object} ctx 上下文
+ * @param {object} params 参数
+ * @returns {object} 执行结果
+ */
+async function main(params, ctx, options) {
+  var opts = (this && typeof this.getOptions === 'function') ? this.getOptions() : {};
+
+  var holder;
+  try {
+    holder = await _getClient(opts);
+  } catch (e) {
+    ctx.output = {
+      error: {
+        code: 'LOCK_CONNECT_FAIL',
+        message: 'Redis 连接失败: ' + e.message
+      }
+    };
+    return ctx.output;
+  }
+
+  if (!holder || !holder.client) {
+    ctx.output = {
+      error: {
+        code: 'LOCK_MISSING_DEP',
+        message: '分布式锁需要 redis 库，请手动执行: npm install redis'
+      }
+    };
+    return ctx.output;
+  }
+  var client = holder.client;
+
+  var action = params.action || '';
+  var lock_key = params.lock_key || '';
+
+  if (!lock_key) {
+    ctx.output = { error: { code: 'LOCK_NO_KEY', message: '锁键名 lock_key 不能为空' } };
+    await holder.release();
+    return ctx.output;
+  }
+
+  try {
+    switch (action) {
+      case 'acquire':
+        ctx.output = await _acquire(client, lock_key, params.ttl);
+        break;
+      case 'release':
+        ctx.output = await _release(client, lock_key, params.lock_value);
+        break;
+      case 'renew':
+        ctx.output = await _renew(client, lock_key, params.lock_value, params.ttl);
+        break;
+      default:
+        ctx.output = {
+          error: { code: 'LOCK_UNKNOWN_ACTION', message: '不支持的操作: ' + action + '，支持: acquire/release/renew' }
+        };
+    }
+  } finally {
+    await holder.release();
+  }
+
+  return ctx.output;
+}
+
+module.exports = { main };

package/package.json

@@ -1,41 +1,51 @@
 {
-    "name": "mm_redis",
-    "version": "2.1.7",
-    "description": "高效的Redis客户端封装库，提供连接池管理、数据类型操作、错误处理和批量操作优化",
-    "main": "index.js",
-    "scripts": {
-        "test": "node test.js",
-        "dev": "nodemon test.js"
-    },
-    "repository": {
-        "type": "git",
-        "url": "git+https://gitee.com/qiuwenwu91/mm_redis.git"
-    },
-    "keywords": [
-        "redis",
-        "cache",
-        "client",
-        "connection-pool",
-        "pipeline",
-        "hash",
-        "set",
-        "sorted-set",
-        "list",
-        "redis-client",
-        "mm_redis",
-        "nodejs"
-    ],
-    "author": "qww",
-    "license": "ISC",
-    "bugs": {
-        "url": "https://gitee.com/qiuwenwu91/mm_redis/issues"
-    },
-    "homepage": "https://www.npmjs.com/package/mm_redis",
-    "dependencies": {
-        "mm_expand": "^2.5.4",
-        "redis": "^6.2.1"
-    },
-    "engines": {
-        "node": ">=14.0.0"
-    }
+  "name": "mm_redis",
+  "version": "2.3.0",
+  "description": "高效的Redis客户端封装库，提供连接池管理、数据类型操作、错误处理和批量操作优化",
+  "main": "index.js",
+  "scripts": {
+    "test": "node test.js",
+    "dev": "nodemon test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/qiuwenwu91/mm_redis.git"
+  },
+  "keywords": [
+    "mm_mod",
+    "mm_adapter",
+    "mm_redis",
+    "redis",
+    "cache",
+    "client",
+    "connection-pool",
+    "pipeline",
+    "hash",
+    "set",
+    "sorted-set",
+    "list",
+    "redis-client",
+    "nodejs"
+  ],
+  "layer": "infrastructure",
+  "group": "cache",
+  "author": "qww",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://gitee.com/qiuwenwu91/mm_redis/issues"
+  },
+  "homepage": "https://www.npmjs.com/package/mm_redis",
+  "dependencies": {
+    "mm_admin": "^1.1.0",
+    "mm_eslint": "^1.0.0",
+    "mm_helper": "^1.0.0",
+    "mm_mod": "^1.0.1",
+    "redis": "^6.2.1"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "devDependencies": {
+    "mm_eslint": "^1.7.7"
+  }
 }

package/test.js

@@ -1,10 +1,23 @@
+// 独立运行时补充全局 $ 对象（mm_os 宿主环境已提供，npm 包测试需自备）
+if (!global.$) {
+  global.$ = {
+    log: {
+      debug: console.debug ? console.debug.bind(console) : console.log.bind(console),
+      info: console.info ? console.info.bind(console) : console.log.bind(console),
+      warn: console.warn ? console.warn.bind(console) : console.log.bind(console),
+      error: console.error ? console.error.bind(console) : console.log.bind(console),
+      success: console.log.bind(console)
+    }
+  };
+}
+
 const { redisAdmin } = require('./index.js');
 
 async function test() {
 	try {
 		var bl, num, arr = [];
 		var config = './config.json'.loadJson(__dirname);
-		var rs = redisAdmin('sys', config);
+		var rs = redisAdmin('os', config);
 		await rs.open();
 		
 		// 清理之前的测试数据

package/tool/push_queue/index.js

@@ -0,0 +1,7 @@
+'use strict';
+/**
+ * push_queue —— 工具契约适配层
+ * 业务实现归位于模块 lib/tools/push_queue/，本文件只把模块能力暴露给加载器。
+ * 其它模块可直接 require('mm_redis').tools.push_queue 复用。
+ */
+module.exports = require('../../lib/tools/push_queue');

package/tool/push_queue/tool.json

@@ -0,0 +1,56 @@
+{
+  "name": "push_queue",
+  "handler": "sender",
+  "title": "队列发信器",
+  "description": "将消息写入 Redis 消息队列（lPush）。适用场景：需要异步解耦、削峰填谷或与消费端对接时。工作流提示：queue_name 必填队列名称，data 填消息数据（会 JSON 序列化），返回 sent 与 message 确认入队结果。",
+  "type": "gateway",
+  "params": {
+    "type": "object",
+    "properties": {
+      "queue_name": {
+        "type": "string",
+        "description": "队列名称"
+      },
+      "data": {
+        "description": "消息数据"
+      }
+    },
+    "required": [
+      "queue_name",
+      "data"
+    ]
+  },
+  "returns": {
+    "description": "返回队列发信结果，正常时包含队列名称与消息数据，异常时包含错误码与错误信息",
+    "type": "object",
+    "properties": {
+      "sent": {
+        "type": "boolean",
+        "description": "是否入队成功"
+      },
+      "tip": {
+        "type": "string",
+        "description": "提示信息"
+      },
+      "message": {
+        "description": "消息数据"
+      },
+      "error": {
+        "type": "object",
+        "description": "错误信息，仅调用出错时返回",
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "错误码"
+          },
+          "message": {
+            "type": "string",
+            "description": "错误描述"
+          }
+        }
+      }
+    }
+  },
+  "options": {},
+  "group": "transport"
+}

package/tool/queue/index.js

@@ -0,0 +1,7 @@
+'use strict';
+/**
+ * queue —— 工具契约适配层
+ * 业务实现归位于模块 lib/tools/queue/，本文件只把模块能力暴露给加载器。
+ * 其它模块可直接 require('mm_redis').tools.queue 复用。
+ */
+module.exports = require('../../lib/tools/queue');

package/tool/queue/tool.json

@@ -0,0 +1,129 @@
+{
+  "name": "queue",
+  "handler": "manager",
+  "title": "消息队列管理器",
+  "description": "消息队列发布、消费、确认、重试、死信。适用场景：异步解耦、可靠传递。工作流提示：action 与 queue_name 必填，publish/delay 配 message，消费后 _raw 做 ack/retry，死信 dlq 配 dlq_action，结果在 obj/list、ID 在 message_id。",
+  "type": "data",
+  "params": {
+    "type": "object",
+    "properties": {
+      "action": {
+        "type": "string",
+        "description": "操作类型: publish/consume/batch_consume/ack/retry/dlq/delay/delay_poll/status",
+        "enum": [
+          "publish",
+          "consume",
+          "batch_consume",
+          "ack",
+          "retry",
+          "dlq",
+          "delay",
+          "delay_poll",
+          "status"
+        ]
+      },
+      "queue_name": {
+        "type": "string",
+        "description": "队列名称"
+      },
+      "message": {
+        "description": "消息内容(publish/delay时必填)"
+      },
+      "count": {
+        "type": "number",
+        "description": "批量消费数量(batch_consume时使用，默认10)"
+      },
+      "_raw": {
+        "type": "string",
+        "description": "消费时返回的原始消息字符串(ack/retry时必填)"
+      },
+      "max_retries": {
+        "type": "number",
+        "description": "最大重试次数(retry时使用，默认3)"
+      },
+      "dlq_action": {
+        "type": "string",
+        "description": "死信操作: view/replay/clear (dlq时使用)",
+        "enum": [
+          "view",
+          "replay",
+          "clear"
+        ]
+      },
+      "delay_seconds": {
+        "type": "number",
+        "description": "延迟秒数(delay时使用，必须>0)"
+      }
+    },
+    "required": [
+      "action",
+      "queue_name"
+    ]
+  },
+  "returns": {
+    "description": "管理操作结果，读操作返回 obj/list，写操作返回 msg/message_id/queue，异常时返回 error",
+    "type": "object",
+    "properties": {
+      "obj": {
+        "description": "消费的消息内容或状态"
+      },
+      "list": {
+        "type": "array",
+        "description": "批量消费的消息列表"
+      },
+      "msg": {
+        "type": "string",
+        "description": "操作结果描述"
+      },
+      "message_id": {
+        "type": "string",
+        "description": "消息ID"
+      },
+      "queue": {
+        "type": "string",
+        "description": "队列名称"
+      },
+      "count": {
+        "type": "number",
+        "description": "操作影响的消息数量"
+      },
+      "retry_count": {
+        "type": "number",
+        "description": "当前重试次数"
+      },
+      "delay_seconds": {
+        "type": "number",
+        "description": "延迟秒数"
+      },
+      "exec_at": {
+        "type": "string",
+        "description": "延迟消息执行时间"
+      }
+    }
+  },
+  "options": {
+    "driver": {
+      "type": "string",
+      "description": "队列驱动: redis",
+      "default": "redis"
+    },
+    "host": {
+      "type": "string",
+      "description": "队列服务主机",
+      "default": "localhost"
+    },
+    "port": {
+      "type": "number",
+      "description": "队列服务端口"
+    },
+    "password": {
+      "type": "string",
+      "description": "队列服务密码"
+    },
+    "db": {
+      "type": "number",
+      "description": "Redis 数据库编号"
+    }
+  },
+  "group": "system"
+}

package/tool/redis/index.js

@@ -0,0 +1,7 @@
+'use strict';
+/**
+ * redis —— 工具契约适配层
+ * 业务实现归位于模块 lib/tools/redis/，本文件只把模块能力暴露给加载器。
+ * 其它模块可直接 require('mm_redis').tools.redis 复用。
+ */
+module.exports = require('../../lib/tools/redis');

package/tool/redis/tool.json

@@ -0,0 +1,133 @@
+{
+  "name": "redis",
+  "handler": "manager",
+  "title": "Redis管理器",
+  "description": "管理 Redis 缓存，覆盖键值、哈希、列表、集合、有序集合、发布订阅。适用场景：缓存数据、计数器、分布式协作或消息订阅时。工作流提示：action 与 key 必填，字符串配 value/ttl，哈希配 field/body，集合/有序集合/pub/sub 有专属 action，返回随操作而定。",
+  "type": "data",
+  "params": {
+    "type": "object",
+    "properties": {
+      "action": {
+        "type": "string",
+        "description": "操作类型",
+        "enum": [
+          "get",
+          "set",
+          "del",
+          "has",
+          "exists",
+          "add",
+          "getset",
+          "expire",
+          "pexpire",
+          "persist",
+          "ttl",
+          "incr",
+          "decr",
+          "incrby",
+          "decrby",
+          "incrbyfloat",
+          "keys",
+          "clear",
+          "clearExpire",
+          "dbsize",
+          "flushdb",
+          "isConnected",
+          "mget",
+          "mset",
+          "msetObj",
+          "strlen",
+          "append",
+          "setrange",
+          "hget",
+          "hset",
+          "hgetall",
+          "hkeys",
+          "hvals",
+          "hlen",
+          "hdel",
+          "hmset",
+          "hmget",
+          "hexists",
+          "hsetObj",
+          "setForList",
+          "addForList",
+          "getForList",
+          "clearForList",
+          "hasForList",
+          "sadd",
+          "srem",
+          "sismember",
+          "smembers",
+          "scard",
+          "sinter",
+          "sunion",
+          "sdiff",
+          "zadd",
+          "zrem",
+          "zscore",
+          "zrank",
+          "zrevrank",
+          "zincrby",
+          "zcard",
+          "zcount",
+          "zrevrange",
+          "publish",
+          "unsubscribe"
+        ]
+      },
+      "key": {
+        "type": "string",
+        "description": "缓存键"
+      },
+      "value": {
+        "description": "缓存值/增量值/成员等"
+      },
+      "ttl": {
+        "type": "number",
+        "description": "过期时间(秒)",
+        "min": 0,
+        "max": 31536000
+      },
+      "field": {
+        "type": "string",
+        "description": "哈希字段名/有序集合成员名(哈希和有序集合操作)"
+      },
+      "body": {
+        "type": "object",
+        "description": "批量数据对象(hsetObj/msetObj 操作)"
+      }
+    },
+    "required": [
+      "action",
+      "key"
+    ]
+  },
+  "returns": {
+    "description": "管理操作结果，返回值类型根据操作而定",
+    "type": "object"
+  },
+  "options": {
+    "host": {
+      "type": "string",
+      "description": "Redis主机地址",
+      "default": "127.0.0.1"
+    },
+    "port": {
+      "type": "number",
+      "description": "Redis端口",
+      "default": 6379
+    },
+    "password": {
+      "type": "string",
+      "description": "Redis密码",
+      "default": "asd159357"
+    },
+    "db": {
+      "type": "number",
+      "description": "数据库编号",
+      "default": 0
+    }
+  },
+  "group": "storage"
+}

package/tool/redis_lock/index.js

@@ -0,0 +1,7 @@
+'use strict';
+/**
+ * redis_lock —— 工具契约适配层
+ * 业务实现归位于模块 lib/tools/redis_lock/，本文件只把模块能力暴露给加载器。
+ * 其它模块可直接 require('mm_redis').tools.redis_lock 复用。
+ */
+module.exports = require('../../lib/tools/redis_lock');