mm_redis

一个高效的Redis客户端封装库，提供完整的连接池管理、数据类型操作和批量操作优化

版本信息

• 最新版本: 2.0.0
• 更新日期: 2025-10-20
• 作者: qww
• NPM: https://www.npmjs.com/package/mm_redis
• GitHub: https://gitee.com/qiuwenwu91/mm_redis
• Node.js: >= 14.0.0

功能特性

🚀 核心功能

• 完整的连接池管理：优化并发性能，支持连接复用和自动回收
• Pipeline批量操作：支持Redis Pipeline机制，大幅提升批量操作效率
• 全面的数据类型支持：覆盖String、List、Hash、Set、Sorted Set等所有主要Redis数据类型

🔧 高级特性

• 智能连接管理：自动重连机制，使用指数退避策略，确保连接稳定可靠
• 健壮的错误处理：全面的错误处理机制和详细的日志记录，便于问题排查
• 便捷的数据序列化：自动JSON序列化/反序列化，无需手动转换数据格式
• 键空间隔离：支持键前缀管理，实现多业务场景下的数据隔离
• 灵活的事件系统：统一的事件机制，支持操作前后的事件监听和拦截
• 丰富的数值操作：支持原子性的数值增减操作，适用于计数器等场景

安装

npm

npm install mm_redis

yarn

yarn add mm_redis

pnpm

pnpm add mm_redis

快速开始

const { Redis } = require('mm_redis');

// 创建Redis实例
const redis = new Redis({
    host: 'localhost',
    port: 6379,
    password: 'your_password',
    db: 0
});

// 连接Redis
await redis.connect();

// 设置缓存
await redis.set('user:1', { name: '张三', age: 25 });

// 获取缓存
const user = await redis.get('user:1');
console.log(user); // { name: '张三', age: 25 }

// 错误处理
try {
    await redis.set('key', 'value');
} catch (err) {
    console.error('Redis操作失败:', err);
}

配置引入方式

mm_redis支持多种配置引入方式，满足不同场景的需求：

1. 对象配置（推荐）

const { Redis } = require('mm_redis');

// 直接传入配置对象
const redis = new Redis({
    host: 'localhost',
    port: 6379,
    password: 'your_password',
    db: 0,
    key_prefix: 'app:',
    max_clients: 10,
    connect_timeout: 5000
});

2. 文件配置

// config/redis.json
{
    "host": "localhost",
    "port": 6379,
    "password": "your_password",
    "db": 0,
    "key_prefix": "app:",
    "max_clients": 10,
    "connect_timeout": 5000
}

// 使用配置
const { Redis } = require('mm_redis');
const config = require('./config/redis.json');
const redis = new Redis(config);

3. 环境变量配置

// 环境变量
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_password
REDIS_DB=0
REDIS_KEY_PREFIX=app:
REDIS_MAX_CLIENTS=10
REDIS_CONNECT_TIMEOUT=5000

// 使用环境变量
const { Redis } = require('mm_redis');
const redis = new Redis({
    host: process.env.REDIS_HOST,
    port: parseInt(process.env.REDIS_PORT),
    password: process.env.REDIS_PASSWORD,
    db: parseInt(process.env.REDIS_DB),
    key_prefix: process.env.REDIS_KEY_PREFIX,
    max_clients: parseInt(process.env.REDIS_MAX_CLIENTS),
    connect_timeout: parseInt(process.env.REDIS_CONNECT_TIMEOUT)
});

变更日志

v2.0.0 (2025-10-14)

• 移除list_push方法，统一使用addForList方法进行列表添加操作
• 更新文档，将所有list_push引用替换为addForList
• 更新文档中的API列表和使用示例

v1.9.8 (2024-12-22)

• 更新文档，完善npm发布所需内容
• 添加GitHub仓库链接到文档
• 优化功能特性描述，增强文档可读性
• 添加Node.js版本要求说明

v1.9.5 (2024-12-21)

• 修复hmset和hgetall方法的兼容性问题，确保与Redis客户端v5兼容
• 移除已废弃的hexists、hkeys和hvals方法，优化API设计
• 优化mget和mset方法的实现，确保与Redis v5 API完全兼容
• 更新测试脚本，移除对已废弃方法的调用
• 更新兼容性表格，确保文档与实际API一致
• 修复原生Redis API调用中的错误，提升代码稳定性
• 优化连接池管理，修复潜在的内存泄漏问题

v1.9.4 (2024-12-20)

• 优化了配置引入方式，支持对象配置和文件路径配置两种方式
• 改进了setConfig方法的实现，使用Object.assign替代原来的合并方式
• 修复了连接池相关的警告信息
• 增强了错误处理机制

v1.9.0 (2024-11-20)

• 初始版本发布
• 支持完整的连接池管理
• 实现Pipeline批量操作
• 支持所有主要Redis数据类型操作

使用示例

// 连接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();

列表操作

// 设置列表
await redis.setForList('users', ['user1', 'user2', 'user3']);

// 添加元素到列表
await redis.addForList('users', 'user4');

// 获取列表
const users = await redis.getForList('users');
$.log.debug('[Redis] 用户列表:', users);

// 获取列表的部分元素
const partialUsers = await redis.getForList('users', 0, 2);

// 清空列表
await redis.clearForList('users');

Hash操作

// 设置哈希字段
await redis.hset('user:profile:1', 'name', '张三');
await redis.hset('user:profile:1', 'age', 25);

// 批量设置哈希字段
await redis.hmset('user:profile:1', {
    'email': '[email protected]',
    'phone': '13800138000'
});

// 获取哈希字段
const name = await redis.hget('user:profile:1', 'name');

// 获取哈希的所有字段和值
const profile = await redis.hgetall('user:profile:1');
$.log.debug('[Redis] 用户资料:', profile);

// 获取哈希字段数量
const fieldCount = await redis.hlen('user:profile:1');

// 删除哈希字段
await redis.hdel('user:profile:1', ['email', 'phone']);

批量操作

// 批量获取
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优化批量操作

// 创建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);

发布订阅

// 订阅频道
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提供了完善的事件系统，可以监听各种操作的前后事件，用于日志记录、数据修改或操作拦截。

// 监听设置操作前的事件
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 | | setForList | setForList_before | setForList_after | setForList_error | | addForList | addForList_before | addForList_after | addForList_error | | clearForList | clearForList_before | clearForList_after | clearForList_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 | | incr | incr_before | incr_after | incr_error | | decr | decr_before | decr_after | decr_error | | incrby | incrby_before | incrby_after | incrby_error | | decrby | decrby_before | decrby_after | decrby_error | | expire | expire_before | expire_after | expire_error | | sadd | sadd_before | sadd_after | sadd_error | | srem | srem_before | srem_after | srem_error | | zadd | zadd_before | zadd_after | zadd_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): 设置字符串子串

列表操作

• setForList(key, value, seconds): 设置列表
• addForList(key, value): 添加元素到列表
• getForList(key, start, end): 获取列表
• hasForList(key, value): 判断列表中是否存在元素
• clearForList(key, value): 清空列表或重置列表

Hash操作

• hset(key, field, value): 设置哈希字段
• hmset(key, obj): 批量设置哈希字段
• hget(key, field): 获取哈希字段值
• hgetall(key): 获取哈希的所有字段和值
• hdel(key, fields): 删除哈希字段
• hlen(key): 获取哈希字段数量

批量操作

• mget(keys): 批量获取缓存
• mset(obj, seconds): 批量设置缓存
• pipeline(): 创建Pipeline对象进行批量操作优化

高级操作

• subscribe(channel, func): 订阅频道
• unsubscribe(channel): 取消订阅
• publish(channel, message): 发布消息
• clear(key): 清空缓存或当前数据库
• sort(key, options): 排序
• keys(pattern): 获取所有键名

集合(Set)操作

• sadd(key, members): 添加成员到集合
• srem(key, members): 从集合中移除成员
• sismember(key, member): 检查成员是否在集合中
• smembers(key): 获取集合中的所有成员
• scard(key): 获取集合中的成员数量
• sinter(keys): 获取多个集合的交集
• sunion(keys): 获取多个集合的并集
• sdiff(keys): 获取多个集合的差集

有序集合(Sorted Set)操作

• zadd(key, score, member): 添加成员到有序集合
• zrem(key, members): 从有序集合中移除成员
• zscore(key, member): 获取有序集合中成员的分数
• zrank(key, member): 获取有序集合中成员的排名
• zrange(key, start, stop, withScores): 获取有序集合中指定范围的成员
• zcard(key): 获取有序集合中的成员数量
• zincrby(key, increment, member): 增加有序集合中成员的分数

数值操作

• incr(key): 将键的值增加1
• decr(key): 将键的值减少1
• incrby(key, increment): 将键的值增加指定的整数
• decrby(key, decrement): 将键的值减少指定的整数
• expire(key, seconds): 设置键的过期时间

连接池管理

本模块内置了高效的连接池管理，可自动处理连接的创建、回收和复用。连接池配置可在初始化时设置：

{
    "pool": {
        "max_clients": 10,      // 最大连接数
        "min_idle": 2,          // 最小空闲连接数
        "max_idle": 5,          // 最大空闲连接数
        "idle_timeout": 30000   // 空闲超时时间(ms)
    }
}

错误处理

所有方法都包含了完善的错误处理机制，并提供详细的日志输出。在发生错误时，会自动记录错误信息，并在可能的情况下提供回退方案。

最佳实践

1. 使用连接池: 对于高并发应用，连接池配置至关重要，合理设置最大连接数和空闲连接数
2. 使用Pipeline: 对于批量操作，使用Pipeline可显著提升性能
3. 合理设置过期时间: 避免Redis中数据无限增长
4. 使用键前缀: 通过键前缀进行业务隔离，避免键冲突
5. 及时关闭连接: 在应用结束时调用close()方法关闭所有连接
6. 利用事件系统: 使用事件系统进行日志记录、数据验证和操作拦截

版本更新

2.0.0 (2025-10-14)

• 移除list_push方法，统一使用addForList方法进行列表添加操作
• 更新文档，将所有list_push引用替换为addForList
• 更新文档中的API列表和使用示例
• 优化连接池配置管理，统一配置到this.config.pool中
• 新增连接池配置参数：min_idle、max_idle、idle_timeout

贡献指南

我们欢迎社区贡献！如果你有兴趣为mm_redis项目做出贡献，请遵循以下步骤：

1. Fork本仓库
2. 创建你的功能分支 (git checkout -b feature/amazing-feature)
3. 提交你的变更 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开一个Pull Request

请确保你的代码遵循项目的编码规范，并通过所有测试。

许可证

本项目采用ISC许可证 - 查看 LICENSE 文件了解详情

问题反馈

如果您在使用过程中遇到任何问题或有任何建议，请通过以下方式反馈：

• GitHub Issues: https://gitee.com/qiuwenwu91/mm_redis/issues
• NPM: https://www.npmjs.com/package/mm_redis

鸣谢

感谢所有为本项目做出贡献的开发者和用户！

相关链接

• Redis官方文档: https://redis.io/documentation
• Node Redis客户端: https://github.com/redis/node-redis