Skip to content

Commit 7a18ba0

Browse files
rockyshi1993rockyshi1993
committed
feat:添加分布式事务锁,但是单元测试还没完全验证
1 parent 87d7546 commit 7a18ba0

24 files changed

Lines changed: 6475 additions & 18 deletions

‎CHANGELOG.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,40 @@
66

77
### Added
88

9+
#### 🌐 分布式部署支持 - v2.2.0（2025-11-25 - 完成）
10+
11+
**分布式缓存失效** ✅
12+
- ✨ 基于 Redis Pub/Sub 实现跨实例缓存失效广播
13+
- ✨ 自动订阅失效消息并更新本地缓存
14+
- ✨ 支持通配符模式匹配（如 `user:*`）
15+
- ✨ 实例ID隔离，避免自我触发
16+
- ✨ 1-5ms 延迟的实时广播
17+
- 🔧 **关键修复**: 添加 `setPublish()` 方法动态注入广播回调，确保分布式失效正常工作
18+
19+
**分布式事务锁** ✅
20+
- 🔒 基于 Redis 实现跨实例的事务缓存锁
21+
- 🔒 使用 SET NX EX 原子操作获取锁
22+
- 🔒 支持锁的自动过期（默认5分钟）
23+
- 🔒 使用 Lua 脚本批量释放锁
24+
- 🔒 防止事务中间状态被其他实例缓存
25+
26+
**核心文件** ✅
27+
- 📦 `lib/distributed-cache-invalidator.js` - 缓存失效广播器
28+
- 📦 `lib/transaction/DistributedCacheLockManager.js` - 分布式锁管理器
29+
- 📦 `lib/index.js` - 集成分布式组件
30+
31+
**文档** ✅
32+
- 📚 `docs/distributed-deployment.md` - 完整的部署指南（5种架构方案）
33+
- 📚 `examples/distributed-deployment.examples.js` - 3个可运行示例
34+
- 📚 `docs/INDEX.md` - 更新文档索引
35+
- 📚 `README.md` - 更新功能说明
36+
37+
**配置支持** ✅
38+
- ⚙️ `cache.distributed.enabled` - 启用分布式缓存失效
39+
- ⚙️ `cache.distributed.redisUrl` - Redis连接URL
40+
- ⚙️ `cache.distributed.channel` - 自定义频道
41+
- ⚙️ `cache.transaction.distributedLock` - 配置分布式事务锁
42+
943
#### 🚀 事务性能优化 - v2.1.0（2025-11-19 18:30 - 完成）
1044

1145
**优化1: 只读优化** ✅

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ monSQLize 完整封装了 MongoDB 的原生功能：
2525
- 🔧 **智能缓存**：TTL/LRU/命名空间失效/并发去重
2626
- 🔧 **自动缓存失效**：写操作后自动清理相关缓存
2727
- 🔧 **事务支持**：自动管理/手动管理，缓存锁，只读优化（-30% DB访问），文档级别锁（16倍并发），重试，超时，监控 🆕 v2.1.0
28+
- 🔧 **分布式部署**：多实例缓存一致性、事务隔离性保障、Redis Pub/Sub 广播 🆕 v2.2.0
2829
- 🔧 **深度分页**：游标分页（支持前后翻页、跳页、书签）
2930
- 🔧 **性能监控**：慢查询日志、查询超时控制、元数据返回
3031
- 🔧 **跨库访问**：轻松访问不同数据库的集合
@@ -43,6 +44,7 @@ monSQLize 完整封装了 MongoDB 的原生功能：
4344
- **Delete**: deleteOne, deleteMany, findOneAndDelete
4445
- **索引管理**: createIndex, createIndexes, listIndexes, dropIndex, dropIndexes
4546
- **事务支持**: withTransaction, startTransaction, 缓存锁, 只读优化, 文档级别锁, 重试, 超时, 监控, 统计 🆕 v2.1.0
47+
- **分布式部署**: 缓存失效广播, 分布式事务锁, 多实例支持 🆕 v2.2.0
4648
- **其他**: 智能缓存、多层缓存、跨库访问、慢查询日志、TypeScript 类型
4749

4850
- **计划中**：
@@ -63,6 +65,7 @@ monSQLize 完整封装了 MongoDB 的原生功能：
6365
| **执行计划** | ✅ | ✅ | 集成到查询链 |
6466
| **跨库访问** | 手动切换 | ✅ | 一行代码切换 |
6567
| **缓存管理** | ❌ | ✅ | TTL/LRU/自动失效/多层缓存 |
68+
| **分布式部署** | ❌ | ✅ | 多实例缓存一致性/事务锁 🆕 |
6669
| **性能监控** | 需配置 | ✅ | 开箱即用的慢查询日志 |
6770

6871
---

‎docs/INDEX.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@
1111
| [mongodb-native-vs-extensions.md](mongodb-native-vs-extensions.md) | **MongoDB 原生 vs monSQLize 扩展功能对比** |
1212
| [connection.md](connection.md) | 连接管理和配置 |
1313
| [cache.md](cache.md) | 缓存系统（LRU + TTL） |
14+
| [transaction.md](transaction.md) | 事务管理（自动重试、缓存锁） |
15+
| [transaction-optimizations.md](transaction-optimizations.md) | 事务优化策略 |
16+
| [distributed-deployment.md](distributed-deployment.md) | **分布式部署指南（多实例缓存一致性）⭐** |
1417
| [events.md](events.md) | 事件系统 |
1518

1619
---
@@ -94,6 +97,7 @@
9497
| [utilities.md](utilities.md) | 工具函数 |
9598
| [collection-management.md](collection-management.md) | 集合管理 |
9699
| [readPreference.md](readPreference.md) | 读偏好设置 |
100+
| [distributed-deployment.md](distributed-deployment.md) | **分布式部署配置** |
97101
| [MONGODB-MEMORY-SERVER.md](MONGODB-MEMORY-SERVER.md) | 内存数据库测试 |
98102

99103
---
@@ -152,9 +156,11 @@
152156
4. [update-one.md](update-one.md) / [update-many.md](update-many.md) - 学习更新数据
153157
5. [delete-one.md](delete-one.md) / [delete-many.md](delete-many.md) - 学习删除数据
154158
6. [cache.md](cache.md) - 了解缓存机制
159+
7. [transaction.md](transaction.md) - 学习事务管理
160+
8. [distributed-deployment.md](distributed-deployment.md) - **多实例部署（生产环境必读）**
155161

156162
---
157163

158-
**文档总数**: 34个（新增：increment-one.md）
159-
**最后更新**: 2025-11-18
164+
**文档总数**: 37个（新增：distributed-deployment.md）
165+
**最后更新**: 2025-11-25
160166

‎docs/distributed-deployment-quickref.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# 🚀 分布式部署快速参考
2+
3+
## 最简配置（只需3行）
4+
5+
```javascript
6+
distributed: {
7+
enabled: true // 只需这一行！其他都是可选的
8+
}
9+
```
10+
11+
---
12+
13+
## 完整配置（推荐）
14+
15+
```javascript
16+
const Redis = require('ioredis');
17+
const redis = new Redis('redis://localhost:6379');
18+
19+
const msq = new MonSQLize({
20+
type: 'mongodb',
21+
databaseName: 'mydb',
22+
config: { uri: 'mongodb://...' },
23+
cache: {
24+
multiLevel: true,
25+
local: { maxSize: 1000 },
26+
remote: MonSQLize.createRedisCacheAdapter(redis), // ① Redis 缓存
27+
distributed: {
28+
enabled: true, // ② 启用分布式失效
29+
instanceId: process.env.INSTANCE_ID // ③ 实例ID（建议设置）
30+
}
31+
}
32+
});
33+
```
34+
35+
---
36+
37+
## 参数速查表
38+
39+
### distributed（分布式缓存失效）
40+
41+
| 参数 | 必需？ | 默认值 |
42+
|-----|-------|--------|
43+
| `enabled` | ✅ 是 | - |
44+
| `redis` | ❌ 否 | 自动从 `remote` 提取 |
45+
| `instanceId` | ❌ 否 | `instance-${timestamp}-${random}` |
46+
| `channel` | ❌ 否 | `'monsqlize:cache:invalidate'` |
47+
48+
### transaction.distributedLock（事务锁）
49+
50+
| 参数 | 必需？ | 默认值 |
51+
|-----|-------|--------|
52+
| `redis` | ✅ 是 | - |
53+
| `keyPrefix` | ❌ 否 | `'monsqlize:cache:lock:'` |
54+
55+
---
56+
57+
## 常见场景
58+
59+
### 场景1: 一般Web应用（推荐）
60+
61+
```javascript
62+
distributed: {
63+
enabled: true,
64+
instanceId: process.env.INSTANCE_ID // 使用环境变量
65+
}
66+
```
67+
68+
### 场景2: 金融/支付系统
69+
70+
```javascript
71+
distributed: {
72+
enabled: true,
73+
instanceId: process.env.INSTANCE_ID
74+
},
75+
transaction: {
76+
distributedLock: {
77+
redis // 必须显式配置（ES6 简写）
78+
}
79+
}
80+
```
81+
82+
### 场景3: Kubernetes部署
83+
84+
```javascript
85+
distributed: {
86+
enabled: true,
87+
instanceId: process.env.HOSTNAME // 使用Pod名称
88+
}
89+
```
90+
91+
---
92+
93+
## 环境变量设置
94+
95+
### Docker
96+
97+
```bash
98+
docker run -e INSTANCE_ID=server-1 myapp
99+
```
100+
101+
### Kubernetes
102+
103+
```yaml
104+
env:
105+
- name: INSTANCE_ID
106+
valueFrom:
107+
fieldRef:
108+
fieldPath: metadata.name # 使用Pod名称
109+
```
110+
111+
### PM2
112+
113+
```json
114+
{
115+
"apps": [{
116+
"name": "app-1",
117+
"script": "server.js",
118+
"env": {
119+
"INSTANCE_ID": "app-1"
120+
}
121+
}]
122+
}
123+
```
124+
125+
---
126+
127+
## 关键点记忆
128+
129+
1. **`enabled: true`** - 唯一必需的配置
130+
2. **`redis`** - 自动从 `remote` 复用，无需重复配置
131+
3. **`instanceId`** - 可选但建议设置，便于调试
132+
4. **事务锁的 `redis`** - 必须显式配置
133+
134+
---
135+
136+
## 验证配置
137+
138+
```javascript
139+
// 启动后检查
140+
const stats = msq._cacheInvalidator?.getStats();
141+
console.log('分布式失效器状态:', stats);
142+
// 输出: { messagesSent: 0, messagesReceived: 0, instanceId: 'xxx', ... }
143+
```
144+
145+
---
146+
147+
**文档**: [完整说明](./distributed-deployment.md)
148+
**更新**: 2025-11-25
149+

0 commit comments

Comments
 (0)