mm_mongodb 1.4.4 → 1.4.5

package/README.md

@@ -1,231 +1,565 @@
-# mm_mongodb
-
-这是超级美眉mongodb帮助函数模块，用于便捷操作mongodb，使用await方式，可以避免嵌套函数。
-
-## 功能特点
-
-- 支持异步/await操作，避免回调地狱
-- 简化MongoDB的常用操作
-- 支持数据库连接池
-- 提供缓存操作扩展
-- 支持基本的CRUD操作
-
-## 安装
-
-```bash
-npm install mm_mongodb
-```
-
-## 基础配置
-
-### 默认配置
-
-```javascript
-const config = {
-    // 服务器地址
-    host: "localhost",
-    // 端口号
-    port: 27017,
-    // 数据库名
-    database: "mm",
-    // 用户名
-    user: "admin",
-    // 密码
-    password: "",
-    // 附加选项
-    options: {
-        useNewUrlParser: true,
-        useUnifiedTopology: true
-    }
-}
-```
-
-## 基本使用
-
-### 引入模块
-
-```javascript
-const { MongoDB, mongoDB_admin } = require('mm_mongodb');
-```
-
-### 创建连接
-
-```javascript
-// 方式1：直接实例化
-const mb = new MongoDB("localhost", "mm");
-mb.setConfig();
-await mb.open();
-
-// 方式2：使用管理器（推荐，支持连接池）
-const mb = mongoDB_admin("sys");
-mb.setConfig();
-await mb.open();
-```
-
-## API文档
-
-### 数据库操作
-
-#### open()
-- 说明：连接数据库
-- 返回：Promise对象，连接成功返回true
-
-#### close()
-- 说明：关闭数据库连接
-
-#### setConfig(config)
-- 说明：设置数据库配置
-- 参数：
-  - config: Object|String - 配置对象或配置文件路径
-
-### 表操作
-
-#### addTable(table)
-- 说明：创建数据表
-- 参数：
-  - table: String - 表名
-- 返回：Promise对象
-
-### 数据操作
-
-#### addObj(obj)
-- 说明：添加一条数据
-- 参数：
-  - obj: Object - 要添加的对象
-- 返回：Promise对象
-
-#### addList(list)
-- 说明：批量添加数据
-- 参数：
-  - list: Array - 对象数组
-- 返回：Promise对象
-
-#### del(query)
-- 说明：删除数据
-- 参数：
-  - query: Object - 查询条件
-- 返回：Promise对象
-
-#### set(query, body)
-- 说明：修改数据
-- 参数：
-  - query: Object - 查询条件
-  - body: Object - 修改内容
-- 返回：Promise对象
-
-#### get(query)
-- 说明：查询数据
-- 参数：
-  - query: Object - 查询条件
-- 返回：Promise对象，返回数组
-
-## 使用示例
-
-### 基本CRUD操作
-
-```javascript
-const { MongoDB } = require('mm_mongodb');
-
-async function test() {
-    // 实例化构造函数
-    const mb = new MongoDB("localhost", "mm");
-    mb.setConfig();
-    
-    // 连接数据库
-    await mb.open();
-    
-    try {
-        // 创建数据表
-        await mb.addTable('mm_table');
-        
-        // 添加单条数据
-        let ret = await mb.addObj({
-            name: "张三",
-            age: 21,
-            sex: true
-        });
-        
-        // 批量添加数据
-        ret = await mb.addList([{
-            name: "李四",
-            age: 18,
-            sex: false
-        }, {
-            name: "王五",
-            age: 15,
-            sex: true
-        }]);
-        
-        // 查询数据
-        ret = await mb.get({
-            name: '李四'
-        });
-        
-        // 修改数据
-        ret = await mb.set(
-            { name: '李四' },
-            { age: 20 }
-        );
-        
-        // 删除数据
-        ret = await mb.del({
-            name: '王五'
-        });
-        
-    } catch (e) {
-        console.error(e);
-    }
-    
-    // 关闭连接
-    mb.close();
-}
-```
-
-### 缓存操作扩展
-
-```javascript
-const { Mongodb_cache, mongodb_cache_admin } = require('mm_mongodb/cache');
-
-async function test() {
-    const mb = new Mongodb_cache("localhost", "mm");
-    mb.setConfig();
-    await mb.open();
-    
-    try {
-        // 添加缓存
-        await mb.add("user:1", {
-            name: "张三",
-            age: 21
-        });
-        
-        // 获取缓存
-        const data = await mb.get("user:1");
-        
-        // 设置缓存（带过期时间）
-        await mb.set("temp:1", "临时数据", 3600); // 1小时后过期
-        
-        // 删除缓存
-        await mb.del("user:1");
-        
-    } catch (e) {
-        console.error(e);
-    }
-    
-    mb.close();
-}
-```
-
-## 注意事项
-
-1. 使用前请确保MongoDB服务已启动
-2. 建议使用try-catch处理可能的异常
-3. 操作完成后记得关闭连接
-4. 推荐使用连接池管理器（mongoDB_admin）来创建实例
-
-## 许可证
-
-ISC License
-
-## 作者
-
-qww
+# mm_mongodb
+
+MongoDB数据库操作模块，提供了简洁易用的API、缓存功能以及完整的Redis兼容接口。
+
+## 功能特点
+
+- 支持MongoDB连接池管理
+- 自动连接和重连机制
+- 事务支持
+- 索引管理
+- 缓存功能
+- **Redis兼容API**：支持Redis风格的键值操作、列表、集合、哈希等数据类型
+- 环境变量配置支持
+- 完善的错误处理和重试机制
+- 查询注入防护
+- 事件系统：支持监听关键操作的事件
+
+## 安装
+
+```bash
+npm install mm_mongodb
+```
+
+## 配置
+
+### 基本配置
+
+在项目根目录创建 `config.tpl.json` 文件，配置如下：
+
+```json
+{
+    "mongodb": {
+        "url": "mongodb://username:password@host:port/database",
+        "poolSize": 20,
+        "minPoolSize": 5,
+        "maxPoolSize": 100,
+        "waitQueueTimeoutMS": 10000,
+        "connectTimeoutMS": 10000,
+        "socketTimeoutMS": 45000,
+        "authSource": "admin",
+        "authMechanism": "DEFAULT"
+    }
+}
+```
+
+### 环境变量配置
+
+支持通过环境变量配置MongoDB连接信息，优先级高于配置文件：
+
+- `MONGO_URL`：MongoDB连接字符串
+- `MONGO_HOST`：MongoDB主机地址
+- `MONGO_PORT`：MongoDB端口
+- `MONGO_USERNAME`：MongoDB用户名
+- `MONGO_PASSWORD`：MongoDB密码
+- `MONGO_DATABASE`：MongoDB数据库名
+- `MONGO_AUTH_SOURCE`：认证源数据库
+- `MONGO_AUTH_MECHANISM`：认证机制
+
+## 使用示例
+
+### 基本使用
+
+```javascript
+const { MongoDB } = require('mm_mongodb');
+
+// 创建MongoDB实例
+const db = new MongoDB();
+
+// 连接数据库
+await db.open();
+
+// 创建表
+await db.createTable('users');
+
+// 插入数据
+await db.insert('users', { name: '张三', age: 25 });
+
+// 查询数据
+const result = await db.get('users', { name: '张三' });
+
+// 更新数据
+await db.set('users', { name: '张三' }, { age: 26 });
+
+// 删除数据
+await db.del('users', { name: '张三' });
+
+// 关闭连接
+await db.close();
+```
+
+### 使用连接池
+
+```javascript
+const { mongodb_admin } = require('mm_mongodb');
+
+// 获取连接池实例
+const db = mongodb_admin('default');
+
+// 使用连接池
+await db.open();
+const data = await db.get('users', {});
+```
+
+### 使用事务
+
+```javascript
+const { MongoDB } = require('mm_mongodb');
+const db = new MongoDB();
+
+await db.open();
+
+// 开始事务
+const session = await db.startTransaction();
+
+try {
+    // 在事务中执行操作
+    await db.insert('users', { name: '李四', age: 30 }, { session });
+    await db.insert('orders', { userId: '李四', amount: 100 }, { session });
+    
+    // 提交事务
+    await db.commitTransaction(session);
+    console.log('事务提交成功');
+} catch (error) {
+    // 回滚事务
+    await db.rollbackTransaction(session);
+    console.error('事务回滚:', error);
+}
+```
+
+### 创建索引
+
+```javascript
+const db = new MongoDB();
+await db.open();
+
+// 创建普通索引
+await db.createIndex('users', { name: 1 }, { unique: true });
+
+// 创建TTL索引（数据过期自动删除）
+await db.createTTLIndex('logs', { createdAt: 1 }, 3600); // 3600秒后过期
+```
+
+### 缓存使用
+
+#### 基本缓存操作
+
+```javascript
+const { mongodb_cache_admin } = require('mm_mongodb');
+
+// 获取缓存实例
+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:*');
+```
+
+### 字符串操作
+
+```javascript
+// 追加字符串
+await cache.append('greeting', ' World');
+
+// 获取字符串长度
+const length = await cache.strlen('greeting');
+
+// 获取字符串子串
+const substring = await cache.getrange('greeting', 0, 4); // 获取前5个字符
+
+// 设置字符串子串
+await cache.setrange('greeting', 6, 'MongoDB');
+```
+
+### 数值操作
+
+```javascript
+// 原子递增
+await cache.incr('counter'); // 自增1
+
+// 原子递减
+await cache.decr('counter'); // 自减1
+
+// 增加指定整数
+await cache.incrby('counter', 10); // 增加10
+
+// 减少指定整数
+await cache.decrby('counter', 5); // 减少5
+```
+
+### 列表操作
+
+```javascript
+// 从右侧推入元素
+await cache.rpush('list', 'item1');
+
+// 从左侧推入元素
+await cache.lpush('list', 'item0');
+
+// 获取列表长度
+const length = await cache.llen('list');
+
+// 获取列表指定范围的元素
+const range = await cache.lrange('list', 0, 1); // 获取前两个元素
+
+// 获取列表指定索引的元素
+const item = await cache.lindex('list', 0);
+
+// 从左侧弹出元素
+const lpop = await cache.lpop('list');
+
+// 从右侧弹出元素
+const rpop = await cache.rpop('list');
+
+// 修改列表指定索引的元素
+await cache.lset('list', 0, 'new_item');
+
+// 删除列表中的元素
+await cache.lrem('list', 2, 'value'); // 删除前2个值为'value'的元素
+
+// 裁剪列表
+await cache.ltrim('list', 0, 1); // 保留前两个元素
+```
+
+### 集合操作
+
+```javascript
+// 添加集合成员
+await cache.sadd('set', 'member1');
+
+// 批量添加集合成员
+await cache.saddMulti('set', 'member2', 'member3');
+
+// 获取集合所有成员
+const members = await cache.smembers('set');
+
+// 判断成员是否在集合中
+const isMember = await cache.sismember('set', 'member1');
+
+// 获取集合成员数量
+const count = await cache.scard('set');
+
+// 移除集合成员
+await cache.srem('set', 'member1');
+
+// 批量移除集合成员
+await cache.sremMulti('set', 'member2', 'member3');
+
+// 计算两个集合的差集
+const diff = await cache.sdiff('set1', 'set2');
+
+// 计算两个集合的交集
+const inter = await cache.sinter('set1', 'set2');
+
+// 计算两个集合的并集
+const union = await cache.sunion('set1', 'set2');
+```
+
+### 哈希操作
+
+```javascript
+// 设置哈希字段
+await cache.hset('hash', 'field1', 'value1');
+
+// 获取哈希字段
+const value = await cache.hget('hash', 'field1');
+
+// 获取哈希所有字段和值
+const allFields = await cache.hgetall('hash');
+
+// 批量设置哈希字段
+await cache.hmset('hash', { field2: 'value2', field3: 'value3' });
+
+// 批量获取哈希字段
+const values = await cache.hmget('hash', 'field1', 'field2', 'field3');
+
+// 删除哈希字段
+await cache.hdel('hash', 'field1');
+
+// 批量删除哈希字段
+await cache.hdelMulti('hash', 'field2', 'field3');
+
+// 判断哈希字段是否存在
+const exists = await cache.hexists('hash', 'field1');
+
+// 获取哈希字段数量
+const count = await cache.hlen('hash');
+
+// 获取哈希所有字段名
+const keys = await cache.hkeys('hash');
+
+// 获取哈希所有字段值
+const values = await cache.hvals('hash');
+```
+
+### 键重命名和数据库信息
+
+```javascript
+// 重命名键
+await cache.rename('old_key', 'new_key');
+
+// 仅当新键不存在时重命名
+const renamed = await cache.renamenx('old_key', 'new_key');
+
+// 获取键空间大小（数据库中的键数量）
+const size = await cache.dbsize();
+```
+
+## 事件系统
+
+mm_mongodb的缓存模块实现了事件系统，可以监听各种操作的发生。增删改类方法会触发相应的事件，而查询类方法不触发事件以提高性能。
+
+```javascript
+// 监听事件
+cache.on('set_before', (data) => {
+    console.log('设置缓存前:', data);
+});
+
+cache.on('set_after', (data) => {
+    console.log('设置缓存后:', data);
+});
+
+cache.on('set_error', (data) => {
+    console.error('设置缓存错误:', data);
+});
+```
+
+### 支持事件的方法
+
+以下增删改类方法支持事件触发：
+
+- 原子操作：incr, decr, incrby, decrby
+- 字符串操作：append, addStr
+- 列表操作：rpush, lpush, lset, lrem, ltrim
+- 集合操作：sadd, saddMulti, srem, sremMulti
+- 哈希操作：hset, hmset, hdel, hdelMulti
+- 键操作：set, setnx, setex, mset, del, delKeys, rename, renamenx
+
+## 性能优化建议
+
+1. **使用连接池**：优先使用`mongodb_admin`和`mongodb_cache_admin`创建的连接池实例
+2. **合理设置索引**：为常用查询字段创建索引
+3. **查询优化**：避免全表扫描，使用精确查询
+4. **批量操作**：优先使用批量操作方法如`insertBatch`、`mget`、`mset`等
+5. **过期时间**：为临时数据设置合理的过期时间，避免数据膨胀
+6. **查询类方法**：注意查询类方法不触发事件，以提高查询性能
+
+## 迁移指南
+
+从Redis迁移到使用mm_mongodb的Redis兼容API时，只需以下步骤：
+
+1. 安装mm_mongodb：`npm install mm_mongodb`
+2. 修改导入语句：将Redis客户端导入改为`mongodb_cache_admin`
+3. 添加连接初始化：调用`await cache.open()`确保连接已建立
+4. 保持命令调用不变：大多数Redis命令可以直接使用
+
+```javascript
+// Redis客户端示例
+// const redis = require('redis');
+// const client = redis.createClient();
+
+// mm_mongodb替换示例
+const { mongodb_cache_admin } = require('mm_mongodb');
+const cache = mongodb_cache_admin('default');
+await cache.open(); // 确保连接已建立
+
+// 后续命令调用保持不变
+await cache.set('key', 'value');
+const value = await cache.get('key');
+```
+
+## API文档
+
+### MongoDB类
+
+#### 构造函数
+
+```javascript
+new MongoDB(scope = 'default', dir = '', config = {})
+```
+- `scope`：作用域，用于区分不同的连接池
+- `dir`：配置文件路径
+- `config`：配置对象
+
+#### 连接管理
+
+- `open()`：连接数据库
+- `close()`：关闭数据库连接
+- `setUrl(url)`：设置连接URL
+- `setConfig(config)`：设置配置
+
+#### 表操作
+
+- `createTable(tableName)`：创建表
+- `dropTable(tableName)`：删除表
+- `existsTable(tableName)`：检查表是否存在
+
+#### 数据操作
+
+- `insert(tableName, data)`：插入数据
+- `insertBatch(tableName, datas)`：批量插入数据
+- `get(tableName, query, options)`：查询数据
+- `getOne(tableName, query, options)`：查询单条数据
+- `set(tableName, query, data, options)`：修改数据
+- `del(tableName, query, options)`：删除数据
+- `count(tableName, query)`：统计数量
+
+#### 事务支持
+
+- `startTransaction()`：开始事务，返回会话对象
+- `commitTransaction(session)`：提交事务
+- `rollbackTransaction(session)`：回滚事务
+
+#### 索引管理
+
+- `createIndex(tableName, keys, options)`：创建索引
+- `createTTLIndex(tableName, keys, expireAfterSeconds)`：创建TTL索引
+- `getIndexes(tableName)`：获取索引信息
+- `dropIndex(tableName, indexName)`：删除索引
+
+### Mongodb_cache类
+
+#### 基本操作
+
+- `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使用指南」章节。
+
+## 安全注意事项
+
+1. 密码会自动进行URI编码，确保安全传输
+2. 支持查询条件注入防护
+3. 自动加载环境变量中的敏感信息，避免硬编码
+4. 连接错误时会自动重试，提高稳定性
+5. 避免使用未经处理的用户输入作为查询条件
+
+## 依赖
+
+- [mm_logs](https://www.npmjs.com/package/mm_logs)：日志模块
+- [mongodb](https://www.npmjs.com/package/mongodb)：MongoDB官方驱动
+
+## 作者
+
+邱文武 - [qww.elins.cn](http://qww.elins.cn)
+
+## 许可证
+
+MIT