mm_mongodb 1.4.6 → 1.4.8

package/README.md

@@ -13,7 +13,7 @@ MongoDB数据库操作模块，提供了简洁易用的API、缓存功能以及*
 - ✅ 环境变量配置支持
 - ✅ 完善的错误处理和重试机制
 - ✅ 查询注入防护
-- ✅ 事件系统：支持监听关键操作的事件
+- ✅ 事件系统：支持监听关键操作的事件，包括操作前、操作后和错误事件
 
 ## 安装
 
@@ -140,6 +140,84 @@ await db.createIndex('users', { name: 1 }, { unique: true });
 await db.createTTLIndex('logs', { createdAt: 1 }, 3600); // 3600秒后过期
 ```
 
+## 事件系统
+
+mm_mongodb提供了完整的事件系统，允许您监听各种数据库操作的前后事件，便于进行日志记录、性能监控、数据校验等操作。
+
+### 支持的事件
+
+| 事件名称 | 触发时机 | 事件参数 |
+|--------|--------|--------|
+| `set_before` | 在执行set操作前 | `{ table, key, value }` |
+| `set_after` | 在执行set操作后 | `{ table, key, value, result }` |
+| `set_error` | 在set操作出错时 | `{ table, key, value, error }` |
+| `del_before` | 在执行del操作前 | `{ table, key }` |
+| `del_after` | 在执行del操作后 | `{ table, key, result }` |
+| `del_error` | 在del操作出错时 | `{ table, key, error }` |
+| `add_before` | 在执行add操作前 | `{ table, key, value }` |
+| `add_after` | 在执行add操作后 | `{ table, key, value, result, exists }` |
+| `add_error` | 在add操作出错时 | `{ table, key, value, error }` |
+
+### 事件参数说明
+
+- `table`: 操作的表名
+- `key`: 操作的键名
+- `value`: 操作的值
+- `result`: 操作的结果
+- `error`: 错误信息（仅在错误事件中）
+- `exists`: 键是否已存在（仅在add_after事件中）
+
+### 使用示例
+
+```javascript
+const { MongoDB } = require('mm_mongodb');
+const db = new MongoDB();
+
+// 连接数据库
+await db.open();
+
+// 监听set操作前事件
+db.on('set_before', (data) => {
+    console.log(`准备设置缓存: ${data.key} = ${JSON.stringify(data.value)}`);
+    // 可以在这里进行数据校验、权限检查等
+});
+
+// 监听set操作后事件
+db.on('set_after', (data) => {
+    console.log(`缓存设置成功: ${data.key}, 结果:`, data.result);
+    // 可以在这里记录日志、触发其他操作等
+});
+
+// 监听add操作后事件，特别注意exists标记
+db.on('add_after', (data) => {
+    if (data.exists) {
+        console.log(`键 ${data.key} 已存在，未添加新值`);
+    } else {
+        console.log(`成功添加新键: ${data.key}`);
+    }
+});
+
+// 监听错误事件
+db.on('set_error', (data) => {
+    console.error(`设置缓存失败: ${data.key}, 错误:`, data.error);
+});
+
+// 执行操作，触发事件
+await db.set('test_key', 'test_value');
+
+// 测试add方法的exists标记
+await db.add('test_key', 'another_value'); // 键已存在，exists将为true
+```
+
+### 应用场景
+
+1. **数据校验和验证**：在操作前事件中验证数据的有效性
+2. **访问控制和权限管理**：检查是否有权限执行特定操作
+3. **性能监控**：记录操作执行时间，监控系统性能
+4. **审计日志**：记录所有关键操作的详细信息
+5. **缓存一致性维护**：在数据变更时更新相关缓存
+6. **业务规则执行**：在特定操作前后执行业务逻辑
+
 ## Redis兼容API使用指南
 
 mm_mongodb提供了**完整的Redis兼容API**，使您可以使用熟悉的Redis命令与MongoDB进行交互。这对于从Redis迁移到MongoDB或在两者间切换使用非常有用。
@@ -335,6 +413,17 @@ await cache.addInt('counter', -5); // 减少5
 
 mm_mongodb的缓存模块实现了事件系统，可以监听各种操作的发生。增删改类方法会触发相应的事件，而查询类方法不触发事件以提高性能。
 
+### 事件命名规范
+
+所有事件严格遵循以下命名格式：
+- 操作前事件：`action_before`
+- 操作后事件：`action_after`
+- 操作错误事件：`action_error`
+
+其中`action`为方法名，例如`set`、`del`、`add`等。
+
+### 事件示例
+
 ```javascript
 // 监听事件
 cache.on('set_before', (data) => {
@@ -352,7 +441,7 @@ cache.on('set_error', (data) => {
 
 ### 支持事件的方法
 
-以下增删改类方法支持事件触发：
+以下增删改类方法支持事件触发，每种方法都会触发对应的`action_before`、`action_after`和`action_error`事件：
 
 - 原子操作：incr, decr, addInt, addFloat
 - 字符串操作：append, addStr
@@ -360,7 +449,17 @@ cache.on('set_error', (data) => {
 - 集合操作：sadd, saddMulti, srem, sremMulti
 - 哈希操作：hset, hmset, hdel, hdelMulti
 - 有序集合操作：zadd, zrem
-- 键操作：set, del, expire, mset
+- 键操作：set, del, expire, mset, add
+
+### 事件参数
+
+事件回调函数接收的参数通常包含以下信息：
+- 操作涉及的键（key）
+- 操作涉及的值（value）
+- 操作结果（仅在after事件中）
+- 错误信息（仅在error事件中）
+
+具体参数结构取决于触发事件的方法类型。
 
 ## 性能优化建议