mm_redis 1.5.0 → 1.7.0

package/README.md

@@ -4,8 +4,8 @@ mm_redis是一个高效的Redis客户端封装库，提供了全面的Redis功
 
 ## 版本信息
 
-- **当前版本**: 1.6.0
-- **更新日期**: 2024-01-10
+- **当前版本**: 1.7.0
+- **更新日期**: 2024-10-07
 - **作者**: 邱文武
 
 ## 功能特性
@@ -18,6 +18,7 @@ mm_redis是一个高效的Redis客户端封装库，提供了全面的Redis功
 - 自动JSON序列化/反序列化
 - 键前缀管理，支持多业务隔离
 - 自动连接管理，无需手动维护连接状态
+- 统一的事件系统，支持操作前后的事件监听
 
 ## 安装
 
@@ -194,6 +195,79 @@ $.log.debug(`[Redis] 消息已发布，${receivedCount}个客户端接收`);
 await redis.unsubscribe('notifications');
 ```
 
+### 事件系统
+
+mm_redis提供了完善的事件系统，可以监听各种操作的前后事件，用于日志记录、数据修改或操作拦截。
+
+```javascript
+// 监听设置操作前的事件
+redis.on('set_before', (data) => {
+    $.log.debug('[Redis] 设置缓存前:', data);
+    // 可以修改data中的值
+    // data.value = JSON.stringify(data.value);
+    // 可以通过设置data.cancel = true来取消操作
+});
+
+// 监听设置操作后的事件
+redis.on('set_after', (data) => {
+    $.log.debug('[Redis] 设置缓存后:', data);
+    // data包含key, value, ttl, success等信息
+});
+
+// 监听设置操作的错误事件
+redis.on('set_error', (data) => {
+    $.log.error('[Redis] 设置缓存错误:', data);
+    // data包含key, value, ttl, error等信息
+});
+```
+
+#### 事件属性规范
+
+所有事件都遵循统一的属性命名规范：
+
+1. **通用属性**：
+   - `key`: 操作的键名
+   - `value`: 操作的值（替代str、fields、obj等）
+   - `ttl`: 过期时间（替代seconds）
+   - `result`: 操作结果（替代length）
+   - `success`: 操作是否成功
+   - `cancel`: 是否取消操作（仅限前置事件）
+   - `error`: 错误信息（仅限错误事件）
+
+2. **特定属性**：
+   - `deleted`: 删除的键列表（用于del操作）
+   - `index`: 索引位置（用于setrange操作）
+   - `field`: 哈希字段名（用于hset操作）
+
+3. **事件命名模式**：
+   - 前置事件: `${methodName}_before`
+   - 后置事件: `${methodName}_after`
+   - 错误事件: `${methodName}_error`
+
+#### 支持的事件列表
+
+| 操作方法 | 前置事件 | 后置事件 | 错误事件 |
+|---------|---------|---------|--------|
+| set | set_before | set_after | set_error |
+| get | get_before | get_after | get_error |
+| del | del_before | del_after | del_error |
+| add | add_before | add_after | add_error |
+| addInt | addInt_before | addInt_after | addInt_error |
+| addFloat | addFloat_before | addFloat_after | addFloat_error |
+| addStr | addStr_before | addStr_after | addStr_error |
+| setrange | setrange_before | setrange_after | setrange_error |
+| clear | clear_before | clear_after | clear_error |
+| list_set | list_set_before | list_set_after | list_set_error |
+| list_push | list_push_before | list_push_after | list_push_error |
+| list_clear | list_clear_before | list_clear_after | list_clear_error |
+| mset | mset_before | mset_after | mset_error |
+| mget | mget_before | mget_after | mget_error |
+| hset | hset_before | hset_after | hset_error |
+| hmset | hmset_before | hmset_after | hmset_error |
+| hdel | hdel_before | hdel_after | hdel_error |
+| hget | hget_before | hget_after | hget_error |
+| hgetall | hgetall_before | hgetall_after | hgetall_error |
+
 ## API文档
 
 ### 连接管理
@@ -278,9 +352,16 @@ await redis.unsubscribe('notifications');
 3. **合理设置过期时间**: 避免Redis中数据无限增长
 4. **使用键前缀**: 通过键前缀进行业务隔离，避免键冲突
 5. **及时关闭连接**: 在应用结束时调用close()方法关闭所有连接
+6. **利用事件系统**: 使用事件系统进行日志记录、数据验证和操作拦截
 
 ## 版本更新
 
+### 1.7.0 (2024-10-07)
+- 统一事件系统的属性命名规范
+- 更新所有方法的事件emit属性，使用统一的key、value、ttl、result等命名
+- 增加事件系统的详细文档
+- 修复部分方法中的拼写错误
+
 ### 1.6.0 (2024-01-10)
 - 添加完整的连接池管理功能
 - 新增Pipeline批量操作优化

package/index.js

@@ -479,7 +479,7 @@ Redis.prototype.ttl = async function(key, seconds) {
 Redis.prototype.addInt = async function(key, num) {
 	try {
 		// 触发前置事件，允许修改或阻止操作
-		const beforeEventData = { key, num, cancel: false };
+		const beforeEventData = { key, value: num, cancel: false };
 		this.emit('addInt_before', beforeEventData);
 		
 		// 如果事件处理器标记为取消，则返回false
@@ -489,7 +489,7 @@ Redis.prototype.addInt = async function(key, num) {
 		}
 		
 		// 使用可能被修改的值
-		let { key: finalKey, num: finalNum } = beforeEventData;
+		let { key: finalKey, value: finalNum } = beforeEventData;
 		
 		const connection = await this._getConnection();
 		try {
@@ -534,14 +534,14 @@ Redis.prototype.addInt = async function(key, num) {
 			}
 			
 			// 触发后置事件
-			this.emit('addInt_after', { key: finalKey, num: finalNum, result });
+			this.emit('addInt_after', { key: finalKey, value: finalNum, result, success: true });
 			return result;
 		} finally {
 			this._recycleConnection(connection);
 		}
 	} catch (err) {
 		// 触发错误事件
-		this.emit('addInt_error', { key, num, error: err });
+		this.emit('addInt_error', { key, value: num, error: err });
 		$.log.error(`[Redis] 增加整数值失败 [${key}]:`, err);
 		throw err;
 	}
@@ -556,7 +556,7 @@ Redis.prototype.addInt = async function(key, num) {
 Redis.prototype.addFloat = async function(key, num) {
 	try {
 		// 触发前置事件，允许修改或阻止操作
-		const beforeEventData = { key, num, cancel: false };
+		const beforeEventData = { key, value: num, cancel: false };
 		this.emit('addFloat_before', beforeEventData);
 		
 		// 如果事件处理器标记为取消，则抛出错误
@@ -566,7 +566,7 @@ Redis.prototype.addFloat = async function(key, num) {
 		}
 		
 		// 使用可能被修改的值
-		let { key: finalKey, num: finalNum } = beforeEventData;
+		let { key: finalKey, value: finalNum } = beforeEventData;
 		let result;
 		
 		const connection = await this._getConnection();
@@ -595,7 +595,7 @@ Redis.prototype.addFloat = async function(key, num) {
 			}
 			
 			// 触发后置事件
-			this.emit('addFloat_after', { key: finalKey, num: finalNum, result });
+			this.emit('addFloat_after', { key: finalKey, value: finalNum, result, success: true });
 			return result;
 		} catch (err) {
 			// 如果出错，回退到先获取再设置的方式
@@ -609,14 +609,14 @@ Redis.prototype.addFloat = async function(key, num) {
 			await this.set(finalKey, n);
 			
 			// 触发后置事件
-			this.emit('addFloat_after', { key: finalKey, num: finalNum, result: n });
+			this.emit('addFloat_after', { key: finalKey, value: finalNum, result: n, success: true });
 			return n;
 		} finally {
 			this._recycleConnection(connection);
 		}
 	} catch (err) {
 		// 触发错误事件
-		this.emit('addFloat_error', { key, num, error: err });
+		this.emit('addFloat_error', { key, value: num, error: err });
 		$.log.error(`[Redis] 增加浮点数值失败 [${key}]:`, err);
 		throw err;
 	}
@@ -631,7 +631,7 @@ Redis.prototype.addFloat = async function(key, num) {
 Redis.prototype.addStr = async function(key, str) {
 	try {
 		// 触发前置事件，允许修改或阻止操作
-		const beforeEventData = { key, str, cancel: false };
+		const beforeEventData = { key, value: str, cancel: false };
 		this.emit('addStr_before', beforeEventData);
 		
 		// 如果事件处理器标记为取消，则返回0
@@ -641,7 +641,7 @@ Redis.prototype.addStr = async function(key, str) {
 		}
 		
 		// 使用可能被修改的值
-		let { key: finalKey, str: finalStr } = beforeEventData;
+		let { key: finalKey, value: finalStr } = beforeEventData;
 		let result;
 		
 		const connection = await this._getConnection();
@@ -666,7 +666,7 @@ Redis.prototype.addStr = async function(key, str) {
 			}
 			
 			// 触发后置事件
-			this.emit('addStr_after', { key: finalKey, str: finalStr, length: result });
+			this.emit('addStr_after', { key: finalKey, value: finalStr, result, success: true });
 			return result;
 		} catch (err) {
 			$.log.error('[Redis] 追加字符串失败:', err);
@@ -676,14 +676,14 @@ Redis.prototype.addStr = async function(key, str) {
 			await this.set(finalKey, value);
 			
 			// 触发后置事件
-			this.emit('addStr_after', { key: finalKey, str: finalStr, length: value.length });
+			this.emit('addStr_after', { key: finalKey, value: finalStr, result: value.length, success: true });
 			return value.length;
 		} finally {
 			this._recycleConnection(connection);
 		}
 	} catch (err) {
 		// 触发错误事件
-		this.emit('addStr_error', { key, str, error: err });
+		this.emit('addStr_error', { key, value: str, error: err });
 		$.log.error(`[Redis] 追加字符串失败 [${key}]:`, err);
 		return 0;
 	}
@@ -715,25 +715,25 @@ Redis.prototype.del = async function(key) {
 			if (Array.isArray(finalKey)) {
 				// 批量删除 - 分别删除每个键以确保正确处理
 				success = true;
-				const deletedKeys = [];
+				const deleted = [];
 				for (const k of finalKey) {
 					const prefixedKey = this.applyPrefix(k);
 					const result = await connection.del(prefixedKey);
 					if (result !== 1) {
 						success = false;
 					} else {
-						deletedKeys.push(k);
+						deleted.push(k);
 					}
 				}
 				// 触发后置事件
-				this.emit('del_after', { key: finalKey, success, deletedKeys });
+				this.emit('del_after', { key: finalKey, success, deleted });
 			} else {
 				// 单个删除
 				const prefixedKey = this.applyPrefix(finalKey);
 				const n = await connection.del(prefixedKey);
 				success = n === 1;
 				// 触发后置事件
-				this.emit('del_after', { key: finalKey, success, deletedKeys: success ? [finalKey] : [] });
+				this.emit('del_after', { key: finalKey, success, deleted: success ? [finalKey] : [] });
 			}
 			return success;
 		} finally {
@@ -757,7 +757,7 @@ Redis.prototype.del = async function(key) {
 Redis.prototype.set = async function(key, value, seconds) {
 	try {
 		// 触发前置事件，允许修改或阻止操作
-		const beforeEventData = { key, value, seconds, cancel: false };
+		const beforeEventData = { key, value, ttl: seconds, cancel: false };
 		this.emit('set_before', beforeEventData);
 		
 		// 如果事件处理器标记为取消，则返回false
@@ -767,7 +767,7 @@ Redis.prototype.set = async function(key, value, seconds) {
 		}
 		
 		// 使用可能被修改的值
-		let { key: finalKey, value: finalValue, seconds: finalSeconds } = beforeEventData;
+		let { key: finalKey, value: finalValue, ttl: finalSeconds } = beforeEventData;
 		
 		const connection = await this._getConnection();
 		try {
@@ -785,7 +785,7 @@ Redis.prototype.set = async function(key, value, seconds) {
 			}
 			
 			// 触发后置事件
-			this.emit('set_after', { key, value, seconds, success: true });
+			this.emit('set_after', { key, value, ttl: seconds, success: true });
 			return true;
 		} finally {
 			this._recycleConnection(connection);
@@ -793,7 +793,7 @@ Redis.prototype.set = async function(key, value, seconds) {
 	} catch (err) {
 		$.log.error(`[Redis] 设置缓存失败 [${key}]:`, err);
 		// 触发错误事件
-		this.emit('set_error', { key, value, seconds, error: err });
+		this.emit('set_error', { key, value, error: err });
 		return false;
 	}
 };
@@ -808,7 +808,7 @@ Redis.prototype.set = async function(key, value, seconds) {
 Redis.prototype.add = async function(key, value, seconds) {
 	try {
 		// 触发前置事件，允许修改或阻止操作
-		const beforeEventData = { key, value, seconds, cancel: false };
+		const beforeEventData = { key, value, ttl: seconds, cancel: false };
 		this.emit('add_before', beforeEventData);
 		
 		// 如果事件处理器标记为取消，则返回false
@@ -818,7 +818,7 @@ Redis.prototype.add = async function(key, value, seconds) {
 		}
 		
 		// 使用可能被修改的值
-		let { key: finalKey, value: finalValue, seconds: finalSeconds } = beforeEventData;
+		let { key: finalKey, value: finalValue, ttl: finalSeconds } = beforeEventData;
 		
 		const connection = await this._getConnection();
 		try {
@@ -832,7 +832,7 @@ Redis.prototype.add = async function(key, value, seconds) {
 			const success = result === "OK";
 			
 			// 触发后置事件
-			this.emit('add_after', { key, value, seconds, success });
+			this.emit('add_after', { key: finalKey, value: finalValue, ttl: finalSeconds, success });
 			return success;
 		} finally {
 			this._recycleConnection(connection);
@@ -840,7 +840,7 @@ Redis.prototype.add = async function(key, value, seconds) {
 	} catch (err) {
 		$.log.error(`[Redis] 添加缓存失败 [${key}]:`, err);
 		// 触发错误事件
-		this.emit('add_error', { key, value, seconds, error: err });
+		this.emit('add_error', { key, value, ttl: seconds, error: err });
 		return false;
 	}
 };
@@ -988,7 +988,7 @@ Redis.prototype.setrange = async function(key, index, value) {
 			}
 			
 			// 触发后置事件
-			this.emit('setrange_after', { key: finalKey, index: finalIndex, value: finalValue, length: result, success: true });
+			this.emit('setrange_after', { key: finalKey, index: finalIndex, value: finalValue, result, success: true });
 			return result;
 		} catch (err) {
 			$.log.error('[Redis] 设置字符串范围失败:', err);
@@ -1002,7 +1002,7 @@ Redis.prototype.setrange = async function(key, index, value) {
 			await this.set(finalKey, str);
 			
 			// 触发后置事件
-			this.emit('setrange_after', { key: finalKey, index: finalIndex, value: finalValue, length: str.length, success: true });
+			this.emit('setrange_after', { key: finalKey, index: finalIndex, value: finalValue, result: str.length, success: true });
 			return str.length;
 		} finally {
 			this._recycleConnection(connection);
@@ -1160,7 +1160,7 @@ Redis.prototype.keys = async function(pattern = '*') {
 Redis.prototype.list_set = async function(key, value, seconds) {
 	try {
 		// 触发前置事件，允许修改或阻止操作
-		const beforeEventData = { key, value, seconds, cancel: false };
+		const beforeEventData = { key, value, ttl: seconds, cancel: false };
 		this.emit('list_set_before', beforeEventData);
 		
 		// 如果事件处理器标记为取消，则返回0
@@ -1170,7 +1170,7 @@ Redis.prototype.list_set = async function(key, value, seconds) {
 		}
 		
 		// 使用可能被修改的值
-		let { key: finalKey, value: finalValue, seconds: finalSeconds } = beforeEventData;
+		let { key: finalKey, value: finalValue, ttl: finalSeconds } = beforeEventData;
 		let len = 0;
 		
 		const connection = await this._getConnection();
@@ -1218,14 +1218,14 @@ Redis.prototype.list_set = async function(key, value, seconds) {
 			}
 			
 			// 触发后置事件
-			this.emit('list_set_after', { key: finalKey, value: finalValue, seconds: finalSeconds, length: len, success: len > 0 });
+			this.emit('list_set_after', { key: finalKey, value: finalValue, ttl: finalSeconds, result: len, success: len > 0 });
 			return len;
 		} finally {
 			this._recycleConnection(connection);
 		}
 	} catch (err) {
 		// 触发错误事件
-		this.emit('list_set_error', { key, value, seconds, error: err });
+		this.emit('list_set_error', { key, value, error: err });
 		$.log.error(`[Redis] 设置列表失败 [${key}]:`, err);
 		return 0;
 	}
@@ -1283,7 +1283,7 @@ Redis.prototype.list_push = async function(key, value) {
 			}
 			
 			// 触发后置事件
-			this.emit('list_push_after', { key: finalKey, value: finalValue, length: len, success });
+			this.emit('list_push_after', { key: finalKey, value: finalValue, result: len, success });
 			return len;
 		} finally {
 			this._recycleConnection(connection);
@@ -1512,7 +1512,7 @@ Redis.prototype.mget = async function(keys) {
 Redis.prototype.mset = async function(obj, seconds) {
 	try {
 		// 触发前置事件，允许修改或阻止操作
-		const beforeEventData = { data: obj, ttl: seconds, cancel: false };
+		const beforeEventData = { value: obj, ttl: seconds, cancel: false };
 		this.emit('mset_before', beforeEventData);
 		
 		// 如果事件处理器标记为取消，则返回false
@@ -1522,11 +1522,11 @@ Redis.prototype.mset = async function(obj, seconds) {
 		}
 		
 		// 使用可能被修改的值
-		let { data: finalData, ttl: finalSeconds } = beforeEventData;
+		let { value: finalData, ttl: finalSeconds } = beforeEventData;
 		
 		// 检查最终数据是否有效
 		if (!finalData || typeof finalData !== 'object') {
-			throw new Error('事件处理后的data必须是非空对象');
+			throw new Error('事件处理后的value必须是非空对象');
 		}
 		
 		// 使用Pipeline优化批量操作
@@ -1545,11 +1545,11 @@ Redis.prototype.mset = async function(obj, seconds) {
 		await pipeline.exec();
 		
 		// 触发后置事件
-		this.emit('mset_after', { data: finalData, ttl: finalSeconds, success: true });
+		this.emit('mset_after', { value: finalData, ttl: finalSeconds, success: true });
 		return true;
 	} catch (err) {
 		// 触发错误事件
-		this.emit('mset_error', { data: obj, ttl: seconds, error: err });
+		this.emit('mset_error', { value: obj, ttl: seconds, error: err });
 		
 		// 如果Pipeline失败，回退到原实现
 		$.log.warn('[Redis] 使用Pipeline批量设置失败，使用回退方案:', err);
@@ -1571,11 +1571,11 @@ Redis.prototype.mset = async function(obj, seconds) {
 			}
 			
 			// 触发后置事件（使用原始数据，因为前置数据修改处理已失败）
-			this.emit('mset_after', { data: obj, ttl: seconds, success: true });
+			this.emit('mset_after', { value: obj, ttl: seconds, success: true });
 			return true;
 		} catch (fallbackErr) {
 			// 触发错误事件
-			this.emit('mset_error', { data: obj, ttl: seconds, error: fallbackErr });
+			this.emit('mset_error', { value: obj, ttl: seconds, error: fallbackErr });
 			$.log.error('[Redis] 回退方案批量设置也失败:', fallbackErr);
 			return false;
 		} finally {
@@ -1666,7 +1666,7 @@ Redis.prototype.hvals = async function(key) {
 Redis.prototype.hdel = async function(key, fields) {
 	try {
 		// 触发前置事件，允许修改或阻止操作
-		const beforeEventData = { key, fields, cancel: false };
+		const beforeEventData = { key, value: fields, cancel: false };
 		this.emit('hdel_before', beforeEventData);
 		
 		// 如果事件处理器标记为取消，则返回false
@@ -1676,7 +1676,7 @@ Redis.prototype.hdel = async function(key, fields) {
 		}
 		
 		// 使用可能被修改的值
-		let { key: finalKey, fields: finalFields } = beforeEventData;
+		let { key: finalKey, value: finalFields } = beforeEventData;
 		let success = true;
 		
 		const connection = await this._getConnection();
@@ -1697,14 +1697,14 @@ Redis.prototype.hdel = async function(key, fields) {
 			}
 			
 			// 触发后置事件
-			this.emit('hdel_after', { key: finalKey, fields: finalFields, success });
+			this.emit('hdel_after', { key: finalKey, value: finalFields, success });
 			return success;
 		} finally {
 			this._recycleConnection(connection);
 		}
 	} catch (err) {
 		// 触发错误事件
-		this.emit('hdel_error', { key, fields, error: err });
+		this.emit('hdel_error', { key, value: fields, error: err });
 		$.log.error(`[Redis] 删除哈希字段失败 [${key}]:`, err);
 		return false;
 	}
@@ -2146,7 +2146,7 @@ Redis.prototype.hset = async function(key, field, value) {
             await connection.execute('hset', finalKey, finalField, finalValue);
             
             // 触发后置事件
-            this.emit('hset_after', { key, field, value, success: true });
+            this.emit('hset_after', { key: finalKey, field: finalField, value: finalValue, success: true });
             return true;
         } finally {
             this._recycleConnection(connection);
@@ -2203,7 +2203,7 @@ Redis.prototype.hget = async function(key, field) {
 Redis.prototype.hmset = async function(key, obj) {
     try {
         // 触发前置事件，允许修改或阻止操作
-        const beforeEventData = { key, obj, cancel: false };
+        const beforeEventData = { key, value: obj, cancel: false };
         this.emit('hmset_before', beforeEventData);
         
         // 如果事件处理器标记为取消，则返回false
@@ -2213,7 +2213,7 @@ Redis.prototype.hmset = async function(key, obj) {
         }
         
         // 使用可能被修改的值
-        let { key: finalKey, obj: finalObj } = beforeEventData;
+        let { key: finalKey, value: finalObj } = beforeEventData;
         
         const connection = await this._getConnection();
         try {
@@ -2232,15 +2232,15 @@ Redis.prototype.hmset = async function(key, obj) {
             }
             
             // 触发后置事件
-            this.emit('hmset_after', { key, obj, success: true });
+            this.emit('hmset_after', { key: finalKey, value: finalObj, success: true });
             return true;
         } finally {
-            this._releaseConnection(connection);
+            this._recycleConnection(connection);
         }
     } catch (err) {
         $.log.error(`[Redis] 批量设置哈希字段失败 [${key}]:`, err);
         // 触发错误事件
-        this.emit('hmset_error', { key, obj, error: err });
+        this.emit('hmset_error', { key, value: obj, error: err });
         return false;
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mm_redis",
-    "version": "1.5.0",
+    "version": "1.7.0",
     "description": "这是超级美眉redis缓存帮助类",
     "main": "index.js",
     "scripts": {