Skip to content

Commit 3162a30

Browse files
rockyshi1993rockyshi1993
committed
feat:新增支持Change Stream 同步
1 parent 22c4330 commit 3162a30

17 files changed

Lines changed: 3216 additions & 3 deletions

‎CHANGELOG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99

1010
| 版本 | 日期 | 变更摘要 | 详细 |
1111
|------|------|---------|------|
12-
| [v1.0.8](./changelogs/v1.0.8.md) | 2026-01-17 | 🎉 重大功能：多连接池管理 + Update 聚合管道 + Saga 分布式事务 | [查看](./changelogs/v1.0.8.md) |
12+
| [v1.0.8](./changelogs/v1.0.8.md) | 2026-01-17 | 🎉 重大功能：多连接池 + Update 聚合管道 + Saga 事务 + Change Stream 同步 | [查看](./changelogs/v1.0.8.md) |
1313
| [v1.0.7](./changelogs/v1.0.7.md) | 2026-01-09 | 🔧 依赖更新：schema-dsl@1.1.3 修复类型错误消息 + 测试用例 Schema 语法修复 | [查看](./changelogs/v1.0.7.md) |
1414
| [v1.0.6](./changelogs/v1.0.6.md) | 2026-01-08 | 文档完善：新增 ObjectId 自动转换文档 + 验证所有 v1.3.0+ 功能文档 | [查看](./changelogs/v1.0.6.md) |
1515
| [v1.0.5](./changelogs/v1.0.5.md) | 2026-01-08 | Schema 验证默认启用 + Model 自动加载机制 + 类型定义完善 | [查看](./changelogs/v1.0.5.md) |

‎README.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -562,6 +562,50 @@ const result = await msq.executeSaga('create-order-with-payment', data);
562562

563563
[完整文档](./docs/saga-transaction.md)
564564

565+
---
566+
567+
#### 🆕 Change Stream 数据同步 (v1.0.9)
568+
569+
**实时同步数据到备份库，基于 MongoDB Change Stream**
570+
571+
```javascript
572+
const msq = new MonSQLize({
573+
type: 'mongodb',
574+
config: {
575+
uri: 'mongodb://localhost:27017/main',
576+
replicaSet: 'rs0' // 🔴 必须：Change Stream 需要 Replica Set
577+
},
578+
579+
// 🆕 同步配置
580+
sync: {
581+
enabled: true,
582+
targets: [
583+
{
584+
name: 'backup-main',
585+
uri: 'mongodb://backup:27017/backup',
586+
collections: ['users', 'orders']
587+
}
588+
]
589+
}
590+
});
591+
592+
await msq.connect();
593+
594+
// 正常使用，自动同步
595+
await msq.collection('users').insertOne({ name: 'Alice' });
596+
// ✅ 自动通过 Change Stream 同步到 backup-main
597+
```
598+
599+
**Change Stream 特性**：
600+
- ✅ 实时同步（延迟 10-500ms）
601+
- ✅ 断点续传（Resume Token）
602+
- ✅ 多目标支持（多地容灾）
603+
- ✅ 数据过滤和转换
604+
- ✅ 自动重连和健康检查
605+
- ✅ 主库影响 <2%（异步处理）
606+
607+
[完整文档](./docs/sync-backup.md)
608+
565609
### 3. 📦 便利方法 - 减少 60~80% 代码
566610

567611
<table>

‎STATUS.md‎

Lines changed: 78 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99

1010
- [发布计划](#发布计划)
1111
- [v1.1.0 - ✅ 已完成](#v110)
12-
- [v1.0.8 - ✅ 已完成](#v108)
12+
- [v1.0.8 - 🚧 开发中](#v108)
1313
- [v1.0.7 - ✅ 已完成](#v107)
1414
- [v1.0.6 - ✅ 已完成](#v106)
1515
- [v1.0.5 - ✅ 已完成](#v105)
@@ -28,7 +28,7 @@
2828
| 版本 | 发布状态 | 发布日期 | 需求数 | 进度 |
2929
|------|---------|---------|--------|------|
3030
| [v1.1.0](#v110) | ✅ 已完成 | 2026-01-17 | 1 | 1/1 完成 |
31-
| [v1.0.8](#v108) | ✅ 已完成 | 2026-01-16 | 3 | 3/3 完成 |
31+
| [v1.0.8](#v108) | 🚧 开发中 | 2026-01-17 | 4 | 4/4 完成 |
3232
| [v1.0.7](#v107) | ✅ 已完成 | 2026-01-09 | 3 | 3/3 完成 |
3333
| [v1.0.6](#v106) | ✅ 已完成 | 2026-01-08 | 1 | 1/1 完成 |
3434
| [v1.0.5](#v105) | ✅ 已完成 | 2026-01-08 | 3 | 3/3 完成 |
@@ -42,6 +42,82 @@
4242

4343
## v1.0.8 {#v108}
4444

45+
**发布日期**: 2026-01-17
46+
**版本类型**: 🎉 重大功能 + Update 聚合管道 + Saga 分布式事务 + Change Stream 同步
47+
**进度**: 4 个需求 | 4 个已完成
48+
**测试覆盖率**: 95%+ 🏆
49+
50+
| 需求标题 | 状态 | 优先级 | 详细 |
51+
|---------|------|--------|------|
52+
| Update 聚合管道支持 | ✅ 已完成 | P1 | [方案](../plans/requirements/req-update-aggregation-v1.0.8.md) |
53+
| 多连接池管理 | ✅ 已完成 | P1 | [方案](../plans/requirements/req-multi-pool-v1.0.8.md) |
54+
| Saga 分布式事务 | ✅ 已完成 | P1 | [方案](../plans/requirements/req-saga-v1.0.8.md) |
55+
| Change Stream 数据同步 | ✅ 已完成 | P1 | [方案](../plans/requirements/req-sync-changestream-final-v1.0.8.md) |
56+
57+
**核心功能**:
58+
- ✅ Update 聚合管道（突破原生限制）
59+
- ✅ 多连接池智能管理
60+
- ✅ Saga 分布式事务协调
61+
- ✅ Change Stream 实时数据同步
62+
63+
**Change Stream 同步特性**:
64+
- ✅ 基于 MongoDB Change Stream 实时同步
65+
- ✅ 支持多备份目标
66+
- ✅ Resume Token 断点续传
67+
- ✅ 数据过滤和转换
68+
- ✅ 自动重连和健康检查
69+
- ✅ 主库影响 <2%
70+
71+
**文件清单**:
72+
- Update 聚合管道相关文件
73+
- 多连接池相关文件
74+
- Saga 相关文件
75+
- **Change Stream 同步**:
76+
- `lib/sync/ChangeStreamSyncManager.js` (280行)
77+
- `lib/sync/SyncTarget.js` (120行)
78+
- `lib/sync/ResumeTokenStore.js` (80行)
79+
- `lib/sync/SyncConfig.js` (50行)
80+
- `lib/sync/index.js` (10行)
81+
- 修改 `lib/index.js` (+90行)
82+
- `docs/sync-backup.md`
83+
- `examples/sync-backup.examples.js`
84+
- `test/unit/sync/*.test.js` (32个测试用例)
85+
86+
---
87+
88+
## v1.0.9 {#v109}
89+
90+
**发布日期**: 2026-01-17
91+
**版本类型**: 🎉 Change Stream 数据同步
92+
**进度**: 1 个需求 | 1 个已完成
93+
**测试覆盖率**: 95%+ 🏆
94+
95+
| 需求标题 | 状态 | 优先级 | 详细 |
96+
|---------|------|--------|------|
97+
| Change Stream 数据同步 | ✅ 已完成 | P1 | [方案](../plans/requirements/req-sync-changestream-final-v1.0.9.md) |
98+
99+
**核心功能**:
100+
- ✅ 基于 MongoDB Change Stream 实时同步
101+
- ✅ 支持多备份目标
102+
- ✅ Resume Token 断点续传
103+
- ✅ 数据过滤和转换
104+
- ✅ 自动重连和健康检查
105+
- ✅ 主库影响 <2%
106+
107+
**文件清单**:
108+
- `lib/sync/ChangeStreamSyncManager.js` (280行)
109+
- `lib/sync/SyncTarget.js` (120行)
110+
- `lib/sync/ResumeTokenStore.js` (80行)
111+
- `lib/sync/SyncConfig.js` (50行)
112+
- `lib/sync/index.js` (10行)
113+
- 修改 `lib/index.js` (+80行)
114+
- `docs/sync-backup.md`
115+
- `examples/sync-backup.examples.js`
116+
117+
---
118+
119+
## v1.0.8 {#v108}
120+
45121
**发布日期**: 2026-01-17
46122
**版本类型**: 🎉 重大功能 + Update 聚合管道 + Saga 分布式事务
47123
**进度**: 4 个需求 | 4 个已完成

‎changelogs/v1.0.8-sync.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# v1.0.9 变更日志
2+
3+
> **发布日期**: 2026-01-17
4+
> **版本类型**: 🎉 新功能 - Change Stream 数据同步
5+
6+
---
7+
8+
## 🎉 新功能
9+
10+
### Change Stream 数据同步
11+
12+
**实时同步数据到备份库，基于 MongoDB Change Stream 原生机制**
13+
14+
#### 核心特性
15+
16+
- ✅ **实时同步**：延迟 10-500ms，基于 MongoDB Change Stream
17+
- ✅ **断点续传**：Resume Token 自动保存，重启后继续
18+
- ✅ **多目标支持**：同时同步到多个备份库
19+
- ✅ **数据过滤**：自定义过滤逻辑
20+
- ✅ **数据转换**：支持脱敏、字段转换
21+
- ✅ **自动重连**：网络中断自动恢复（最多5次）
22+
- ✅ **健康检查**：复用 ConnectionPoolManager
23+
- ✅ **主库影响小**：<2%，异步处理
24+
25+
#### 使用示例
26+
27+
```javascript
28+
const MonSQLize = require('monsqlize');
29+
30+
const msq = new MonSQLize({
31+
type: 'mongodb',
32+
config: {
33+
uri: 'mongodb://localhost:27017/main',
34+
replicaSet: 'rs0' // 🔴 必须
35+
},
36+
37+
// 🆕 同步配置
38+
sync: {
39+
enabled: true,
40+
targets: [
41+
{
42+
name: 'backup-main',
43+
uri: 'mongodb://backup:27017/backup',
44+
collections: ['users', 'orders']
45+
}
46+
],
47+
resumeToken: {
48+
storage: 'file', // 'file' | 'redis'
49+
path: './.sync-resume-token'
50+
}
51+
}
52+
});
53+
54+
await msq.connect();
55+
56+
// 正常使用，自动同步
57+
await msq.collection('users').insertOne({ name: 'Alice' });
58+
// ✅ 自动同步到 backup-main
59+
```
60+
61+
#### 新增文件
62+
63+
| 文件 | 行数 | 说明 |
64+
|------|------|------|
65+
| `lib/sync/ChangeStreamSyncManager.js` | 280 | Change Stream 管理器（核心） |
66+
| `lib/sync/SyncTarget.js` | 120 | 备份目标（复用连接池） |
67+
| `lib/sync/ResumeTokenStore.js` | 80 | Resume Token 持久化 |
68+
| `lib/sync/SyncConfig.js` | 50 | 配置验证 |
69+
| `lib/sync/index.js` | 10 | 模块导出 |
70+
71+
#### 修改文件
72+
73+
| 文件 | 变更 | 说明 |
74+
|------|------|------|
75+
| `lib/index.js` | +80行 | 集成 ChangeStreamSyncManager |
76+
77+
#### 新增文档
78+
79+
- `docs/sync-backup.md`: 完整使用指南
80+
- `examples/sync-backup.examples.js`: 6个示例
81+
82+
---
83+
84+
## ⚠️ 前提条件
85+
86+
使用 Change Stream 同步需要满足：
87+
88+
1. **MongoDB Replica Set** 🔴
89+
```bash
90+
rs.status() # 检查
91+
rs.initiate() # 初始化（单节点转 Replica Set）
92+
```
93+
94+
2. **MongoDB 版本 >= 4.0** 🔴
95+
96+
3. **用户权限** 🔴
97+
- 需要 `changeStream` 权限
98+
99+
---
100+
101+
## 📊 性能影响
102+
103+
| 写入 QPS | 主库 CPU | 主库内存 | 同步延迟 |
104+
|---------|---------|---------|---------|
105+
| 100 | +0.5% | +10MB | 10-50ms |
106+
| 1000 | +1% | +20MB | 50-200ms |
107+
| 5000 | +2% | +50MB | 200-500ms |
108+
109+
---
110+
111+
## 🔧 API
112+
113+
### 构造函数选项
114+
115+
```javascript
116+
{
117+
sync: {
118+
enabled: boolean, // 是否启用
119+
targets: Array, // 备份目标
120+
resumeToken: Object, // Resume Token 配置
121+
filter: Function, // 过滤函数（可选）
122+
transform: Function // 转换函数（可选）
123+
}
124+
}
125+
```
126+
127+
### 实例方法
128+
129+
```javascript
130+
// 获取统计
131+
msq._syncManager.getStats()
132+
133+
// 手动停止
134+
await msq._syncManager.stop()
135+
136+
// 手动启动
137+
await msq._syncManager.start()
138+
```
139+
140+
---
141+
142+
## 📚 完整文档
143+
144+
- [使用指南](../docs/sync-backup.md)
145+
- [示例代码](../examples/sync-backup.examples.js)
146+
- [方案设计](../plans/requirements/req-sync-changestream-final-v1.0.9.md)
147+
- [验证报告](../reports/monSQLize/verification/sync-changestream-verification-v1.0.9.md)
148+
149+
---
150+
151+
## 🎯 应用场景
152+
153+
1. **多地容灾**: 同步到多个地域的备份库
154+
2. **数据备份**: 实时备份到专用备份库
155+
3. **数据仓库**: 同步到分析库（ETL）
156+
4. **跨集群同步**: 同步到其他 MongoDB 集群
157+
158+
---
159+
160+
## ⚡ 性能优化建议
161+
162+
1. **过滤不必要的集合**
163+
```javascript
164+
collections: ['users', 'orders'] // 不要用 ['*']
165+
```
166+
167+
2. **使用 Redis 存储 Resume Token**
168+
```javascript
169+
resumeToken: { storage: 'redis', redis: redisInstance }
170+
```
171+
172+
3. **数据转换尽量轻量**
173+
```javascript
174+
transform: (doc) => {
175+
delete doc.heavyField; // 删除大字段
176+
return doc;
177+
}
178+
```
179+
180+
---
181+
182+
## 🐛 已知限制
183+
184+
1. **必须是 Replica Set**: 单节点不支持 Change Stream
185+
2. **初次启动无历史数据**: 只同步启动后的变更
186+
3. **Resume Token 丢失**: 重启后从当前时间开始
187+
188+
---
189+
190+
_发布时间: 2026-01-17_
191+
_版本: v1.0.9_
192+

‎docs/INDEX.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
| [cache.md](cache.md) | 缓存系统（LRU + TTL） |
2424
| [transaction.md](transaction.md) | 事务管理（自动重试、缓存锁） |
2525
| [saga-transaction.md](saga-transaction.md) | **🎉 Saga 分布式事务 - 跨服务事务补偿机制（v1.0.8+）🆕** |
26+
| [sync-backup.md](sync-backup.md) | **🎉 Change Stream 数据同步 - 实时备份到多个数据库（v1.0.8+）🆕** |
2627
| [business-lock.md](business-lock.md) | **业务级分布式锁** |
2728

2829
| [transaction-optimizations.md](transaction-optimizations.md) | 事务优化策略 |

0 commit comments

Comments
 (0)