monsqlize 1.2.1 → 1.2.3

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # 变更日志 (CHANGELOG)
 
 > **说明**: 版本概览摘要，详细变更见 [changelogs/](./changelogs/) 目录  
-> **最后更新**: 2026-04-13
+> **最后更新**: 2026-04-26
 
 ---
 
@@ -9,6 +9,8 @@
 
 | 版本 | 日期 | 变更摘要 | 详细 |
 |------|------|---------|------|
+| [v1.2.3](./changelogs/v1.2.3.md) | 2026-04-26 | 🐛 **Bug Fix**：`model()` 方法修复注册 key 直接作为 MongoDB 集合名的问题，优先读 `definition.collection > definition.name`，注册 key 仅作 fallback，向后兼容 | [查看](./changelogs/v1.2.3.md) |
+| [v1.2.2](./changelogs/v1.2.2.md) | 2026-04-24 | 🆕 **新功能**：Model 数据源绑定 — `connection: { pool?, database? }` 支持 Model 绑定指定连接池和/或数据库，四种组合路由，向后兼容；🐛 **Bug Fix**：修复 `Model._clear()` 导致 `msq.model()` 实例缓存失效失效，populate 关系丢失问题 | [查看](./changelogs/v1.2.2.md) |
 | [v1.2.1](./changelogs/v1.2.1.md) | 2026-04-13 | 🐛 **Bug 修复**：`msq.model()` 实例缓存 + 索引去重 + 死代码清理 + `types/monsqlize.ts` 补全 `model()` / `collection()` 类型 | [查看](./changelogs/v1.2.1.md) |
 | [v1.2.0](./changelogs/v1.2.0.md) | 2026-04-13 | 🐛 **Bug 修复 + 新功能**：`findPage` 正式支持 `projection` 投影参数（修复静默忽略问题）+ 有效投影策略自动保护游标排序字段 + 8 个测试用例 | [查看](./changelogs/v1.2.0.md) |
 | [v1.1.9](./changelogs/v1.1.9.md) | 2026-04-02 | 🚨 **P1 Bug 修复**：MultiLevelCache L2→L1 回填 TTL 缺失（null 永久驻留 L1）+ 新增 `backfillLocalTTL` 配置 + Redis `getWithTTL` 方法 + 14 个回归测试 | [查看](./changelogs/v1.1.9.md) |

package/README.md

@@ -314,78 +314,102 @@ await msq.close();
 
 > **📦 依赖说明**: Model 层需要 `schema-dsl` 包支持（已随 monsqlize 自动安装，无需额外操作）
 
+Model 层有两种使用方式，二者**互斥**，选其一即可：
+
+| 方式 | 适合场景 |
+|------|---------|
+| **手动注册**（`Model.define()`）| 少量 Model、测试环境、需要精确控制加载顺序 |
+| **自动加载**（`models:` 配置项）| 生产环境，Model 文件统一放在一个目录下 |
+
+#### 方式一：手动注册
+
 ```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）
+// 1. 先在 connect() 之前调用 Model.define() 注册所有 Model
 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?'                // 可选字符串
+        username: 'string:3-32!',
+        email: 'email!',
+        password: 'string:6-!',
+        age: 'number:0-120'
     }),
-    
-    // Relations（关联查询）
     relations: {
-        posts: {  // 用户的文章
-            from: 'posts',
-            localField: '_id',
-            foreignField: 'userId',
-            single: false
-        }
+        posts: { from: 'posts', localField: '_id', foreignField: 'userId', single: false }
     },
-    
-    // Hooks（生命周期钩子）
     hooks: (model) => ({
-        insert: {
-            before: async (ctx, doc) => {
-                doc.createdAt = new Date();  // 自动添加时间戳
-                return doc;
-            }
-        }
+        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 });
-            }
-        }
+        instance: { checkPassword(password) { return this.password === password; } },
+        static: { async findByUsername(username) { return await model.findOne({ username }); } }
     })
 });
 
 Model.define('posts', {
-    schema: (dsl) => dsl({
-        title: 'string:1-200!',
-        content: 'string!',
-        userId: 'string!'
-    })
+    schema: (dsl) => dsl({ title: 'string:1-200!', content: 'string!', userId: 'string!' })
 });
 
-// 2. 使用 Model
+// 2. 创建实例并连接
+const msq = new MonSQLize({
+    type: 'mongodb',
+    databaseName: 'mydb',
+    config: { uri: 'mongodb://localhost:27017' },
+    cache: { enabled: true }
+});
+await msq.connect();
+
+// 3. 获取 Model 并使用
 const User = msq.model('users');
+```
+
+#### 方式二：自动加载（推荐用于生产环境）
+
+将每个 Model 单独放在一个文件里，`connect()` 时自动扫描目录加载，无需手动 `Model.define()`：
+
+```javascript
+// app.js
+const path = require('path');
+
+const msq = new MonSQLize({
+    type: 'mongodb',
+    databaseName: 'mydb',
+    config: { uri: 'mongodb://localhost:27017' },
+    // 推荐用绝对路径，避免受 process.cwd() 影响
+    models: path.join(__dirname, 'models')
+    // 或完整配置：
+    // models: { path: path.join(__dirname, 'models'), pattern: '*.model.js', recursive: true }
+});
+
+await msq.connect();            // ← 自动扫描 models/*.model.{js,ts,mjs,cjs}
+
+const User = msq.model('users'); // 直接使用，无需 Model.define()
+```
+
+> 相对路径（如 `'./models'`）以 `process.cwd()` 为基准，即 Node.js 进程的启动目录。为避免歧义，推荐始终使用 `path.join(__dirname, 'models')` 这样的绝对路径。
+
+```javascript
+// models/user.model.js  ← 每个 Model 独立一个文件
+module.exports = {
+    name: 'users',              // 集合名称（必需）
+    schema: (dsl) => dsl({
+        username: 'string:3-32!',
+        email: 'email!'
+    }),
+    methods: (model) => ({
+        static: {
+            async findByUsername(username) { return await model.findOne({ username }); }
+        }
+    })
+};
+```
+
+> 详细说明（完整配置项、文件格式、错误处理）见 [docs/model.md — Model 自动加载](./docs/model.md#model-自动加载v107)
+
+#### 两种方式共同的后续操作
+
+```javascript
 
 // ✅ Schema 验证自动生效
 try {
@@ -432,6 +456,35 @@ await User.insertOne(doc, { skipValidation: true });
 - ✅ **Relations** - 定义表关系（hasOne/hasMany/belongsTo）
 - ✅ **自定义方法** - instance 方法注入到文档，static 方法挂载到 Model
 - ✅ **自动缓存** - Populate 查询结果也会缓存
+- ✅ **数据源绑定** - `connection: { pool?, database? }` 绑定指定连接池和/或数据库（v1.2.2+）
+
+**数据源绑定示例（v1.2.2+）**：
+
+```js
+// 在多连接池场景中，将 Model 绑定到指定的连接池 + 数据库
+const msq = new MonSQLize({
+  uri: 'mongodb://localhost:27017',
+  databaseName: 'main_db',
+  pools: [{ name: 'analytics', uri: 'mongodb://analytics-host:27017' }]
+});
+
+// 绑定到不同数据库（使用默认连接池）
+Model.define('AuditLog', {
+  schema: (dsl) => dsl({ action: 'string!', userId: 'string!' }),
+  connection: { database: 'audit_db' }
+});
+
+// 绑定到不同连接池 + 不同数据库
+Model.define('AnalyticsReport', {
+  schema: (dsl) => dsl({ reportId: 'string!', data: 'object' }),
+  connection: { pool: 'analytics', database: 'reports_db' }
+});
+
+// 调用时自动路由，无需手动切换
+const AuditLogModel  = msq.model('AuditLog');       // → audit_db（默认池）
+const ReportModel    = msq.model('AnalyticsReport'); // → reports_db（analytics 池）
+const UserModel      = msq.model('users');           // → main_db（原逻辑，向后兼容）
+```
 
 📖 **详细文档**：[Model 层完整指南](./docs/model.md) | [Populate API](./docs/populate.md) | [Hooks API](./docs/hooks.md) | [Schema 验证](./docs/model.md#schema-验证)
 
@@ -1412,27 +1465,27 @@ import type { Collection, MonSQLizeConfig } from 'monsqlize';
 ### 📦 MongoDB 原生功能
 
 ✅ **CRUD 操作**
-- find / findOne
-- insertOne / insertMany
-- updateOne / updateMany ⭐ (支持聚合管道 v1.0.8+)
-- deleteOne / deleteMany
-- replaceOne
-- findOneAndUpdate
-- findOneAndReplace
-- findOneAndDelete
+- [find](./docs/find.md) / [findOne](./docs/findOne.md)
+- [insertOne](./docs/insert-one.md) / [insertMany](./docs/insert-many.md)
+- [updateOne](./docs/update-one.md) / [updateMany](./docs/update-many.md) ⭐ (支持聚合管道 v1.0.8+)
+- [deleteOne](./docs/delete-one.md) / [deleteMany](./docs/delete-many.md)
+- [replaceOne](./docs/replace-one.md)
+- [findOneAndUpdate](./docs/find-one-and-update.md)
+- [findOneAndReplace](./docs/find-one-and-replace.md)
+- [findOneAndDelete](./docs/find-one-and-delete.md)
 
 ✅ **聚合 & 查询**
-- aggregate
-- count / distinct
-- watch (Change Streams)
-- explain
+- [aggregate](./docs/aggregate.md)
+- [count](./docs/count.md) / [distinct](./docs/distinct.md)
+- [watch (Change Streams)](./docs/watch.md)
+- [explain](./docs/explain.md)
 
 ✅ **索引管理**
 - createIndex / createIndexes
 - listIndexes
 - dropIndex / dropIndexes
 
-✅ **事务支持**
+✅ **[事务支持](./docs/transaction.md)**
 - withTransaction
 - startTransaction
 
@@ -1441,44 +1494,44 @@ import type { Collection, MonSQLizeConfig } from 'monsqlize';
 
 ### 🚀 增强功能
 
-✅ **企业级多连接池** (v1.0.8+)
+✅ **[企业级多连接池](./docs/multi-pool.md)** (v1.0.8+)
 - ConnectionPoolManager
 - 5种智能选择策略
 - 实时健康检查
 - 自动故障转移
 - 完整统计收集
 
-✅ **Saga 分布式事务** (v1.1.0 计划)
+✅ **[Saga 分布式事务](./docs/saga-transaction.md)** (v1.1.0 计划)
 - 跨服务事务（设计完成）
 - 自动补偿机制（设计完成）
 - 状态跟踪（设计完成）
 - 超时和重试（设计完成）
 
-✅ **智能缓存**
+✅ **[智能缓存](./docs/cache.md)**
 - TTL 过期策略
 - LRU 淘汰策略
 - 自动失效机制
 - 并发去重
-- 多层缓存 (内存+Redis)
+- [多层缓存 (内存+Redis)](./docs/cache-implementation.md)
 
 ✅ **便利方法**
-- findOneById
-- findByIds
-- upsertOne
-- incrementOne
-- findAndCount
+- [findOneById](./docs/find-one-by-id.md)
+- [findByIds](./docs/find-by-ids.md)
+- [upsertOne](./docs/upsert-one.md)
+- [incrementOne](./docs/increment-one.md)
+- [findAndCount](./docs/find-and-count.md)
 
 ✅ **性能优化**
-- insertBatch - 批量插入优化
-- deleteBatch - 批量删除（流式+进度监控）
-- updateBatch - 批量更新（流式+进度监控）
+- [insertBatch](./docs/insertBatch.md) - 批量插入优化
+- [deleteBatch](./docs/deleteBatch.md) - 批量删除（流式+进度监控）
+- [updateBatch](./docs/updateBatch.md) - 批量更新（流式+进度监控）
 - 只读事务优化
-- Count 队列控制
+- [Count 队列控制](./docs/count-queue.md)
 - 连接池管理
 
-✅ **分布式支持**
+✅ **[分布式支持](./docs/distributed-deployment.md)**
 - Redis 广播缓存失效
-- 分布式锁
+- [分布式锁](./docs/business-lock.md)
 - 多实例一致性
 
 </td>
@@ -1487,28 +1540,28 @@ import type { Collection, MonSQLizeConfig } from 'monsqlize';
 ### 🛠️ 企业级特性
 
 ✅ **运维监控**
-- 慢查询日志（支持持久化存储）🆕
+- [慢查询日志](./docs/slow-query-log.md)（支持持久化存储）🆕
 - 性能指标统计
 - 健康检查
 - 缓存命中率监控
 
-✅ **深度分页**
+✅ **[深度分页](./docs/findPage.md)**
 - 游标分页
 - 异步总数统计
-- 书签管理
+- [书签管理](./docs/bookmarks.md)
 - 跳页优化
 
 ✅ **数据库管理**
 - 跨库访问
-- Schema 验证
-- 集合管理
+- [Schema 验证](./docs/model.md)
+- [集合管理](./docs/collection-management.md)
 - 数据库命令
 
 ✅ **开发体验**
 - TypeScript 支持
-- 链式调用 API ⭐
+- [链式调用 API](./docs/chaining-api.md) ⭐
 - ESM/CommonJS 双模式
-- ObjectId 自动转换 ⭐
+- [ObjectId 自动转换](./docs/objectid-auto-convert.md) ⭐
 - 77% 测试覆盖率
 
 </td>

package/index.d.ts

@@ -178,6 +178,7 @@ declare module 'monsqlize' {
     export import DefaultValue = Model.DefaultValue;
     export import HookContext = Model.HookContext;
     export import ValidationResult = Model.ValidationResult;
+    export import ModelConnection = Model.ModelConnection;
     export import ModelDefinition = Model.ModelDefinition;
     export import RelationConfig = Model.RelationConfig;
     export import PopulateConfig = Model.PopulateConfig;

package/lib/index.js

@@ -737,8 +737,18 @@ module.exports = class {
     // 获取 Model 定义
     const modelDef = Model.get(collectionName);
 
-    // 获取 collection 实例
-    const collection = this.dbInstance.collection(collectionName);
+    // [v1.2.3 patch] 实际 MongoDB 集合名可能不同于注册 key
+    // 优先读 definition.collection > definition.name > key（fallback，向后兼容）
+    const actualCollectionName =
+      modelDef.definition.collection ||
+      modelDef.definition.name ||
+      collectionName;
+
+    // 获取 collection 实例（v1.2.2+ 支持 connection 路由）
+    const connection = modelDef.definition.connection;
+    const collection = (connection && (connection.pool || connection.database))
+      ? this._resolveModelCollection(actualCollectionName, connection)
+      : this.dbInstance.collection(actualCollectionName);
 
     // 创建 ModelInstance 并缓存
     const instance = new Model.ModelInstance(collection, modelDef.definition, this);
@@ -749,6 +759,55 @@ module.exports = class {
     return instance;
   }
 
+  /**
+   * 解析 Model 绑定的 collection（内部方法）
+   *
+   * 根据 Model 定义中的 connection 配置，将请求路由到正确的连接池和数据库。
+   *
+   * 四种组合：
+   *   1. pool + database → 指定池、指定数据库
+   *   2. pool 只配置  → 指定池、实例默认 databaseName
+   *   3. database 只配置 → 默认连接池、指定数据库
+   *   4. 均未配置   → 原逻辑（此方法不会被调用）
+   *
+   * @private
+   * @param {string} collectionName - 集合名称
+   * @param {{ pool?: string, database?: string }} connection - Model 的 connection 配置
+   * @returns {Object} monSQLize 包装 collection 对象
+   * @since v1.2.2
+   */
+  _resolveModelCollection(collectionName, connection) {
+    const poolName = connection.pool;
+    const dbName   = connection.database || this.databaseName;
+
+    if (poolName) {
+      if (!this._poolManager) {
+        const err = new Error(
+          `Model '${collectionName}' requires pool '${poolName}' but no pools are configured. ` +
+          `Add 'pools' to MonSQLize constructor options.`
+        );
+        err.code = 'NO_POOL_MANAGER';
+        throw err;
+      }
+
+      const client = this._poolManager._getPool(poolName);
+      if (!client) {
+        const availablePools = this._poolManager.getPoolNames().join(', ');
+        const err = new Error(
+          `Pool '${poolName}' not found. Available pools: [${availablePools}]`
+        );
+        err.code = 'POOL_NOT_FOUND';
+        throw err;
+      }
+
+      // 指定池 + 数据库：通过 adapter 的 collectionFromClient 复用包装逻辑
+      return this._adapter.collectionFromClient(client, dbName, collectionName);
+    }
+
+    // 只切换数据库，用默认连接
+    return this.dbInstance.db(dbName).collection(collectionName);
+  }
+
   /**
    * 获取集合实例（代理方法）
    *

package/lib/model/index.js

@@ -160,6 +160,11 @@ class Model {
         this._validateOptions(definition.options);
       }
 
+      // ========== 验证 connection 配置（v1.2.2+）==========
+      if (definition.connection) {
+        this._validateConnection(definition.connection);
+      }
+
       // ========== 解析 timestamps 配置 ==========
       const timestampsConfig = this._parseTimestampsConfig(
         definition.options?.timestamps,
@@ -222,6 +227,37 @@ class Model {
     }
   }
 
+  /**
+   * 验证 connection 配置
+   *
+   * @private
+   * @param {Object} connection - connection 配置对象
+   * @throws {Error} 配置不合法时抛出错误
+   *
+   * @since v1.2.2
+   */
+  static _validateConnection(connection) {
+    if (!connection || typeof connection !== 'object') {
+      return;
+    }
+
+    if (connection.pool !== undefined) {
+      if (typeof connection.pool !== 'string' || connection.pool.trim() === '') {
+        const err = new Error('connection.pool must be a non-empty string');
+        err.code = 'INVALID_MODEL_DEFINITION';
+        throw err;
+      }
+    }
+
+    if (connection.database !== undefined) {
+      if (typeof connection.database !== 'string' || connection.database.trim() === '') {
+        const err = new Error('connection.database must be a non-empty string');
+        err.code = 'INVALID_MODEL_DEFINITION';
+        throw err;
+      }
+    }
+  }
+
   /**
    * 验证 options 配置
    * @private
@@ -454,8 +490,12 @@ class Model {
    * @private
    */
   static _clear() {
+    // 将所有已注册名标记为需要缓存失效，让 msq.model() 重建 ModelInstance
+    for (const name of this._registry.keys()) {
+      this._redefinedNames.add(name);
+    }
     this._registry.clear();
-    this._redefinedNames.clear();
+    // 注意：不清除 _redefinedNames，确保 msq 实例缓存能感知本次 clear
   }
 }
 

package/lib/mongodb/index.js

@@ -336,6 +336,31 @@ module.exports = class {
         };
     }
 
+    /**
+     * 从指定 MongoClient 创建包装 collection（用于多连接池 Model 绑定场景）
+     *
+     * 当 Model 定义了 `connection.pool` 时，`msq.model()` 会调用此方法，
+     * 将指定连接池的 MongoClient 传入，复用现有 collection() 的完整包装逻辑
+     * （runner、缓存、慢查询等），避免重复实现。
+     *
+     * 线程安全说明：Node.js 单线程，临时替换 this.client 的同步操作无竞态风险。
+     *
+     * @param {import('mongodb').MongoClient} client - 指定连接池的 MongoClient 实例
+     * @param {string} databaseName - 数据库名称
+     * @param {string} collectionName - 集合名称
+     * @returns {Object} monSQLize 包装 collection 对象
+     * @since v1.2.2
+     */
+    collectionFromClient(client, databaseName, collectionName) {
+        const originalClient = this.client;
+        this.client = client;
+        try {
+            return this.collection(databaseName, collectionName);
+        } finally {
+            this.client = originalClient;
+        }
+    }
+
     /**
  * 关闭连接并释放资源
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monsqlize",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "A lightweight MongoDB ORM with multi-level caching, transaction support, distributed features, Saga distributed transactions, unified expression system with 122 operators, and universal function caching (100% MongoDB support)",
   "main": "lib/index.js",
   "module": "index.mjs",
@@ -114,7 +114,7 @@
   },
   "dependencies": {
     "async-lock": "^1.4.1",
-    "mongodb": "^6.17.0",
+    "mongodb": "^6.21.0",
     "schema-dsl": "^1.2.4",
     "ssh2": "^1.17.0"
   }

package/types/model/definition.ts

@@ -106,5 +106,47 @@ export interface ModelDefinition<T = any> {
      * }
      */
     statics?: Record<string, (...args: any[]) => any>;
+
+    /**
+     * 数据源绑定配置（v1.2.2+）
+     *
+     * 声明此 Model 使用哪个连接池和/或数据库。
+     * 不配置时行为与 v1.2.1 完全相同（向后兼容）。
+     *
+     * @example
+     * // 绑定到指定连接池 + 数据库
+     * connection: { pool: 'analytics', database: 'reports_db' }
+     *
+     * @example
+     * // 只切换数据库（使用默认连接池）
+     * connection: { database: 'logs_db' }
+     *
+     * @since v1.2.2
+     */
+    connection?: ModelConnection;
+}
+
+/**
+ * Model 数据源绑定配置
+ *
+ * 声明 Model 使用哪个连接池（pool）和/或数据库（database）。
+ * 两个字段均为可选：
+ *   - 只指定 pool   → 使用该池 + 实例初始化时的 databaseName
+ *   - 只指定 database → 使用默认连接池 + 指定数据库
+ *   - 两者都指定    → 使用指定池 + 指定数据库
+ *   - 均不指定      → 与原来完全相同（向后兼容）
+ *
+ * @since v1.2.2
+ */
+export interface ModelConnection {
+    /**
+     * 连接池名称，须与 MonSQLize 构造函数 `pools[].name` 对应
+     */
+    pool?: string;
+
+    /**
+     * 数据库名称，不指定时使用实例初始化时的 `databaseName`
+     */
+    database?: string;
 }