@@ -270,6 +270,7 @@ console.log(`总计: ${result.totals?.total}, 共 ${result.totals?.totalPages}
270270- ✅ ** Read** : find, findOne, findPage（游标分页）, aggregate, count, distinct
271271- ✅ ** Update** : updateOne, updateMany, replaceOne, findOneAndUpdate, findOneAndReplace
272272- ✅ ** Delete** : deleteOne, deleteMany, findOneAndDelete
273+ - ✅ ** Watch** : watch（Change Streams 实时监听）** ⭐ v1.1 .0 **
273274
274275#### ** 索引管理（100 % 完成）**
275276- ✅ createIndex, createIndexes, listIndexes, dropIndex, dropIndexes
@@ -980,6 +981,141 @@ const salesReport = await collection.aggregate([
980981
981982-- -
982983
984+ ### 实时监听（watch）⭐ v1.1 .0
985+
986+ ** 监听 MongoDB 数据变更，支持自动缓存失效** ：
987+
988+ #### 1. 基础监听
989+
990+ ` ` ` javascript
991+ // 监听集合的所有数据变更
992+ const watcher = collection.watch();
993+
994+ watcher.on('change', (change) => {
995+ console.log('数据变更:', change.operationType); // insert/update/delete/replace
996+ console.log('文档ID:', change.documentKey._id);
997+ console.log('完整文档:', change.fullDocument);
998+ });
999+
1000+ // 插入数据（会触发 change 事件）
1001+ await collection.insertOne({ name: 'Alice', age: 25 });
1002+ ` ` `
1003+
1004+ #### 2. 过滤事件
1005+
1006+ ` ` ` javascript
1007+ // 只监听 insert 和 update 操作
1008+ const watcher = collection.watch([
1009+ { $match: { operationType: { $in: ['insert', 'update'] } } }
1010+ ]);
1011+
1012+ watcher.on('change', (change) => {
1013+ console.log('新增或修改:', change.operationType);
1014+ });
1015+ ` ` `
1016+
1017+ #### 3. 自动缓存失效 ⭐
1018+
1019+ ` ` ` javascript
1020+ // 启用自动缓存失效（默认开启）
1021+ const watcher = collection.watch([], {
1022+ autoInvalidateCache: true // 数据变更时自动失效相关缓存
1023+ });
1024+
1025+ // 1. 查询并缓存数据
1026+ const users = await collection.find({ status: 'active' }, { cache: 60000 });
1027+
1028+ // 2. 更新数据（触发 watch）
1029+ await collection.updateOne({ _id: userId }, { $set: { status: 'inactive' } });
1030+
1031+ // 3. ✅ watch 自动失效相关缓存
1032+ // 4. 下次查询自动从数据库读取最新数据
1033+ ` ` `
1034+
1035+ #### 4. 错误处理和重连
1036+
1037+ ` ` ` javascript
1038+ const watcher = collection.watch();
1039+
1040+ // 监听错误（自动重试瞬态错误）
1041+ watcher.on('error', (error) => {
1042+ console.warn('持久性错误:', error.message);
1043+ });
1044+
1045+ // 监听重连
1046+ watcher.on('reconnect', (info) => {
1047+ console.log(` 第 ${info .attempt } 次重连，延迟 ${info .delay }ms` );
1048+ });
1049+
1050+ // 监听恢复
1051+ watcher.on('resume', () => {
1052+ console.log('✅ 已恢复监听（断点续传）');
1053+ });
1054+
1055+ // 监听致命错误
1056+ watcher.on('fatal', (error) => {
1057+ console.error('💥 致命错误（无法恢复）:', error);
1058+ // 通知运维
1059+ });
1060+ ` ` `
1061+
1062+ #### 5. 统计监控
1063+
1064+ ` ` ` javascript
1065+ const watcher = collection.watch();
1066+
1067+ // 获取运行统计
1068+ const stats = watcher.getStats();
1069+ console.log('总变更数:', stats.totalChanges);
1070+ console.log('重连次数:', stats.reconnectAttempts);
1071+ console.log('运行时长:', stats.uptime, 'ms');
1072+ console.log('缓存失效次数:', stats.cacheInvalidations);
1073+ console.log('活跃状态:', stats.isActive);
1074+ ` ` `
1075+
1076+ #### 6. 优雅关闭
1077+
1078+ ` ` ` javascript
1079+ // 应用退出时关闭 watcher
1080+ process.on('SIGTERM', async () => {
1081+ await watcher.close();
1082+ await db.close();
1083+ process.exit(0);
1084+ });
1085+ ` ` `
1086+
1087+ ** 核心特性** ：
1088+ - ✅ ** 自动重连** ：网络中断后自动恢复（指数退避：1s → 2s → 4s → ... → 60s ）
1089+ - ✅ ** 断点续传** ：resumeToken 自动管理，不丢失任何变更
1090+ - ✅ ** 智能缓存失效** ：数据变更时自动失效相关缓存
1091+ - ✅ ** 跨实例同步** ：分布式环境自动广播缓存失效
1092+ - ✅ ** 完整事件系统** ：change, error, reconnect, resume, close, fatal
1093+ - ✅ ** 统计监控** ：完整的运行统计和健康检查
1094+
1095+ ** 注意事项** ：
1096+ - ⚠️ ** 需要副本集** ：Change Streams 需要 MongoDB 4.0 + 副本集或分片集群
1097+ - ⚠️ ** 测试环境** ：可使用 mongodb- memory- server 副本集模式
1098+
1099+ ** 测试环境配置** ：
1100+ ` ` ` javascript
1101+ const db = new MonSQLize({
1102+ type: 'mongodb',
1103+ databaseName: 'mydb',
1104+ config: {
1105+ useMemoryServer: true,
1106+ memoryServerOptions: {
1107+ instance: {
1108+ replSet: 'rs0' // 启用副本集（支持 Change Streams）
1109+ }
1110+ }
1111+ }
1112+ });
1113+ ` ` `
1114+
1115+ 📖 详细文档：[watch 方法完整指南](./ docs/ watch .md )
1116+
1117+ -- -
1118+
9831119## 📚 完整文档
9841120
9851121### 核心文档
0 commit comments