mm_mongodb 1.4.5 → 1.4.6

package/README.md

@@ -1,19 +1,19 @@
 # mm_mongodb
 
-MongoDB数据库操作模块，提供了简洁易用的API、缓存功能以及完整的Redis兼容接口。
+MongoDB数据库操作模块，提供了简洁易用的API、缓存功能以及**完整的Redis兼容接口**。
 
 ## 功能特点
 
-- 支持MongoDB连接池管理
-- 自动连接和重连机制
-- 事务支持
-- 索引管理
-- 缓存功能
-- **Redis兼容API**：支持Redis风格的键值操作、列表、集合、哈希等数据类型
-- 环境变量配置支持
-- 完善的错误处理和重试机制
-- 查询注入防护
-- 事件系统：支持监听关键操作的事件
+- ✅ 支持MongoDB连接池管理
+- ✅ 自动连接和重连机制
+- ✅ 事务支持
+- ✅ 索引管理
+- ✅ 缓存功能
+- ✅ **完整的Redis兼容API**：支持Redis风格的键值操作、列表、集合、有序集合、哈希等数据类型
+- ✅ 环境变量配置支持
+- ✅ 完善的错误处理和重试机制
+- ✅ 查询注入防护
+- ✅ 事件系统：支持监听关键操作的事件
 
 ## 安装
 
@@ -140,254 +140,195 @@ await db.createIndex('users', { name: 1 }, { unique: true });
 await db.createTTLIndex('logs', { createdAt: 1 }, 3600); // 3600秒后过期
 ```
 
-### 缓存使用
+## Redis兼容API使用指南
+
+mm_mongodb提供了**完整的Redis兼容API**，使您可以使用熟悉的Redis命令与MongoDB进行交互。这对于从Redis迁移到MongoDB或在两者间切换使用非常有用。
 
-#### 基本缓存操作
+### 快速开始
 
 ```javascript
 const { mongodb_cache_admin } = require('mm_mongodb');
 
-// 获取缓存实例
+// 获取Redis兼容的缓存实例
 const cache = mongodb_cache_admin('default');
 
-// 连接数据库
+// 连接数据库（重要：必须先连接）
 await cache.open();
 
-// 设置缓存（10秒过期）
-await cache.set('user_1', { id: 1, name: '王五' }, 10);
-
-// 获取缓存
-const user = await cache.get('user_1');
-
-// 删除缓存
-await cache.del('user_1');
-```
-
-#### 数值操作
-
-```javascript
-// 增加整数值
-await cache.addInt('counter', 1); // 增加1
-
-// 增加浮点数值
-await cache.addFloat('score', 0.5); // 增加0.5
-```
-
-#### 数组操作
-
-```javascript
-// 设置数组
-await cache.list_set('users', ['张三', '李四', '王五']);
-
-// 添加到数组
-await cache.list_push('users', '赵六');
-
-// 获取数组
-const users = await cache.list_get('users');
-
-// 判断元素是否在数组中
-const exists = await cache.list_has('users', '张三');
-```
-
-#### 过期时间管理
-
-```javascript
-// 设置过期时间（秒）
-await cache.expire('temp_data', 300); // 5分钟后过期
-
-// 获取剩余过期时间
-const ttl = await cache.ttl('temp_data');
-if (ttl === -1) console.log('永不过期');
-else if (ttl === -2) console.log('键不存在');
-else console.log(`剩余${ttl}秒过期`);
-```
-
-## Redis兼容API使用指南
-
-mm_mongodb提供了完整的Redis兼容API，使您可以使用熟悉的Redis命令与MongoDB进行交互。这对于从Redis迁移到MongoDB或在两者间切换使用非常有用。
-
-### 基本键值操作
-
-```javascript
-// 设置键值（支持过期时间）
+// 基本操作示例
 await cache.set('name', 'Redis Compatible');
-
-// 仅当键不存在时设置
-await cache.setnx('counter', 1);
-
-// 设置带过期时间的键（SET EX）
-await cache.setex('temp_key', 60, '临时值');
-
-// 获取键值
 const value = await cache.get('name');
-
-// 批量设置
-await cache.mset({ 'key1': 'value1', 'key2': 'value2' });
-
-// 批量获取
-const values = await cache.mget('key1', 'key2', 'key3');
-
-// 删除键
-await cache.del('name');
-
-// 批量删除键
-await cache.delKeys('key1', 'key2');
-
-// 判断键是否存在
-const exists = await cache.has('name');
-
-// 获取匹配的键名
-const keys = await cache.keys('user:*');
 ```
 
-### 字符串操作
+### 核心缓存方法
+
+| 方法名 | 说明 | 示例 |
+|-------|------|------|
+| `set(key, value, seconds)` | 设置键值，支持过期时间 | `await cache.set('name', 'value', 60);` |
+| `get(key)` | 获取键值 | `const value = await cache.get('name');` |
+| `del(key)` | 删除键 | `await cache.del('name');` |
+| `has(key)` / `exists(key)` | 判断键是否存在 | `const exists = await cache.has('name');` |
+| `clear(prefix)` | 清空缓存（可选前缀过滤） | `await cache.clear('temp:*');` |
+| `keys(pattern)` | 获取匹配的键名 | `const keys = await cache.keys('user:*');` |
+| `ttl(key)` | 获取剩余过期时间 | `const ttl = await cache.ttl('name');` |
+| `expire(key, seconds)` | 设置过期时间 | `await cache.expire('name', 60);` |
+| `add(key, value)` | 添加缓存（如果存在则不覆盖） | `await cache.add('counter', 1);` |
+| `addInt(key, value)` | 增加整数值 | `await cache.addInt('counter', 10);` |
+| `addFloat(key, value)` | 增加浮点数值 | `await cache.addFloat('score', 0.5);` |
+| `addStr(key, value)` | 追加字符串 | `await cache.addStr('message', ' World');` |
+| `sort(prefix, count, type)` | 排序并获取 | `const sorted = await cache.sort('user:*', 10, 'asc');` |
+
+### 哈希表操作
 
 ```javascript
-// 追加字符串
-await cache.append('greeting', ' World');
+// 设置哈希字段
+await cache.hset('user:1', 'name', '张三');
 
-// 获取字符串长度
-const length = await cache.strlen('greeting');
+// 获取哈希字段
+const name = await cache.hget('user:1', 'name');
 
-// 获取字符串子串
-const substring = await cache.getrange('greeting', 0, 4); // 获取前5个字符
+// 获取哈希所有字段和值
+const user = await cache.hgetall('user:1');
 
-// 设置字符串子串
-await cache.setrange('greeting', 6, 'MongoDB');
-```
+// 批量设置哈希字段
+await cache.hmset('user:2', { name: '李四', age: 30 });
 
-### 数值操作
+// 批量获取哈希字段
+const values = await cache.hmget('user:2', 'name', 'age');
 
-```javascript
-// 原子递增
-await cache.incr('counter'); // 自增1
+// 删除哈希字段
+await cache.hdel('user:1', 'name');
 
-// 原子递减
-await cache.decr('counter'); // 自减1
+// 批量删除哈希字段
+await cache.hdelMulti('user:2', 'name', 'age');
 
-// 增加指定整数
-await cache.incrby('counter', 10); // 增加10
+// 判断哈希字段是否存在
+const exists = await cache.hexists('user:1', 'name');
 
-// 减少指定整数
-await cache.decrby('counter', 5); // 减少5
+// 获取哈希字段数量
+const count = await cache.hlen('user:1');
+
+// 获取哈希所有字段名
+const keys = await cache.hkeys('user:1');
+
+// 获取哈希所有字段值
+const vals = await cache.hvals('user:1');
 ```
 
 ### 列表操作
 
 ```javascript
 // 从右侧推入元素
-await cache.rpush('list', 'item1');
+await cache.rpush('messages', '你好');
 
 // 从左侧推入元素
-await cache.lpush('list', 'item0');
+await cache.lpush('messages', 'Hello');
 
 // 获取列表长度
-const length = await cache.llen('list');
+const length = await cache.llen('messages');
 
 // 获取列表指定范围的元素
-const range = await cache.lrange('list', 0, 1); // 获取前两个元素
+const range = await cache.lrange('messages', 0, 1); // 获取前两个元素
 
 // 获取列表指定索引的元素
-const item = await cache.lindex('list', 0);
+const message = await cache.lindex('messages', 0);
 
 // 从左侧弹出元素
-const lpop = await cache.lpop('list');
+const firstMessage = await cache.lpop('messages');
 
 // 从右侧弹出元素
-const rpop = await cache.rpop('list');
+const lastMessage = await cache.rpop('messages');
 
 // 修改列表指定索引的元素
-await cache.lset('list', 0, 'new_item');
+await cache.lset('messages', 0, 'Updated Message');
 
 // 删除列表中的元素
-await cache.lrem('list', 2, 'value'); // 删除前2个值为'value'的元素
+await cache.lrem('messages', 2, 'value'); // 删除前2个值为'value'的元素
 
 // 裁剪列表
-await cache.ltrim('list', 0, 1); // 保留前两个元素
+await cache.ltrim('messages', 0, 4); // 保留前5个元素
 ```
 
 ### 集合操作
 
 ```javascript
 // 添加集合成员
-await cache.sadd('set', 'member1');
+await cache.sadd('users:online', 'user1');
 
 // 批量添加集合成员
-await cache.saddMulti('set', 'member2', 'member3');
+await cache.saddMulti('users:online', 'user2', 'user3');
 
 // 获取集合所有成员
-const members = await cache.smembers('set');
+const members = await cache.smembers('users:online');
 
 // 判断成员是否在集合中
-const isMember = await cache.sismember('set', 'member1');
+const isOnline = await cache.sismember('users:online', 'user1');
 
 // 获取集合成员数量
-const count = await cache.scard('set');
+const count = await cache.scard('users:online');
 
 // 移除集合成员
-await cache.srem('set', 'member1');
+await cache.srem('users:online', 'user1');
 
 // 批量移除集合成员
-await cache.sremMulti('set', 'member2', 'member3');
+await cache.sremMulti('users:online', 'user2', 'user3');
 
 // 计算两个集合的差集
-const diff = await cache.sdiff('set1', 'set2');
+const offlineUsers = await cache.sdiff('users:all', 'users:online');
 
 // 计算两个集合的交集
-const inter = await cache.sinter('set1', 'set2');
+const activeUsers = await cache.sinter('users:online', 'users:paid');
 
 // 计算两个集合的并集
-const union = await cache.sunion('set1', 'set2');
+const allUsers = await cache.sunion('users:online', 'users:offline');
 ```
 
-### 哈希操作
+### 有序集合操作
 
 ```javascript
-// 设置哈希字段
-await cache.hset('hash', 'field1', 'value1');
+// 添加有序集合成员
+await cache.zadd('ranking', 'user1', 100);
 
-// 获取哈希字段
-const value = await cache.hget('hash', 'field1');
-
-// 获取哈希所有字段和值
-const allFields = await cache.hgetall('hash');
+// 获取有序集合成员数量
+const count = await cache.zcard('ranking');
 
-// 批量设置哈希字段
-await cache.hmset('hash', { field2: 'value2', field3: 'value3' });
-
-// 批量获取哈希字段
-const values = await cache.hmget('hash', 'field1', 'field2', 'field3');
+// 获取有序集合成员分数
+const score = await cache.zscore('ranking', 'user1');
 
-// 删除哈希字段
-await cache.hdel('hash', 'field1');
+// 按分数范围获取有序集合成员
+const topUsers = await cache.zrangebyscore('ranking', 0, 100);
 
-// 批量删除哈希字段
-await cache.hdelMulti('hash', 'field2', 'field3');
+// 移除有序集合成员
+await cache.zrem('ranking', 'user1');
+```
 
-// 判断哈希字段是否存在
-const exists = await cache.hexists('hash', 'field1');
+### 批量操作
 
-// 获取哈希字段数量
-const count = await cache.hlen('hash');
+```javascript
+// 批量设置键值
+await cache.mset({ 'key1': 'value1', 'key2': 'value2' });
 
-// 获取哈希所有字段名
-const keys = await cache.hkeys('hash');
+// 批量获取键值
+const values = await cache.mget('key1', 'key2', 'key3');
 
-// 获取哈希所有字段值
-const values = await cache.hvals('hash');
+// 批量删除键
+await cache.del('key1', 'key2', 'key3');
 ```
 
-### 键重命名和数据库信息
+### 数值操作
 
 ```javascript
-// 重命名键
-await cache.rename('old_key', 'new_key');
+// 原子递增
+await cache.incr('counter'); // 自增1
+
+// 原子递减
+await cache.decr('counter'); // 自减1
 
-// 仅当新键不存在时重命名
-const renamed = await cache.renamenx('old_key', 'new_key');
+// 增加指定整数
+await cache.addInt('counter', 10); // 增加10
 
-// 获取键空间大小（数据库中的键数量）
-const size = await cache.dbsize();
+// 减少指定整数
+await cache.addInt('counter', -5); // 减少5
 ```
 
 ## 事件系统
@@ -413,23 +354,24 @@ cache.on('set_error', (data) => {
 
 以下增删改类方法支持事件触发：
 
-- 原子操作：incr, decr, incrby, decrby
+- 原子操作：incr, decr, addInt, addFloat
 - 字符串操作：append, addStr
-- 列表操作：rpush, lpush, lset, lrem, ltrim
+- 列表操作：rpush, lpush, lset, lrem, ltrim, lpop, rpop
 - 集合操作：sadd, saddMulti, srem, sremMulti
 - 哈希操作：hset, hmset, hdel, hdelMulti
-- 键操作：set, setnx, setex, mset, del, delKeys, rename, renamenx
+- 有序集合操作：zadd, zrem
+- 键操作：set, del, expire, mset
 
 ## 性能优化建议
 
 1. **使用连接池**：优先使用`mongodb_admin`和`mongodb_cache_admin`创建的连接池实例
 2. **合理设置索引**：为常用查询字段创建索引
 3. **查询优化**：避免全表扫描，使用精确查询
-4. **批量操作**：优先使用批量操作方法如`insertBatch`、`mget`、`mset`等
+4. **批量操作**：优先使用批量操作方法如`mset`、`mget`等
 5. **过期时间**：为临时数据设置合理的过期时间，避免数据膨胀
-6. **查询类方法**：注意查询类方法不触发事件，以提高查询性能
+6. **Redis兼容模式**：使用字符串键名可以简化操作，与Redis保持一致的使用体验
 
-## 迁移指南
+## 从Redis迁移指南
 
 从Redis迁移到使用mm_mongodb的Redis兼容API时，只需以下步骤：
 
@@ -442,6 +384,7 @@ cache.on('set_error', (data) => {
 // Redis客户端示例
 // const redis = require('redis');
 // const client = redis.createClient();
+// await client.connect();
 
 // mm_mongodb替换示例
 const { mongodb_cache_admin } = require('mm_mongodb');
@@ -502,46 +445,17 @@ new MongoDB(scope = 'default', dir = '', config = {})
 - `getIndexes(tableName)`：获取索引信息
 - `dropIndex(tableName, indexName)`：删除索引
 
-### Mongodb_cache类
+### Redis兼容API
 
-#### 基本操作
+详细的Redis兼容API见上方「Redis兼容API使用指南」章节。支持以下类别的API：
 
-- `get(key)`：获取缓存
-- `set(key, value, seconds)`：设置缓存
-- `add(key, value, seconds)`：添加缓存（如果存在则不覆盖）
-- `del(key)`：删除缓存
-- `has(key)`：判断键是否存在
-- `clear(prefix)`：清空缓存（可选前缀过滤）
-
-#### 数值操作
-
-- `addInt(key, value)`：增加整数值
-- `addFloat(key, value)`：增加浮点数值
-- `addStr(key, value)`：追加字符串
-
-#### 数组操作
-
-- `list_set(key, value, seconds)`：设置数组
-- `list_push(key, value)`：添加到数组
-- `list_get(key, start, end)`：获取数组片段
-- `list_has(key, value)`：判断元素是否在数组中
-- `list_clear(key, value)`：清空数组
-
-#### 过期时间
-
-- `expire(key, seconds)`：设置过期时间
-- `ttl(key)`：获取剩余过期时间
-
-#### 其他操作
-
-- `keys(pattern)`：获取匹配的键名
-- `getrange(key, start, end)`：获取字符串范围
-- `setrange(key, index, value)`：设置字符串范围
-- `sort(prefix, count, type)`：排序并获取
-
-#### Redis兼容API
-
-详细的Redis兼容API见上方「Redis兼容API使用指南」章节。
+- **核心缓存方法**：set, get, del, has, exists, clear, keys, ttl, expire等
+- **哈希表操作**：hset, hget, hgetall, hmset, hmget, hdel, hdelMulti, hexists, hkeys, hvals, hlen等
+- **列表操作**：rpush, lpush, lrange, lindex, llen, lpop, rpop, lset, lrem, ltrim等
+- **集合操作**：sadd, saddMulti, srem, sremMulti, smembers, scard, sismember, sdiff, sinter, sunion等
+- **有序集合操作**：zadd, zrem, zrangebyscore, zscore, zcard等
+- **批量操作**：mget, mset等
+- **数值操作**：incr, decr, addInt, addFloat等
 
 ## 安全注意事项
 
@@ -551,6 +465,10 @@ new MongoDB(scope = 'default', dir = '', config = {})
 4. 连接错误时会自动重试，提高稳定性
 5. 避免使用未经处理的用户输入作为查询条件
 
+## 兼容性表格
+
+查看详细的方法兼容性对比表格，请参考项目中的 [compatibility_table.md](https://github.com/qwwang/mm_mongodb/blob/main/compatibility_table.md) 文件。
+
 ## 依赖
 
 - [mm_logs](https://www.npmjs.com/package/mm_logs)：日志模块

package/compatibility_table.md

@@ -0,0 +1,85 @@
+```markdown
+# 三种缓存方式方法兼容性对比表格
+
+## 核心缓存方法
+
+| 方法名 | Redis | MongoDB | CacheBase | 状态说明 |
+|-------|-------|---------|-----------|----------|
+| set | ✅ | ✅ | ✅ | 完全兼容 |
+| get | ✅ | ✅ | ✅ | 完全兼容 |
+| del | ✅ | ✅ | ✅ | 完全兼容 |
+| has | ✅ | ✅ | ✅ | 完全兼容 |
+| clear | ✅ | ✅ | ✅ | 完全兼容 |
+| keys | ✅ | ✅ | ✅ | 完全兼容 |
+| ttl | ✅ | ✅ | ✅ | 完全兼容 |
+| add | ✅ | ✅ | ✅ | 完全兼容 |
+| addInt | ✅ | ✅ | ✅ | 完全兼容 |
+| addFloat | ✅ | ✅ | ✅ | 完全兼容 |
+| addStr | ✅ | ✅ | ✅ | 完全兼容 |
+| sort | ✅ | ✅ | ✅ | 模拟实现 |
+
+## Redis兼容方法 - 哈希表操作
+
+| 方法名 | Redis | MongoDB | CacheBase | 状态说明 |
+|-------|-------|---------|-----------|----------|
+| hset | ✅ | ✅ | ✅ | 模拟实现，通过set对象方式 |
+| hget | ✅ | ✅ | ✅ | 模拟实现，通过get对象方式 |
+| hgetall | ✅ | ✅ | ✅ | 模拟实现，返回完整对象 |
+| hdel | ✅ | ✅ | ✅ | 模拟实现，删除对象属性 |
+| hexists | ✅ | ✅ | ✅ | 模拟实现，通过hget判断 |
+| hkeys | ✅ | ✅ | ✅ | 模拟实现，返回对象所有键 |
+| hvals | ✅ | ✅ | ✅ | 模拟实现，返回对象所有值 |
+| hmset | ✅ | ✅ | ✅ | 模拟实现，批量设置哈希表字段 |
+| hmget | ✅ | ✅ | ✅ | 模拟实现，批量获取哈希表字段 |
+| hlen | ✅ | ✅ | ✅ | 模拟实现，返回哈希表字段数量 |
+
+## Redis兼容方法 - 集合操作
+
+| 方法名 | Redis | MongoDB | CacheBase | 状态说明 |
+|-------|-------|---------|-----------|----------|
+| sadd | ✅ | ✅ | ✅ | 模拟实现，通过数组存储集合 |
+| srem | ✅ | ✅ | ✅ | 模拟实现，从数组中移除元素 |
+| sismember | ✅ | ✅ | ✅ | 模拟实现，检查元素是否在数组中 |
+| smembers | ✅ | ✅ | ✅ | 模拟实现，返回数组所有元素 |
+| scard | ✅ | ✅ | ✅ | 模拟实现，返回数组长度 |
+| saddMulti | ✅ | ✅ | ✅ | 模拟实现，批量添加集合元素 |
+| sremMulti | ✅ | ✅ | ✅ | 模拟实现，批量移除集合元素 |
+| sdiff | ✅ | ✅ | ✅ | 模拟实现，集合差集操作 |
+| sinter | ✅ | ✅ | ✅ | 模拟实现，集合并集操作 |
+| sunion | ✅ | ✅ | ✅ | 模拟实现，集合交集操作 |
+
+## Redis兼容方法 - 有序集合操作
+
+| 方法名 | Redis | MongoDB | CacheBase | 状态说明 |
+|-------|-------|---------|-----------|----------|
+| zadd | ✅ | ✅ | ✅ | 模拟实现，通过对象存储分数 |
+| zrem | ✅ | ✅ | ✅ | 模拟实现，移除有序集合元素 |
+| zrangebyscore | ✅ | ✅ | ✅ | 模拟实现，按分数范围获取元素 |
+| zscore | ✅ | ✅ | ✅ | 模拟实现，获取元素分数 |
+| zcard | ✅ | ✅ | ✅ | 模拟实现，返回有序集合元素数量 |
+
+## Redis兼容方法 - 列表操作
+
+| 方法名 | Redis | MongoDB | CacheBase | 状态说明 |
+|-------|-------|---------|-----------|----------|
+| rpush | ✅ | ✅ | ✅ | 模拟实现，从列表右侧添加元素 |
+| lpush | ✅ | ✅ | ✅ | 模拟实现，从列表左侧添加元素 |
+| lrange | ✅ | ✅ | ✅ | 模拟实现，获取列表指定范围元素 |
+| lindex | ✅ | ✅ | ✅ | 模拟实现，获取列表指定索引元素 |
+| llen | ✅ | ✅ | ✅ | 模拟实现，获取列表长度 |
+| lpop | ✅ | ✅ | ✅ | 模拟实现，从列表左侧弹出元素 |
+| rpop | ✅ | ✅ | ✅ | 模拟实现，从列表右侧弹出元素 |
+
+## Redis兼容方法 - 其他常用命令
+
+| 方法名 | Redis | MongoDB | CacheBase | 状态说明 |
+|-------|-------|---------|-----------|----------|
+| expire | ✅ | ✅ | ✅ | 兼容，内部映射到ttl |
+| incr | ✅ | ✅ | ✅ | 完全兼容，通过addInt模拟 |
+| decr | ✅ | ✅ | ✅ | 完全兼容，通过addInt模拟 |
+| exists | ✅ | ✅ | ✅ | 兼容，内部映射到has |
+| mget | ✅ | ✅ | ✅ | 完全兼容，返回键值对对象 |
+| mset | ✅ | ✅ | ✅ | 完全兼容，批量设置键值 |
+
+注：✅ 完全兼容/功能正常 | ⚠️ 部分兼容/有异常 | ❌ 不兼容/未实现
+```