COMPATIBILITY.md

monSQLize 兼容性矩阵

最后更新: 2025-01-02
版本: 1.0.0

---

📑 目录

• 📊 概述
• 🟢 Node.js 版本支持
• 🔵 MongoDB Driver 版本支持
• 🟠 MongoDB Server 版本支持
• 🧪 组合兼容性矩阵
• 📦 依赖版本
• 🚀 测试矩阵
• 📖 使用建议
• ⚠️ 已知限制
• 🔍 如何检测当前环境
• 📝 更新日志
• 🤝 贡献
• 📞 支持

---

�📊 概述

本文档说明 monSQLize 支持的 Node.js、MongoDB Driver 和 MongoDB Server 版本范围。

---

🟢 Node.js 版本支持

Node.js 版本	支持状态	测试状态	备注
16.x	✅ 支持	✅ 已测试	最低支持版本（>=16.0.0），LTS
18.x	✅ 完全支持	✅ 已测试	LTS（推荐）
20.x	✅ 完全支持	✅ 已测试	LTS（推荐）
22.x	✅ 支持	✅ 已测试	最新版本
14.x	❌ 不支持	-	已移除支持
12.x	❌ 不支持	-	已 EOL

Node.js 特性支持

特性	Node.js 版本要求	monSQLize 支持
async/await	7.6+	✅ 全版本支持
Promise.allSettled	12.9+	✅ 全版本支持
可选链 (?.)	14.0+	✅ 全版本支持
Worker Threads	16.0+	✅ 全版本支持
空值合并 (??)	14.0+	✅ 全版本支持
Worker Threads	16.0+	✅ 条件支持（自动检测）
performance.now()	8.5+	✅ 全版本支持

---

🔵 MongoDB Driver 版本支持

Driver 版本	支持状态	测试状态	已知问题	推荐度
4.x (4.17.2)	⚠️ 部分支持	✅ 已测试	连接选项必需设置	⭐⭐
5.x (5.9.2)	✅ 完全支持	✅ 已测试	findOneAnd* 返回格式不同	⭐⭐⭐
6.x (6.17.0)	✅ 完全支持	✅ 已测试	无	⭐⭐⭐⭐⭐ 推荐
7.x	🔶 实验性	⏸️ 待测试	待验证	⭐⭐⭐
3.x	❌ 不支持	-	太旧	-

Driver 4.x 使用注意事项

Driver 4.x 需要显式设置连接选项：

const MonSQLize = require('monsqlize');

const msq = new MonSQLize({
  uri: 'mongodb://localhost:27017',
  config: {
    // Driver 4.x 必需的选项
    useNewUrlParser: true,
    useUnifiedTopology: true,
    poolSize: 10,
  }
});

Driver 5.x vs 6.x 差异

findOneAnd 返回值变化*（最重要）：

// Driver 5.x: 返回完整元数据
const result = await collection.findOneAndUpdate(filter, update);
console.log(result);
// { value: {...}, ok: 1, lastErrorObject: {...} }

// Driver 6.x: 默认返回文档
const result = await collection.findOneAndUpdate(filter, update);
console.log(result);
// { _id: ..., name: "Alice" }  // 直接返回文档

// Driver 6.x: 获取完整元数据
const result = await collection.findOneAndUpdate(filter, update, {
  includeResultMetadata: true
});
console.log(result);
// { value: {...}, ok: 1 }

monSQLize 的处理方式:

• ✅ 自动检测驱动版本
• ✅ 统一返回格式（向后兼容）
• ✅ 用户无需关心差异

---

🟠 MongoDB Server 版本支持

Server 版本	支持状态	测试状态	特性限制	推荐度
4.4	✅ 支持	✅ 已测试	基础功能，部分聚合操作符不可用	⭐⭐⭐
5.0	✅ 完全支持	✅ 已测试	支持时间序列集合	⭐⭐⭐⭐
6.0	✅ 完全支持	✅ 已测试	支持加密字段	⭐⭐⭐⭐⭐ 推荐
7.0	✅ 完全支持	✅ 已测试	最新特性	⭐⭐⭐⭐⭐
4.0-4.2	⚠️ 可能兼容	⏸️ 未测试	未验证	⭐⭐
3.x	❌ 不支持	-	太旧	-

MongoDB Server 特性支持

特性	Server 版本要求	monSQLize 支持
事务	4.0+ (副本集)	✅ 完全支持
多文档事务	4.0+ (副本集), 4.2+ (分片)	✅ 完全支持
通配符索引	4.2+	✅ 完全支持
$function 操作符	4.4+	✅ 自动检测
$setWindowFields	5.0+	✅ 自动检测
时间序列集合	5.0+	✅ 完全支持
加密字段	6.0+	✅ 完全支持

---

🧪 组合兼容性矩阵

推荐组合 ⭐⭐⭐⭐⭐

Node.js	MongoDB Driver	MongoDB Server	状态	适用场景
20.x	6.17.0	6.0 / 7.0	✅ 完美	生产环境（推荐）
18.x	6.17.0	6.0 / 7.0	✅ 完美	生产环境（推荐）
20.x	6.17.0	5.0	✅ 优秀	生产环境
18.x	5.9.2	5.0	✅ 良好	兼容旧项目

支持的组合 ⭐⭐⭐

Node.js	MongoDB Driver	MongoDB Server	状态	适用场景
16.x	6.17.0	6.0	✅ 支持	旧项目升级
14.x	5.9.2	4.4	✅ 支持	最低兼容配置
22.x	6.17.0	7.0	✅ 支持	尝鲜

不推荐的组合 ⚠️

Node.js	MongoDB Driver	MongoDB Server	状态	原因
14.x	4.17.2	任意	⚠️ 勉强	Driver 4.x 配置复杂
任意	7.x	任意	🔶 未知	Driver 7.x 待全面测试

不支持的组合 ❌

Node.js	MongoDB Driver	MongoDB Server	状态	原因
12.x	任意	任意	❌ 不支持	Node.js 12 已 EOL
任意	3.x	任意	❌ 不支持	Driver 3.x 太旧
任意	任意	3.x	❌ 不支持	Server 3.x 太旧

---

📦 依赖版本

核心依赖

{
  "dependencies": {
    "mongodb": "^6.17.0"
  },
  "optionalDependencies": {
    "ioredis": "^5.8.2"
  }
}

开发依赖

{
  "devDependencies": {
    "mongodb-memory-server": "^10.1.2",
    "mocha": "^11.7.5",
    "chai": "^6.2.1"
  }
}

---

🚀 测试矩阵

CI/CD 测试覆盖

核心测试（每次 PR）

• Node.js: 18.x, 20.x
• MongoDB Driver: 6.17.0
• OS: Ubuntu, Windows

完整测试（merge 到 main / 每日定时）

• Node.js: 14.x, 16.x, 18.x, 20.x, 22.x
• MongoDB Driver: 4.17.2, 5.9.2, 6.17.0
• OS: Ubuntu
• 约 15 种组合

---

📖 使用建议

新项目

推荐配置:
- Node.js 20.x (LTS)
- MongoDB Driver 6.17.0
- MongoDB Server 6.0 或 7.0

升级现有项目

从 Driver 4.x 升级到 6.x

1. 更新 package.json: "mongodb": "^6.17.0"
2. 移除旧的连接选项（useNewUrlParser 等）
3. 运行测试验证兼容性
4. monSQLize 会自动适配差异

从 Node.js 14 升级到 18/20

1. 更新 Node.js 版本
2. 更新依赖: npm update
3. 运行完整测试套件
4. 无需修改 monSQLize 使用方式

---

⚠️ 已知限制

1. Driver 4.x 连接选项

问题: 必须显式设置 useNewUrlParser 等选项
影响: 配置复杂
解决: 使用 version-adapter 提供的推荐选项

2. findOneAnd* 返回值差异

问题: Driver 5.x 和 6.x 返回格式不同
影响: 可能破坏依赖返回值的代码
解决: monSQLize 自动统一格式

3. Worker Threads 仅 Node.js 16+

问题: Node.js 14/15 不支持 Worker Threads
影响: 部分并发特性不可用
解决: 自动检测并跳过

---

🔍 如何检测当前环境

使用 monSQLize 的版本适配器

const versionAdapter = require('monsqlize/test/utils/version-adapter');

// 生成完整报告
const report = versionAdapter.generateReport();
console.log(report);

// 输出示例:
// {
//   node: {
//     version: 'v20.19.4',
//     major: 20,
//     features: {
//       workerThreads: true,
//       performanceNow: true,
//       promiseAllSettled: true
//     }
//   },
//   mongodbDriver: {
//     version: '6.17.0',
//     major: 6,
//     features: {
//       simplifiedFindOneAnd: true,
//       modernConnectionOptions: true
//     }
//   },
//   compatibility: {
//     recommendedConnectionOptions: {...},
//     needsFindOneAndAdaptation: true
//   }
// }

---

📝 更新日志

2025-01-02

• ✅ 初始版本
• ✅ 支持 Node.js 14-22
• ✅ 支持 MongoDB Driver 4.x-6.x
• ✅ 支持 MongoDB Server 4.4-7.0
• ✅ 添加版本适配器
• ✅ 添加 CI/CD 测试矩阵

---

🤝 贡献

发现兼容性问题？请提交 Issue 或 PR：

• GitHub Issues: https://github.com/vextjs/monSQLize/issues
• 兼容性报告模板: [ISSUE_TEMPLATE/compatibility.md]

---

📞 支持

• 📖 文档: docs/
• 💬 讨论: GitHub Discussions
• 🐛 Bug Report: GitHub Issues

---

维护者: vext.js Team
许可证: MIT