mm_redis 1.4.2 → 1.6.0

package/README.md

@@ -0,0 +1,379 @@
+# mm_redis
+
+mm_redis是一个高效的Redis客户端封装库，提供了全面的Redis功能支持，包括连接池管理、数据类型操作、错误处理和批量操作优化。
+
+## 版本信息
+
+- **当前版本**: 1.7.0
+- **更新日期**: 2024-10-07
+- **作者**: 邱文武
+
+## 功能特性
+
+- 完整的连接池管理，优化并发性能
+- 支持Pipeline批量操作，提升执行效率
+- 支持所有主要Redis数据类型：String、List、Hash等
+- 自动重连机制，使用指数退避策略
+- 全面的错误处理和日志记录
+- 自动JSON序列化/反序列化
+- 键前缀管理，支持多业务隔离
+- 自动连接管理，无需手动维护连接状态
+- 统一的事件系统，支持操作前后的事件监听
+
+## 安装
+
+```bash
+npm install mm_redis --save
+```
+
+## 基本配置
+
+```javascript
+const { Redis } = require('mm_redis');
+
+// 创建Redis实例
+const redis = new Redis('default');
+
+// 配置Redis连接
+redis.setConfig({
+    // 服务器地址
+    "host": "localhost",
+    // 端口号
+    "port": 6379,
+    // 密码
+    "password": "",
+    // 数据库
+    "database": 0,
+    // 前缀
+    "prefix": "app:",
+    // 连接超时时间(ms)
+    "connect_timeout": 10000,
+    // 重试次数
+    "retry_count": 3,
+    // 重试间隔(ms)
+    "retry_delay": 1000,
+    // 连接池配置
+    "pool": {
+        "max_clients": 10,      // 最大连接数
+        "min_idle": 2,          // 最小空闲连接数
+        "max_idle": 5,          // 最大空闲连接数
+        "idle_timeout": 30000   // 空闲超时时间(ms)
+    }
+});
+```
+
+## 使用示例
+
+### 基本操作
+
+```javascript
+// 连接Redis
+await redis.open();
+
+// 设置缓存
+await redis.set('user:1', { name: '张三', age: 25 }, 3600);
+
+// 获取缓存
+const user = await redis.get('user:1');
+$.log.debug('[Redis] 获取用户信息:', user);
+
+// 判断键是否存在
+const exists = await redis.has('user:1');
+
+// 删除缓存
+await redis.del('user:1');
+
+// 关闭连接
+await redis.close();
+```
+
+### 列表操作
+
+```javascript
+// 设置列表
+await redis.list_set('users', ['user1', 'user2', 'user3']);
+
+// 添加元素到列表
+await redis.list_push('users', 'user4');
+
+// 获取列表
+const users = await redis.list_get('users');
+$.log.debug('[Redis] 用户列表:', users);
+
+// 获取列表的部分元素
+const partialUsers = await redis.list_get('users', 0, 2);
+
+// 清空列表
+await redis.list_clear('users');
+```
+
+### Hash操作
+
+```javascript
+// 设置哈希字段
+await redis.hset('user:profile:1', 'name', '张三');
+await redis.hset('user:profile:1', 'age', 25);
+
+// 批量设置哈希字段
+await redis.hmset('user:profile:1', {
+    'email': 'zhangsan@example.com',
+    'phone': '13800138000'
+});
+
+// 获取哈希字段
+const name = await redis.hget('user:profile:1', 'name');
+
+// 获取哈希的所有字段和值
+const profile = await redis.hgetall('user:profile:1');
+$.log.debug('[Redis] 用户资料:', profile);
+
+// 获取哈希的所有字段名
+const fields = await redis.hkeys('user:profile:1');
+
+// 获取哈希的所有字段值
+const values = await redis.hvals('user:profile:1');
+
+// 判断哈希字段是否存在
+const hasEmail = await redis.hexists('user:profile:1', 'email');
+
+// 获取哈希字段数量
+const fieldCount = await redis.hlen('user:profile:1');
+
+// 删除哈希字段
+await redis.hdel('user:profile:1', ['email', 'phone']);
+```
+
+### 批量操作
+
+```javascript
+// 批量获取
+const data = await redis.mget(['user:1', 'user:2', 'user:3']);
+$.log.debug('[Redis] 批量获取结果:', data);
+
+// 批量设置
+await redis.mset({
+    'user:4': { name: '李四', age: 30 },
+    'user:5': { name: '王五', age: 35 }
+}, 3600);
+```
+
+### 使用Pipeline优化批量操作
+
+```javascript
+// 创建Pipeline
+const pipeline = redis.pipeline();
+
+// 添加多个命令
+pipeline.set('counter:1', 100);
+pipeline.ttl('counter:1', 3600);
+pipeline.hset('stats:today', 'visits', 500);
+pipeline.hset('stats:today', 'users', 100);
+
+// 执行所有命令
+const results = await pipeline.exec();
+$.log.debug('[Redis] Pipeline执行结果:', results);
+```
+
+### 发布订阅
+
+```javascript
+// 订阅频道
+await redis.subscribe('notifications', async (message) => {
+    $.log.debug('[Redis] 收到通知:', message);
+    // 处理接收到的消息
+});
+
+// 发布消息
+const receivedCount = await redis.publish('notifications', JSON.stringify({ 
+    type: 'info', 
+    content: '系统更新成功' 
+}));
+
+$.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文档
+
+### 连接管理
+
+- `setConfig(config)`: 设置Redis配置
+- `open()`: 连接Redis
+- `close()`: 关闭连接
+- `isConnected()`: 检查连接状态
+
+### 字符串操作
+
+- `set(key, value, seconds)`: 设置缓存
+- `get(key)`: 获取缓存
+- `has(key)`: 判断键是否存在
+- `del(key)`: 删除缓存
+- `add(key, value, seconds)`: 仅当键不存在时设置缓存
+- `ttl(key, seconds)`: 设置或获取过期时间
+- `addInt(key, num)`: 增加整数值
+- `addFloat(key, num)`: 增加浮点数值
+- `addStr(key, str)`: 追加字符串
+- `getrange(key, start, end)`: 获取字符串子串
+- `setrange(key, index, value)`: 设置字符串子串
+
+### 列表操作
+
+- `list_set(key, value, seconds)`: 设置列表
+- `list_push(key, value)`: 添加元素到列表
+- `list_get(key, start, end)`: 获取列表
+- `list_has(key, value)`: 判断列表中是否存在元素
+- `list_clear(key, value)`: 清空列表或重置列表
+
+### Hash操作
+
+- `hset(key, field, value)`: 设置哈希字段
+- `hmset(key, obj)`: 批量设置哈希字段
+- `hget(key, field)`: 获取哈希字段值
+- `hgetall(key)`: 获取哈希的所有字段和值
+- `hkeys(key)`: 获取哈希的所有字段名
+- `hvals(key)`: 获取哈希的所有字段值
+- `hdel(key, fields)`: 删除哈希字段
+- `hexists(key, field)`: 判断哈希字段是否存在
+- `hlen(key)`: 获取哈希字段数量
+
+### 批量操作
+
+- `mget(keys)`: 批量获取缓存
+- `mset(obj, seconds)`: 批量设置缓存
+- `pipeline()`: 创建Pipeline对象进行批量操作优化
+
+### 高级操作
+
+- `subscribe(channel, func)`: 订阅频道
+- `unsubscribe(channel)`: 取消订阅
+- `publish(channel, message)`: 发布消息
+- `clear(key)`: 清空缓存或当前数据库
+- `sort(key, options)`: 排序
+- `keys(pattern)`: 获取所有键名
+
+## 连接池管理
+
+本模块内置了高效的连接池管理，可自动处理连接的创建、回收和复用。连接池配置可在初始化时设置：
+
+```javascript
+{
+    "pool": {
+        "max_clients": 10,      // 最大连接数
+        "min_idle": 2,          // 最小空闲连接数
+        "max_idle": 5,          // 最大空闲连接数
+        "idle_timeout": 30000   // 空闲超时时间(ms)
+    }
+}
+```
+
+## 错误处理
+
+所有方法都包含了完善的错误处理机制，并提供详细的日志输出。在发生错误时，会自动记录错误信息，并在可能的情况下提供回退方案。
+
+## 最佳实践
+
+1. **使用连接池**: 对于高并发应用，连接池配置至关重要，合理设置最大连接数和空闲连接数
+2. **使用Pipeline**: 对于批量操作，使用Pipeline可显著提升性能
+3. **合理设置过期时间**: 避免Redis中数据无限增长
+4. **使用键前缀**: 通过键前缀进行业务隔离，避免键冲突
+5. **及时关闭连接**: 在应用结束时调用close()方法关闭所有连接
+6. **利用事件系统**: 使用事件系统进行日志记录、数据验证和操作拦截
+
+## 版本更新
+
+### 1.7.0 (2024-10-07)
+- 统一事件系统的属性命名规范
+- 更新所有方法的事件emit属性，使用统一的key、value、ttl、result等命名
+- 增加事件系统的详细文档
+- 修复部分方法中的拼写错误
+
+### 1.6.0 (2024-01-10)
+- 添加完整的连接池管理功能
+- 新增Pipeline批量操作优化
+- 增加Hash数据类型支持
+- 增强错误处理和日志记录
+- 优化重连机制，实现指数退避策略
+
+### 1.5.0
+- 优化连接管理
+- 完善错误处理
+- 提升代码稳定性
+
+### 1.0.0
+- 初始版本发布
+- 基础Redis功能支持