---

📑 目录

- ⚡ 性能对比
- 🎯 项目愿景
- 💡 为什么选择 monSQLize？
- 🎯 何时使用 monSQLize？
- 🚀 快速开始
- 🌟 核心特性
- 0. 🎯 统一表达式系统 🆕
- 1. ⚡ 智能缓存系统
- 2. 🏢 企业级特性
- 3. 📦 便利方法
- 4. 🎯 可选Model层
- 5. 🔄 事务管理优化
- 📊 性能测试报告
- 🎨 完整功能清单
- 🆚 与 MongoDB 原生驱动对比
- 📖 完整文档
- 🌍 兼容性
- 🗺️ 产品路线图
- 🤝 贡献指南
- 📄 许可证
- 💬 社区与支持

---

⚡ 性能对比

`javascript
// ❌ MongoDB 原生驱动
const users = await collection.find({ status: 'active' }).toArray(); // 50ms
const product = await products.findOne({ _id: productId }); // 10ms

// ✅ monSQLize（启用缓存）
const users = await collection.find({ status: 'active' }, { cache: 60000 }); // 0.5ms ⚡ 100x faster
const product = await products.findOne({ _id: productId }, { cache: 60000 }); // 0.1ms ⚡ 100x faster
`

只需在初始化时配置缓存，业务代码一行不改，性能立即提升！

---

🎯 项目愿景

用MongoDB语法统一所有数据库查询

monSQLize = MongoDB + SQL = 统一查询语法

$3

为MongoDB应用提供：

- ⚡ 10~100倍性能提升 - L1（内存）+ L2（Redis）智能缓存，业界最完善
- 🏢 企业级特性 - 分布式锁、SSH隧道、慢查询监控（内置，零配置）
- 🛠️ 56+增强方法 - 业界最完整，代码减少60~80%
- 🎯 可选Model层 - Schema验证、Hooks、Populate（6个方法支持）
- ✅ 100% API兼容 - 零学习成本，渐进式采用

⚡ 智能缓存 L1: 内存缓存 (LRU) L2: Redis缓存 自动失效 10~100倍性能提升

🏢 企业特性 分布式锁 SSH隧道 慢查询监控 事务优化 批量操作

🛠️ 增强方法 56+个方法 代码减少60~80% ObjectId自动转换 语义化API

$3

革命性目标: 让MySQL/PostgreSQL也能用MongoDB语法

`javascript
// 同一套代码，支持多种数据库
const users = await collection.find({
age: { $gte: 18 },
status: 'active'
});

// MongoDB - ✅ 当前已支持
// MySQL - 🎯 未来自动转换为: SELECT * FROM users WHERE age >= 18 AND status = 'active'
// PostgreSQL - 🎯 未来自动转换为: SELECT * FROM users WHERE age >= 18 AND status = 'active'
`

解决的核心痛点:
- ❌ 切换数据库需要重写所有查询代码
- ❌ 团队需要学习多种查询语法
- ❌ 跨数据库迁移成本极高
- ❌ 多数据库项目维护复杂

monSQLize方案:
- ✅ 统一使用MongoDB查询语法（最直观、最灵活）
- ✅ 底层自动适配不同数据库
- ✅ 一套代码，多种数据库
- ✅ 零迁移成本

了解更多: 📖 完整项目愿景文档

---

💡 为什么选择 monSQLize？

$3

😫 数据库性能瓶颈 - 高并发时查询变慢 - 热点数据重复查询数据库 - 聚合统计拖慢响应速度 - 用户抱怨页面加载慢 😫 代码重复繁琐 - ObjectId 转换到处都是 - 批量查询要写很多代码 - Upsert 操作不够直观 - 事务代码复杂易错 😫 多实例部署问题 - 缓存不一致导致脏读 - 定时任务重复执行 - 库存扣减并发冲突 - 需要额外的锁机制

✅ monSQLize 的解决方案 - 智能缓存系统 - 热点数据走缓存，10~100倍性能提升 - 自动失效机制 - 写操作自动清理，保证数据一致性 - 缓存命中率 70~90% - 真实业务场景验证 - 响应时间 < 1ms - 从 10~50ms 降至毫秒级 ✅ monSQLize 的解决方案 - 便利方法 - findOneById、findByIds、upsertOne - 自动转换 ObjectId - 无需手动处理 - 语义化 API - 代码更清晰易读 - 事务自动管理 - withTransaction 简化事务代码 ✅ monSQLize 的解决方案 - Redis 广播 - 多实例缓存自动同步 - 分布式锁 - 解决并发控制问题 - 定时任务防重 - tryAcquireLock 机制 - 开箱即用 - 配置简单，无需额外组件

$3

| 场景 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| 商品详情页 | 50ms/次 | 0.5ms/次 | 100x ⚡ |
| 用户列表 | 80ms/次 | 0.8ms/次 | 100x ⚡ |
| 订单统计 | 200ms/次 | 2ms/次 | 100x ⚡ |
| 批量插入 10万条 | 30s | 1.2s | 25x ⚡ |

缓存命中率：电商 85% · 内容平台 75% · 社交应用 80%

---

🎯 何时使用 monSQLize？

$3

| 场景 | 说明 | 预期效果 |
|------|------|---------|
| 高并发读取 | 商品详情、用户信息等热点数据 | 缓存命中率 70~90%，响应时间从 10~50ms 降至 < 1ms |
| 复杂查询 | 聚合统计、关联查询 | 重复查询直接走缓存，避免重复计算 |
| 多实例部署 | 负载均衡、水平扩展 | Redis 广播保证缓存一致性 |
| 事务密集 | 订单、支付等业务 | 自动管理事务，优化只读操作 |
| 并发控制 | 库存扣减、定时任务 | 分布式锁解决复杂并发场景 |

$3

| 场景 | 原因 | 建议 |
|------|------|------|
| 纯写入应用 | 大量写入，很少查询 | 缓存作用有限，使用原生驱动即可 |
| 实时性要求极高 | 必须每次查询最新数据 | 不启用缓存，或使用极短 TTL |
| 简单 CRUD | 简单应用，流量不大 | 原生驱动足够，无需引入复杂度 |
| 内存受限 | 服务器内存紧张 | 缓存会占用额外内存 |

$3

- 渐进式采用：先在热点查询启用缓存，观察效果后逐步扩展
- 监控指标：关注缓存命中率、内存使用、慢查询日志
- 合理配置：根据业务特点调整 TTL、缓存大小
- 混合使用：可与原生驱动混用，性能敏感用 monSQLize，简单查询用原生

---

�️ 文档导航

$3

连接管理 · ObjectId 自动转换 🆕 · 缓存系统 · 事务管理 · Model 层 · 业务锁 · SSH 隧道 · 分布式部署

$3

find · findOne · findOneById · findByIds · findPage · count · distinct · watch ⭐

$3

插入: insertOne · insertMany · insertBatch
更新: updateOne · updateMany · updateBatch · replaceOne · findOneAndUpdate · findOneAndReplace
删除: deleteOne · deleteMany · deleteBatch · findOneAndDelete
便利方法: upsertOne · incrementOne · findAndCount

$3

aggregate · explain · 链式调用 ⭐ · 索引管理 · Count 队列 ⭐ · 慢查询日志 · 书签管理 · ESM 支持

完整文档索引: docs/INDEX.md - 60+ 篇详细文档

---

�🚀 快速开始

$3

`bash
npm install monsqlize
`

自动安装的依赖：
- ✅ mongodb - MongoDB 官方驱动
- ✅ schema-dsl - Schema 验证库（Model 层必需）
- ✅ ssh2 - SSH 隧道支持

可选依赖：
- ⚠️ ioredis - Redis 多层缓存（启用 L2 缓存需要）

$3

`javascript
const MonSQLize = require('monsqlize');

// 1. 初始化并连接
const msq = new MonSQLize({
type: 'mongodb',
databaseName: 'mydb',
config: { uri: 'mongodb://localhost:27017' },
cache: { enabled: true, ttl: 60000 } // 启用缓存，60秒过期
});

await msq.connect();

// 2. 获取集合
const users = msq.collection('users');

// 3. 基础查询（自动缓存）
const user = await users.findOne({ email: 'test@example.com' });

// 4. 插入数据
await users.insertOne({
username: 'john',
email: 'john@example.com',
createdAt: new Date()
});

// 5. 更新数据（自动清除缓存）
await users.updateOne(
{ email: 'test@example.com' },
{ $set: { lastLogin: new Date() } }
);

// 6. 便利方法（自动转换ObjectId）
const userById = await users.findOneById('507f1f77bcf86cd799439011');

// 7. 关闭连接
await msq.close();
`

就这么简单！ 完全兼容MongoDB原生API，只需初始化时启用缓存，业务代码零改动。

$3

如果需要 Schema验证、Populate关联查询、Hooks生命周期 等 ORM 特性，可以使用 Model 层。

> 📦 依赖说明: Model 层需要 schema-dsl 包支持（已随 monsqlize 自动安装，无需额外操作）

`javascript
const MonSQLize = require('monsqlize');
const { Model } = MonSQLize;

const msq = new MonSQLize({
type: 'mongodb',
databaseName: 'mydb',
config: { uri: 'mongodb://localhost:27017' },
cache: { enabled: true },
models: './models' // 🆕 v1.0.7: 自动加载 Model 文件
});

await msq.connect(); // 自动加载 models/*.model.js

// 1. 定义 Model（带 Schema 验证、Relations 和 Hooks）
Model.define('users', {
// 🔴 Schema 验证（默认启用，v1.0.7+，基于 schema-dsl 库）
schema: (dsl) => dsl({
username: 'string:3-32!', // 必需，3-32 字符
email: 'email!', // 必需，邮箱格式
password: 'string:6-!', // 必需，至少 6 字符
age: 'number:0-120', // 可选，0-120 范围
role: 'string?' // 可选字符串
}),

// Relations（关联查询）
relations: {
posts: { // 用户的文章
from: 'posts',
localField: '_id',
foreignField: 'userId',
single: false
}
},

// Hooks（生命周期钩子）
hooks: (model) => ({
insert: {
before: async (ctx, doc) => {
doc.createdAt = new Date(); // 自动添加时间戳
return doc;
}
}
}),

// 自定义方法
methods: (model) => ({
instance: {
// 文档方法（注入到查询结果）
checkPassword(password) {
return this.password === password;
}
},
static: {
// Model 方法
async findByUsername(username) {
return await model.findOne({ username });
}
}
})
});

Model.define('posts', {
schema: (dsl) => dsl({
title: 'string:1-200!',
content: 'string!',
userId: 'string!'
})
});

// 2. 使用 Model
const User = msq.model('users');

// ✅ Schema 验证自动生效
try {
await User.insertOne({
username: 'jo', // ❌ 太短，验证失败
email: 'invalid-email', // ❌ 邮箱格式错误
age: 25
});
} catch (err) {
console.error(err.code); // 'VALIDATION_ERROR'
console.error(err.errors); // 详细的验证错误
}

// ✅ 正确的数据
const user = await User.insertOne({
username: 'john',
email: 'john@example.com',
password: 'secret123',
age: 25
// createdAt 由 hook 自动添加
});

// 使用自定义方法
const foundUser = await User.findByUsername('john');
if (foundUser.checkPassword('secret123')) {
console.log('登录成功');
}

// Populate 关联查询（自动填充用户的文章）
const userWithPosts = await User.findOne({ username: 'john' })
.populate('posts');

console.log(userWithPosts.posts); // [{ title: '...', content: '...' }, ...]

// 禁用验证（特殊场景）
await User.insertOne(doc, { skipValidation: true });
`

Model 层特性：
- ✅ Schema 验证 - 自动验证数据格式（基于 schema-dsl 库，v1.0.7 默认启用）
- ✅ 自动加载 - 扫描目录自动加载 Model 文件（v1.0.7+）
- ✅ Populate - 关联查询，支持 6 个方法（业界领先）
- ✅ Hooks - 生命周期钩子（insert/update/delete/find）
- ✅ Relations - 定义表关系（hasOne/hasMany/belongsTo）
- ✅ 自定义方法 - instance 方法注入到文档，static 方法挂载到 Model
- ✅ 自动缓存 - Populate 查询结果也会缓存

📖 详细文档：Model 层完整指南 | Populate API | Hooks API | Schema 验证

---

$3

`javascript
// 原来的代码
const { MongoClient } = require('mongodb');
const client = await MongoClient.connect('mongodb://localhost:27017');
const db = client.db('mydb');
const users = db.collection('users');

// 迁移后（只需改初始化）
const MonSQLize = require('monsqlize');
const msq = new MonSQLize({
type: 'mongodb',
databaseName: 'mydb', // 数据库名称
config: { uri: 'mongodb://localhost:27017' },
cache: { enabled: true } // 启用缓存
});
await msq.connect();
const users = msq.collection('users');

// ✅ 后续代码完全不变
const user = await users.findOne({ email: 'test@example.com' });
`

---

🌟 核心特性

$3

122个操作符（100% MongoDB支持！新增49个函数），让MongoDB聚合查询像写SQL一样简单！

🆕 统一表达式语法 `javascript const { expr } = require('monsqlize'); // ❌ MongoDB原生（繁琐） await users.aggregate([ { $project: { fullName: { $concat: ['$firstName', ' ', '$lastName'] }, age: { $subtract: [ { $year: new Date() }, { $year: '$birthDate' } ] } } } ]); // ✅ 统一表达式（简洁） await users.aggregate([ { $project: { fullName: expr("CONCAT(firstName, ' ', lastName)"), age: expr("YEAR(CURRENT_DATE) - YEAR(birthDate)") } } ]); `

核心优势 - ✅ 67个操作符 - 覆盖95%使用场景 - ✅ 类SQL语法 - 易读易写，降低学习成本 - ✅ 上下文感知 - 自动适配$match/$project/$group - ✅ Lambda表达式 - FILTER/MAP完整支持 - ✅ 高性能 - LRU缓存，>90%命中率 - ✅ 100%兼容 - 可与原生语法混用 支持的操作符分类: - 🔹 条件判断 (三元、SWITCH) - 🔹 数学计算 (ABS、ROUND、POW等) - 🔹 字符串处理 (CONCAT、SPLIT、REPLACE等) - 🔹 数组操作 (FILTER、MAP、SIZE等) - 🔹 日期处理 (YEAR、MONTH、DAY等) - 🔹 类型转换 (TO_INT、TO_STRING等)

更多示例：

`javascript
// 条件判断 - 三元运算符
expr("score >= 90 ? 'A' : 'B'")

// 多分支条件 - SWITCH
expr("SWITCH(score >= 90, 'A', score >= 80, 'B', score >= 60, 'C', 'F')")

// 字符串处理
expr("UPPER(TRIM(email))")
expr("SPLIT(tags, ',')")

// 数组过滤（Lambda表达式）
expr("FILTER(items, item, item.price > 100)")

// 日期计算
expr("YEAR(createdAt) === 2024 && MONTH(createdAt) === 12")

// 完整聚合查询示例
await orders.aggregate([
{
$project: {
// 价格计算
finalPrice: expr("price * (1 - discount / 100)"),

// 日期提取
year: expr("YEAR(createdAt)"),
month: expr("MONTH(createdAt)"),

// 状态分类
statusLabel: expr("SWITCH(status === 'paid', 'Paid', status === 'pending', 'Pending', 'Cancelled')")
}
},
{
$group: {
_id: { year: '$year', month: '$month' },
totalOrders: expr("COUNT()"),
totalRevenue: expr("SUM(finalPrice)")
}
}
]);
`

📖 完整文档：统一表达式系统 | 67个操作符列表

---

$3

特性 - ✅ TTL 过期策略 - 指定缓存时间 - ✅ LRU 淘汰策略 - 自动淘汰旧数据 - ✅ 自动失效 - 写操作自动清理缓存 - ✅ 并发去重 - 相同查询只执行一次 - ✅ 多层缓存 - 内存 + Redis - ✅ 命名空间隔离 - 按集合独立管理

性能提升 | 操作 | 原生驱动 | monSQLize | 提升 | |------|---------|-----------|------| | 热点查询 | 50ms | 0.5ms | 100x ⚡ | | 复杂聚合 | 200ms | 2ms | 100x ⚡ | | 列表查询 | 30ms | 0.3ms | 100x ⚡ |

`javascript
// 一行代码启用缓存
const users = await collection.find({ status: 'active' }, { cache: 60000 });
`

$3

`javascript
// 自动管理事务生命周期
await db.withTransaction(async (tx) => {
// 只读操作会被优化（不加锁，减少 30% 访问）
const user = await users.findOne({ _id: userId }, { session: tx.session });

// 写操作自动加锁
await users.updateOne({ _id: userId }, { $inc: { balance: -100 } }, { session: tx.session });

// 自动提交 or 回滚
});
`

$3

`javascript
// 定义 Saga（跨服务事务）
msq.defineSaga({
name: 'create-order-with-payment',
steps: [
{
name: 'create-order',
execute: async (ctx) => {
const order = await createOrder(ctx.data);
// ✅ 可以保存字符串、对象、数组等任何类型
ctx.set('order', order); // 保存完整对象
return order;
},
compensate: async (ctx) => {
const order = ctx.get('order');
await cancelOrder(order.id);
}
},
{
name: 'charge-payment',
execute: async (ctx) => {
const charge = await stripe.charges.create({...});
ctx.set('charge', charge); // 保存完整对象
return charge;
},
compensate: async (ctx) => {
const charge = ctx.get('charge');
await stripe.refunds.create({ charge: charge.id });
}
}
]
});

// 执行 Saga（失败自动补偿）
const result = await msq.executeSaga('create-order-with-payment', data);
`

Saga 特性：
- ✅ 跨服务事务协调
- ✅ 失败自动补偿（逆序执行）
- ✅ 支持 Redis 分布式（多进程共享）
- ✅ 无时间限制（突破 60秒限制）
- ✅ 详细日志（完整执行追踪）

完整文档

---

#### 🆕 Change Stream 数据同步 (v1.0.9)

实时同步数据到备份库，基于 MongoDB Change Stream

`javascript
const msq = new MonSQLize({
type: 'mongodb',
config: {
uri: 'mongodb://localhost:27017/main',
replicaSet: 'rs0' // 🔴 必须：Change Stream 需要 Replica Set
},

// 🆕 同步配置
sync: {
enabled: true,
targets: [
{
name: 'backup-main',
uri: 'mongodb://backup:27017/backup',
collections: ['users', 'orders']
}
]
}
});

await msq.connect();

// 正常使用，自动同步
await msq.collection('users').insertOne({ name: 'Alice' });
// ✅ 自动通过 Change Stream 同步到 backup-main
`

Change Stream 特性：
- ✅ 实时同步（延迟 10-500ms）
- ✅ 断点续传（Resume Token）
- ✅ 多目标支持（多地容灾）
- ✅ 数据过滤和转换
- ✅ 自动重连和健康检查
- ✅ 主库影响 <2%（异步处理）

完整文档

$3

❌ 原生驱动 `javascript // 查询单个文档（需要手动转换 ObjectId） const { ObjectId } = require('mongodb'); const user = await users.findOne({ _id: new ObjectId(userId) }); // 批量查询（需要手动构建 $in） const userList = await users.find({ _id: { $in: ids.map(id => new ObjectId(id)) } }).toArray(); // Upsert（需要手动设置选项） await users.updateOne( { email: 'alice@example.com' }, { $set: { name: 'Alice', age: 30 } }, { upsert: true } ); `

✅ monSQLize `javascript // 查询单个文档（自动转换） const user = await users.findOneById(userId); // 批量查询（一行搞定） const userList = await users.findByIds(ids); // Upsert（语义化） await users.upsertOne( { email: 'alice@example.com' }, { name: 'Alice', age: 30 } ); ` 代码减少 60~80%！

🔥 ObjectId 自动转换 - 告别手动转换

`javascript
// ❌ 原生驱动 - 每次都要转换
const { ObjectId } = require('mongodb');
await users.findOne({ _id: new ObjectId(userId) });
await users.find({ _id: { $in: ids.map(id => new ObjectId(id)) } }).toArray();

// ✅ monSQLize - 自动识别并转换
await users.findOneById(userId); // 自动转换字符串
await users.findByIds([id1, id2, id3]); // 批量自动转换
await users.findOne({ _id: userId }); // 查询时也自动转换
`

$3

`javascript
// 多实例部署，Redis 自动同步缓存
const db = new MonSQLize({
cache: {
distributed: {
enabled: true,
redis: redisInstance // 使用 Redis 广播缓存失效
}
}
});

// 实例 A 更新数据
await users.updateOne({ _id: userId }, { $set: { name: 'Bob' } });
// ⚡ 实例 B/C/D 的缓存自动失效
`

$3

`javascript
// 🔥 解决复杂业务场景的并发问题

// 场景1：库存扣减
await db.withLock(inventory:${sku}, async () => {
const product = await inventory.findOne({ sku });
const price = calculatePrice(product, user, coupon); // 复杂计算
if (user.balance < price) throw new Error('余额不足');

await inventory.updateOne({ sku }, { $inc: { stock: -1 } });
await users.updateOne({ userId }, { $inc: { balance: -price } });
await orders.insertOne({ userId, sku, price });
});

// 场景2：定时任务防重（多实例环境）
const lock = await db.tryAcquireLock('cron:daily-report');
if (lock) {
try {
await generateDailyReport(); // 只有一个实例执行
} finally {
await lock.release();
}
}
`

特性：基于 Redis · 自动重试 · TTL 防死锁 · 支持续期 · 降级策略

📖 完整文档

$3

`javascript
// 批量插入 10 万条数据
await users.insertBatch(documents, {
batchSize: 1000, // 每批 1000 条
retryTimes: 3, // 失败重试 3 次
onProgress: (stats) => {
console.log(进度: ${stats.inserted}/${stats.total});
}
});
`

性能: 比原生 insertMany 快 10~50 倍 ⚡

$3

`javascript
// 千万级数据分页（游标分页，性能稳定）
const result = await users.findPage({
query: { status: 'active' },
page: 1000, // 第 1000 页
limit: 20,
totals: {
mode: 'async', // 异步统计总数
ttl: 300000 // 缓存 5 分钟
}
});

console.log(总计: ${result.totals.total}, 共 ${result.totals.totalPages} 页);
`

$3

`javascript
// 🆕 慢查询日志持久化存储（v1.3+）
const msq = new MonSQLize({
type: 'mongodb',
config: { uri: 'mongodb://localhost:27017/mydb' },
slowQueryMs: 500,
slowQueryLog: true // ✅ 零配置启用，自动存储到 admin.slow_query_logs
});

await msq.connect();

// 查询慢查询日志（支持去重聚合）
const logs = await msq.getSlowQueryLogs(
{ collection: 'users' },
{ sort: { count: -1 }, limit: 10 } // 查询高频慢查询Top10
);
// [{ queryHash: 'abc123', count: 2400, avgTimeMs: 520, maxTimeMs: 1200, ... }]

// 自动记录慢查询（原有功能）
// [WARN] Slow query { ns: 'mydb.users', duration: 1200ms, query: {...} }

// 健康检查
const health = await db.health();
// { status: 'ok', uptime: 3600, connections: 10 }

// 性能指标
const stats = await db.getStats();
// { queries: 10000, cacheHits: 9000, hitRate: 0.9 }
`

$3

`javascript
// 场景：数据库位于防火墙后，无法直接访问
const db = new MonSQLize({
type: 'mongodb',
config: {
// SSH隧道配置
ssh: {
host: 'bastion.example.com', // SSH服务器（跳板机）
port: 22,
username: 'deploy',
password: 'your-password', // ✅ 支持密码认证
// 或使用私钥认证（推荐）
// privateKeyPath: '~/.ssh/id_rsa',
},
// MongoDB连接配置（内网地址，自动从URI解析remoteHost和remotePort）
uri: 'mongodb://user:pass@internal-mongo:27017/mydb'
}
});

await db.connect(); // 自动建立SSH隧道
// 正常使用MongoDB，无需关心隧道细节
const users = db.collection('users');
const data = await users.findOne({});
await db.close(); // 自动关闭SSH隧道
`

特性：
- ✅ 支持密码和私钥认证
- ✅ 自动管理隧道生命周期
- ✅ 完美跨平台（基于ssh2库）
- ✅ 开箱即用，零额外配置

📖 SSH隧道详细文档

---

$3

解决混用 mongoose 和 monSQLize 时的 BSON 版本冲突问题。

`javascript
// ❌ 问题场景：mongoose (bson@4.x/5.x) + monSQLize (bson@6.x)
const dataFromMongoose = await MongooseModel.findOne({ ... }).lean();
await msq.collection('orders').insertOne(dataFromMongoose);
// 错误：Unsupported BSON version, bson types must be from bson 6.x.x

// ✅ monSQLize v1.1.1+ 自动处理
const dataFromMongoose = await MongooseModel.findOne({ ... }).lean();
await msq.collection('orders').insertOne(dataFromMongoose);
// 成功：自动将旧版本 ObjectId 转换为 bson@6.x
`

特性：
- ✅ 自动检测并转换来自其他 BSON 版本的 ObjectId
- ✅ 递归处理嵌套对象和数组
- ✅ 性能优化：无需转换时零拷贝
- ✅ 错误降级：转换失败不影响其他字段
- ✅ 完全透明：无需修改业务代码

兼容性：

| BSON 版本 | mongoose 版本 | 支持状态 |
|-----------|--------------|---------|
| bson@4.x | mongoose@5.x | ✅ 完全支持 |
| bson@5.x | mongoose@6.x | ✅ 完全支持 |
| bson@6.x | mongoose@7.x | ✅ 原生支持 |

📖 完整文档

---

$3

monSQLize 提供了一个轻量级的 Model 层，让你可以像使用 ORM 一样定义数据模型，同时保持 MongoDB 的灵活性。

> 📦 依赖说明: Model 层基于 schema-dsl 库实现 Schema 验证，已随 monsqlize 自动安装。

`javascript
const { Model } = require('monsqlize');

// 1. 定义 Model（集成 schema-dsl 验证）
Model.define('users', {
enums: {
role: 'admin|user|guest'
},
schema: function(dsl) {
return dsl({
username: 'string:3-32!',
email: 'email!',
role: this.enums.role.default('user'),
age: 'number:1-150'
});
},
options: {
timestamps: true, // 🆕 v1.0.3: 自动管理 createdAt/updatedAt
softDelete: true // 🆕 v1.0.3: 软删除（标记删除，支持恢复）
},
methods: (model) => ({
// 实例方法 - 注入到查询返回的文档对象
instance: {
isAdmin() {
return this.role === 'admin';
}
},
// 静态方法 - 挂载到 Model 实例
static: {
async findByEmail(email) {
return await model.findOne({ email });
}
}
}),
hooks: (model) => ({
// 生命周期钩子
insert: {
before: (ctx, docs) => {
// 自动添加时间戳
return { ...docs, createdAt: new Date() };
}
}
}),
indexes: [
{ key: { username: 1 }, unique: true },
{ key: { email: 1 }, unique: true }
]
});

// 2. 使用 Model
const db = new MonSQLize({ / ... / });
await db.connect();

const User = db.model('users');

// 自动 Schema 验证
const user = await User.insertOne({
username: 'john',
email: 'john@example.com',
age: 25
}); // ✅ 验证通过

// 使用实例方法
const admin = await User.findOne({ username: 'admin' });
console.log(admin.isAdmin()); // true

// 使用静态方法
const user = await User.findByEmail('john@example.com');

// 软删除（标记删除，可恢复）
await User.deleteOne({ _id: user._id });

// 查询（自动过滤已删除）
const users = await User.find({}); // 不包含已删除用户

// 查询包含已删除
const allUsers = await User.findWithDeleted({});

// 恢复已删除
await User.restore({ _id: user._id });
`

特性：
- ✅ Schema 验证（集成 schema-dsl）
- ✅ 自定义方法（instance + static）
- ✅ 生命周期钩子（before/after）
- ✅ 索引自动创建
- ✅ 自动时间戳（v1.0.3+）
- ✅ 软删除（v1.0.3+）
- ✅ 乐观锁版本控制（v1.0.3+）
- ✅ 关系定义和 populate（v1.2.0+） 🆕
- ✅ TypeScript 类型支持

#### 关系定义和 populate（v1.2.0+）🆕

轻松处理集合之间的关联关系，支持 one-to-one 和 one-to-many。

`javascript
// 1. 定义关系
Model.define('users', {
schema: (dsl) => dsl({
username: 'string!',
profileId: 'objectId'
}),
relations: {
// one-to-one: 用户 → 个人资料
profile: {
from: 'profiles', // 集合名
localField: 'profileId', // 本地字段
foreignField: '_id', // 外部字段
single: true // 返回类型
},
// one-to-many: 用户 → 文章列表
posts: {
from: 'posts',
localField: '_id',
foreignField: 'authorId',
single: false // 返回数组
}
}
});

// 2. 使用 populate
const user = await User.findOne({ username: 'john' })
.populate('profile') // 填充 profile
.populate('posts', { // 填充 posts
select: 'title content', // 只选择部分字段
match: { status: 'published' }, // 额外查询条件
sort: { createdAt: -1 }, // 排序
limit: 10 // 限制数量
});

// 3. 结果
{
_id: '...',
username: 'john',
profileId: '...',
profile: { // ← 自动填充
_id: '...',
bio: 'Software Engineer',
avatar: 'https://...'
},
posts: [ // ← 自动填充
{ _id: '...', title: 'Post 1', content: '...' },
{ _id: '...', title: 'Post 2', content: '...' }
]
}
`

支持的查询方法（全部 6 个）:
- ✅ find().populate() - 批量查询
- ✅ findOne().populate() - 单文档查询
- ✅ findByIds().populate() - 批量 ID 查询
- ✅ findOneById().populate() - 单 ID 查询
- ✅ findAndCount().populate() - 带计数查询
- ✅ findPage().populate() - 分页查询

特点:
- ✅ 极简配置（只需 4 个字段）
- ✅ 接近 MongoDB 原生（直接对应 $lookup）
- ✅ 批量查询优化（避免 N+1 问题）
- ✅ 支持链式调用
- ✅ 丰富的 populate 选项（select/sort/limit/skip/match）

📖 Relations 详细文档

注意：需要安装 schema-dsl 依赖：
`bash
npm install schema-dsl
`

📖 Model 层详细文档

---

� 进阶功能

$3

`javascript
// 实时监听订单变化
const watcher = orders.watch([
{ $match: { 'fullDocument.status': 'pending' } }
]);

watcher.on('change', (change) => {
console.log('新订单:', change.fullDocument);
// 触发通知、更新统计、失效缓存等
});

// ✅ 自动处理：重连、错误恢复、缓存失效
`

特性: 支持聚合管道过滤 · 断点续传 · 自动失效相关缓存

📖 完整文档 | 示例代码

---

$3

`javascript
// 高并发场景：100 个用户同时请求分页
const db = new MonSQLize({
countQueue: {
enabled: true, // 默认启用
concurrency: 8 // 同时最多 8 个 count
}
});

// ✅ 自动队列控制，防止 count 拖垮数据库
const result = await users.findPage({
query: { status: 'active' },
totals: { mode: 'async' } // 自动应用队列
});
`

效果: 数据库 CPU 从 100% → 30% · 其他查询不再超时

📖 完整文档

---

$3

`javascript
// jQuery 风格的链式调用
const result = await users
.find()
.filter({ age: { $gte: 18 } })
.sort({ createdAt: -1 })
.limit(10)
.cache(60000)
.exec();

// ✅ 代码更清晰、可读性更强
`

📖 完整文档 | 链式方法参考

---

$3

`javascript
// 启用版本控制
Model.define('products', {
schema: (dsl) => dsl({ name: 'string!', stock: 'number!' }),
options: { optimisticLock: true }
});

// 自动版本检查和更新
await Product.updateOne(
{ _id: productId, __v: 1 }, // 要求版本为 1
{ $inc: { stock: -1 }, $inc: { __v: 1 } } // 自动递增版本
);
// ❌ 如果版本不匹配（被其他请求修改），更新失败
`

📖 Model 层文档

---

$3

`javascript
// ✅ 支持 import/export
import MonSQLize from 'monsqlize';

const db = new MonSQLize({ / ... / });
await db.connect();

// 🎯 完美支持 TypeScript
import type { Collection, MonSQLizeConfig } from 'monsqlize';
`

📖 ESM 文档

---

�📊 性能测试报告

$3

- CPU: Intel i7-9700K
- 内存: 16GB
- 数据库: MongoDB 5.0
- 数据量: 100 万条

$3

| 场景 | 原生驱动 | monSQLize (缓存) | 提升倍数 |
|------|---------|------------------|---------|
| 热点查询 (findOne) | 10ms | 0.1ms | 100x ⚡ |
| 列表查询 (find) | 50ms | 0.5ms | 100x ⚡ |
| 复杂聚合 (aggregate) | 200ms | 2ms | 100x ⚡ |
| 批量插入 (10万条) | 30s | 1.2s | 25x ⚡ |

$3

- 电商场景: 85% (商品/用户查询)
- 内容平台: 75% (文章/评论查询)
- 社交应用: 80% (个人资料/动态)

结论: 在真实业务场景中，缓存命中率通常在 70~90%，性能提升 10~100 倍。

---

🎨 完整功能清单

$3 ✅ CRUD 操作 - find / findOne - insertOne / insertMany - updateOne / updateMany ⭐ (支持聚合管道 v1.0.8+) - deleteOne / deleteMany - replaceOne - findOneAndUpdate - findOneAndReplace - findOneAndDelete ✅ 聚合 & 查询 - aggregate - count / distinct - watch (Change Streams) - explain ✅ 索引管理 - createIndex / createIndexes - listIndexes - dropIndex / dropIndexes ✅ 事务支持 - withTransaction - startTransaction

$3 ✅ 企业级多连接池 (v1.0.8+) - ConnectionPoolManager - 5种智能选择策略 - 实时健康检查 - 自动故障转移 - 完整统计收集 ✅ Saga 分布式事务 (v1.1.0 计划) - 跨服务事务（设计完成） - 自动补偿机制（设计完成） - 状态跟踪（设计完成） - 超时和重试（设计完成） ✅ 智能缓存 - TTL 过期策略 - LRU 淘汰策略 - 自动失效机制 - 并发去重 - 多层缓存 (内存+Redis) ✅ 便利方法 - findOneById - findByIds - upsertOne - incrementOne - findAndCount ✅ 性能优化 - insertBatch - 批量插入优化 - deleteBatch - 批量删除（流式+进度监控） - updateBatch - 批量更新（流式+进度监控） - 只读事务优化 - Count 队列控制 - 连接池管理 ✅ 分布式支持 - Redis 广播缓存失效 - 分布式锁 - 多实例一致性

$3 ✅ 运维监控 - 慢查询日志（支持持久化存储）🆕 - 性能指标统计 - 健康检查 - 缓存命中率监控 ✅ 深度分页 - 游标分页 - 异步总数统计 - 书签管理 - 跳页优化 ✅ 数据库管理 - 跨库访问 - Schema 验证 - 集合管理 - 数据库命令 ✅ 开发体验 - TypeScript 支持 - 链式调用 API ⭐ - ESM/CommonJS 双模式 - ObjectId 自动转换 ⭐ - 77% 测试覆盖率

---

🆚 与 MongoDB 原生驱动对比

特性	MongoDB 原生	monSQLize
API 兼容性	✅ 原生	✅ 100% 兼容原生，无需学习新 API
智能缓存	❌ 需要自己实现	✅ 内置 TTL/LRU，开箱即用，10~100倍提升
性能	⭐⭐⭐ 基准性能	⭐⭐⭐⭐⭐ 缓存命中时性能提升 10~100 倍
事务支持	⭐⭐ 需要手动管理	⭐⭐⭐⭐⭐ 自动管理生命周期，优化只读操作
分布式部署	❌ 缓存不一致	✅ Redis 广播自动同步，保证一致性
便利方法	❌ 需要自己封装	✅ findOneById、findByIds、upsertOne 等
运维监控	⚠️ 需要额外配置	✅ 慢查询日志、性能统计，开箱即用
学习成本	⭐⭐⭐ MongoDB 语法	⭐ 零学习成本，API 完全一致
迁移成本	-	⭐ 只需修改初始化代码，业务代码不变

$3

✅ 适合场景：
- 高并发读取场景（商品详情、用户信息）
- 需要缓存但不想自己实现
- 多实例部署需要缓存一致性
- 希望零学习成本提升性能

⚠️ 不适合场景：
- 纯写入应用（缓存作用有限）
- 实时性要求极高（每次必查最新）
- 简单应用，流量不大（原生驱动足够）

---

🚀 快速迁移指南

$3

`javascript
// ❌ 原来的代码
const { MongoClient } = require('mongodb');
const client = await MongoClient.connect('mongodb://localhost:27017');
const db = client.db('mydb');
const users = db.collection('users');

// ✅ 迁移后的代码（只需改 3 行）
const MonSQLize = require('monsqlize'); // 1. 引入 monSQLize
const db = new MonSQLize({ // 2. 修改初始化
type: 'mongodb',
config: { uri: 'mongodb://localhost:27017/mydb' },
cache: { enabled: true } // 3. 启用缓存
});
await db.connect();
const users = db.collection('users');

// 🎉 后续所有代码不需要改动，性能提升 10~100 倍！
const user = await users.findOne({ email }); // 完全一样的 API
`

$3

`javascript
// ✅ 可以混用原生驱动和 monSQLize
const nativeClient = await MongoClient.connect('...');
const monsqlize = new MonSQLize({ cache: { enabled: true } });

// 性能敏感的查询用 monSQLize（启用缓存）
const hotData = await monsqlize.collection('products').find({}, { cache: 60000 });

// 简单查询用原生驱动
const coldData = await nativeClient.db('mydb').collection('logs').find({});
`

---

📖 完整文档

$3

- 📖 完整 API 文档索引
- 📖 MongoDB 原生 vs monSQLize 对比
- 📖 事务使用指南
- 📖 业务级分布式锁 🆕 v1.4.0
- 📖 SSH隧道使用指南 🆕 v1.3+
- 📖 分布式部署指南
- 📖 性能优化指南

$3

CRUD 操作:
- find | findOne | findPage
- insertOne | insertMany | insertBatch
- updateOne | updateMany | updateBatch | replaceOne
- deleteOne | deleteMany | deleteBatch

Model 层:
- Model API 文档 - Schema 验证、自定义方法、生命周期钩子

便利方法:
- findOneById | findByIds
- upsertOne | incrementOne | findAndCount

其他功能:
- 索引管理 | 聚合查询
- 缓存系统 | 链式调用

$3

- 📁 完整示例代码目录 - 50+ 可运行示例

---

🌍 兼容性

| 环境 | 支持版本 |
|------|---------|
| Node.js | 16.x, 18.x, 20.x, 21.x |
| MongoDB | 4.4+, 5.x, 6.x, 7.x |
| MongoDB Driver | 4.x, 5.x, 6.x, 7.x |
| 模块系统 | CommonJS, ESM |

查看完整兼容性矩阵

---

🗺️ 产品路线图

$3

- ✅ 业务级分布式锁
- ✅ 智能缓存系统
- ✅ 事务优化
- ✅ 便利方法
- ✅ 分布式支持
- ✅ Model 层（v1.0.3）- Schema 验证、自定义方法、生命周期钩子

$3

- 🔄 查询分析器
- 🔄 自动索引建议
- 🔄 数据迁移工具
- 🔄 GraphQL 支持
- 🔄 Model 关系（relations）完善

$3

- 🔮 统一 API 支持 MySQL
- 🔮 统一 API 支持 PostgreSQL
- 🔮 完整 ORM 功能
- 🔮 数据同步中间件

---

🤝 贡献指南

我们欢迎所有形式的贡献！

- 🐛 提交 Bug
- 💡 提出新功能
- 📖 改进文档
- 💻 提交代码

$3

`bash

克隆仓库

git clone https://github.com/vextjs/monSQLize.git
cd monSQLize

安装依赖

npm install

运行测试

npm test

运行基准测试

npm run benchmark
`

---

📄 许可证

MIT License

---

💬 社区与支持

- 📧 Email: support@monsqlize.dev
- 💬 Issues: GitHub Issues
- 📖 文档: 完整文档
- 🌟 Star: 如果觉得有用，请给我们一个 Star ⭐

---

🎉 快速链接