monsqlize 1.0.0

package/lib/mongodb/writes/result-handler.js

@@ -0,0 +1,236 @@
+/**
+ * findOneAnd* 操作返回值处理工具
+ * 统一处理 MongoDB 驱动返回值的各种边界情况
+ *
+ * **重要说明 - MongoDB 驱动版本兼容性**
+ *
+ * 本模块专门处理 MongoDB Node.js 驱动在不同版本间的 API 差异：
+ *
+ * - **MongoDB 驱动 6.x** (当前支持):
+ *   - `findOneAnd*` 方法默认直接返回文档对象
+ *   - 需要显式传递 `includeResultMetadata: true` 才返回完整元数据
+ *
+ * - **MongoDB 驱动 5.x 及更早版本**:
+ *   - `findOneAnd*` 方法默认返回 `{ value, ok, lastErrorObject }` 格式
+ *
+ * **兼容性保证**:
+ * - 本模块会自动检测和处理驱动返回值格式的差异
+ * - monSQLize 的公共 API 行为保持一致，用户无需关心驱动版本
+ * - 如果未来驱动版本再次变更，仅需修改本模块即可
+ *
+ * **维护建议**:
+ * - 升级 MongoDB 驱动前，务必运行完整测试套件
+ * - 关注 MongoDB 驱动的 CHANGELOG，特别是 `findOneAnd*` 方法的变更
+ * - 如有疑问，参考技术分析报告：`analysis-reports/2025-11-17-mongodb-driver-6x-compatibility-FINAL.md`
+ *
+ * @module result-handler
+ * @since 2025-11-17
+ */
+
+// MongoDB 驱动版本检测（用于诊断和警告）
+let _driverVersionChecked = false;
+let _detectedDriverMajorVersion = null;
+
+/**
+ * 检测 MongoDB 驱动版本（仅在第一次调用时执行）
+ * @private
+ * @returns {number|null} 驱动主版本号，如果无法检测则返回 null
+ */
+function detectDriverVersion() {
+    if (_driverVersionChecked) {
+        return _detectedDriverMajorVersion;
+    }
+
+    _driverVersionChecked = true;
+
+    try {
+        const mongodb = require("mongodb");
+        const versionString = mongodb.version || require("mongodb/package.json").version;
+        const match = versionString.match(/^(\d+)\./);
+        if (match) {
+            _detectedDriverMajorVersion = parseInt(match[1], 10);
+            return _detectedDriverMajorVersion;
+        }
+    } catch (error) {
+        // 无法检测版本，静默失败
+    }
+
+    return null;
+}
+
+/**
+ * 记录驱动版本警告（仅在检测到不支持的版本时）
+ * @private
+ * @param {Object} logger - 日志实例
+ */
+function warnUnsupportedDriverVersion(logger) {
+    const version = detectDriverVersion();
+
+    if (version === null) {
+        // 无法检测版本，不输出警告（避免误报）
+        return;
+    }
+
+    if (version < 6) {
+        // 驱动版本小于 6.x，可能不兼容
+        if (logger && logger.warn) {
+            logger.warn("[result-handler] ⚠️ 检测到 MongoDB 驱动版本过旧", {
+                detectedVersion: version,
+                supportedVersion: "6.x",
+                message: "monSQLize 专为 MongoDB 驱动 6.x 设计，旧版本可能存在兼容性问题",
+                recommendation: "建议升级到 MongoDB Node.js 驱动 ^6.0.0"
+            });
+        }
+    } else if (version > 6) {
+        // 驱动版本大于 6.x，未经测试
+        if (logger && logger.warn) {
+            logger.warn("[result-handler] ⚠️ 检测到 MongoDB 驱动版本未经测试", {
+                detectedVersion: version,
+                testedVersion: "6.x",
+                message: "monSQLize 已针对 MongoDB 驱动 6.x 测试，新版本可能存在未知问题",
+                recommendation: "如遇问题，请查看技术分析报告或回退到驱动 6.x"
+            });
+        }
+    }
+    // 版本 === 6，无需警告
+}
+
+/**
+ * 处理 findOneAnd* 操作的返回值
+ * 统一处理各种边界情况，确保返回值格式的一致性
+ *
+ * @param {Object|null} result - MongoDB 驱动返回的结果
+ * @param {Object} options - 操作选项
+ * @param {boolean} [options.includeResultMetadata=false] - 是否返回完整元数据
+ * @param {Object} [logger] - 日志实例（可选，用于诊断）
+ * @returns {Object|null} 处理后的结果
+ *
+ * @example
+ * // 正常情况（找到文档）
+ * const result = { value: { name: "Alice" }, ok: 1, lastErrorObject: { n: 1, updatedExisting: true } };
+ * handleFindOneAndResult(result, {});  // 返回: { name: "Alice" }
+ *
+ * @example
+ * // 未找到文档
+ * const result = { value: null, ok: 1, lastErrorObject: { n: 0 } };
+ * handleFindOneAndResult(result, {});  // 返回: null
+ *
+ * @example
+ * // result 为 null（驱动异常情况）
+ * handleFindOneAndResult(null, {});  // 返回: null
+ *
+ * @example
+ * // 返回完整元数据
+ * handleFindOneAndResult(null, { includeResultMetadata: true });
+ * // 返回: { value: null, ok: 1, lastErrorObject: { n: 0 } }
+ */
+function handleFindOneAndResult(result, options = {}, logger = null) {
+    // 首次调用时检测驱动版本并输出警告（如果需要）
+    if (!_driverVersionChecked && logger) {
+        warnUnsupportedDriverVersion(logger);
+    }
+
+    // 情况 1：result 为 null 或 undefined（驱动在某些边界情况下可能返回 null）
+    if (!result || result === null) {
+        if (logger && logger.debug) {
+            logger.debug("[result-handler] Result is null/undefined, returning empty result", {
+                includeMetadata: options.includeResultMetadata
+            });
+        }
+
+        if (options.includeResultMetadata) {
+            // 返回标准的空结果元数据
+            return {
+                value: null,
+                ok: 1,
+                lastErrorObject: { n: 0 }
+            };
+        } else {
+            // 仅返回 null
+            return null;
+        }
+    }
+
+    // 情况 2：result 是对象但缺少 lastErrorObject（驱动版本差异或异常情况）
+    if (typeof result === "object" && !result.lastErrorObject) {
+        if (logger && logger.warn) {
+            logger.warn("[result-handler] ⚠️ Result missing lastErrorObject, possible driver version issue", {
+                hasValue: result.value !== undefined,
+                hasOk: result.ok !== undefined,
+                resultKeys: Object.keys(result),
+                driverVersion: detectDriverVersion(),
+                recommendation: "这可能表明 MongoDB 驱动返回了非预期的格式，请检查驱动版本"
+            });
+        }
+
+        const hasValue = result.value !== null && result.value !== undefined;
+        // 补充缺失的 lastErrorObject
+        result.lastErrorObject = {
+            n: hasValue ? 1 : 0
+        };
+        // 如果有值，假设是更新/替换操作成功
+        if (hasValue) {
+            result.lastErrorObject.updatedExisting = true;
+        }
+    }
+
+    // 情况 3：result 是对象且包含 lastErrorObject（正常情况）
+    if (options.includeResultMetadata) {
+        // 返回完整元数据：{ value, ok, lastErrorObject }
+        return result;
+    } else {
+        // 仅返回文档（可能为 null）
+        return result.value !== undefined ? result.value : null;
+    }
+}
+
+/**
+ * 判断操作是否修改了文档（用于缓存失效逻辑）
+ * 安全地检查 MongoDB 操作是否成功修改了文档
+ *
+ * @param {Object|null} result - MongoDB 驱动返回的结果
+ * @returns {boolean} 是否修改/删除了文档
+ *
+ * @example
+ * // 更新成功
+ * const result = { value: {...}, lastErrorObject: { updatedExisting: true } };
+ * wasDocumentModified(result);  // 返回: true
+ *
+ * @example
+ * // Upsert 插入
+ * const result = { value: {...}, lastErrorObject: { upserted: ObjectId(...) } };
+ * wasDocumentModified(result);  // 返回: true
+ *
+ * @example
+ * // 未找到文档
+ * const result = { value: null, lastErrorObject: { n: 0 } };
+ * wasDocumentModified(result);  // 返回: false
+ *
+ * @example
+ * // 删除成功（有返回值）
+ * const result = { value: {...}, lastErrorObject: { n: 1 } };
+ * wasDocumentModified(result);  // 返回: true
+ */
+function wasDocumentModified(result) {
+    // 安全检查：result 或 lastErrorObject 不存在
+    if (!result || !result.lastErrorObject) {
+        return false;
+    }
+
+    // 检查修改标志
+    return !!(
+        // 更新/替换操作：文档已存在并被修改
+        result.lastErrorObject.updatedExisting ||
+        // Upsert 操作：插入了新文档
+        result.lastErrorObject.upserted ||
+        // 删除操作：有文档被删除（通过 n > 0 或 value 不为 null 判断）
+        (result.lastErrorObject.n > 0) ||
+        (result.value !== null && result.value !== undefined)
+    );
+}
+
+module.exports = {
+    handleFindOneAndResult,
+    wasDocumentModified
+};
+

package/lib/mongodb/writes/update-many.js

@@ -0,0 +1,205 @@
+/**
+ * updateMany 操作实现
+ * 更新所有匹配的文档
+ */
+
+const { createError, ErrorCodes } = require("../../errors");
+const CacheFactory = require("../../cache");
+const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+
+/**
+ * 创建 updateMany 操作
+ * @param {Object} context - 模块上下文
+ * @param {Object} context.db - MongoDB 数据库实例
+ * @param {Object} context.cache - 缓存实例
+ * @param {Object} context.logger - 日志实例
+ * @param {Object} context.defaults - 默认配置
+ * @param {string} context.collection - 集合名称
+ * @param {string} context.effectiveDbName - 数据库名称
+ * @param {string} context.instanceId - 实例ID
+ * @returns {Object} 包含 updateMany 方法的对象
+ */
+function createUpdateManyOps(context) {
+    const { db, cache, logger, defaults, collection, effectiveDbName: databaseName, instanceId } = context;
+
+    // 提取集合名称和原生 collection 对象
+    const collectionName = collection.collectionName;
+    const nativeCollection = collection;
+
+    /**
+     * 更新多个文档
+     * @param {Object} filter - 筛选条件（必需）
+     * @param {Object} update - 更新操作（必需，使用更新操作符如 $set）
+     * @param {Object} [options] - 操作选项
+     * @param {boolean} [options.upsert=false] - 不存在时是否插入
+     * @param {Object} [options.writeConcern] - 写关注选项
+     * @param {boolean} [options.bypassDocumentValidation] - 是否绕过文档验证
+     * @param {string} [options.comment] - 操作注释（用于日志追踪）
+     * @param {Object} [options.collation] - 排序规则
+     * @param {Array|Object} [options.arrayFilters] - 数组过滤器
+     * @param {Object} [options.hint] - 索引提示
+     * @returns {Promise<Object>} 更新结果 { acknowledged, matchedCount, modifiedCount, upsertedId?, upsertedCount? }
+     * @throws {Error} 当参数无效时
+     *
+     * @example
+     * const result = await collection("users").updateMany(
+     *     { status: "inactive" },
+     *     { $set: { status: "archived", archivedAt: new Date() } }
+     * );
+     * console.log("Modified:", result.modifiedCount, "documents");
+     *
+     * @example
+     * // 使用数组过滤器
+     * const result = await collection("users").updateMany(
+     *     { "tags.name": "premium" },
+     *     { $set: { "tags.$[elem].verified": true } },
+     *     { arrayFilters: [{ "elem.name": "premium" }] }
+     * );
+     */
+    const updateMany = async function updateMany(filter, update, options = {}) {
+        const startTime = Date.now();
+
+        // 1. 参数验证
+        if (!filter || typeof filter !== "object" || Array.isArray(filter)) {
+            throw createError(
+                ErrorCodes.INVALID_ARGUMENT,
+                "filter 必须是对象类型",
+                [{ field: "filter", type: "object.required", message: "filter 是必需参数且必须是对象" }]
+            );
+        }
+
+        if (!update || typeof update !== "object" || Array.isArray(update)) {
+            throw createError(
+                ErrorCodes.INVALID_ARGUMENT,
+                "update 必须是对象类型",
+                [{ field: "update", type: "object.required", message: "update 是必需参数且必须是对象" }]
+            );
+        }
+
+        // 验证 update 包含更新操作符（防止整体替换）
+        const updateKeys = Object.keys(update);
+        if (updateKeys.length > 0 && !updateKeys.some(key => key.startsWith("$"))) {
+            throw createError(
+                ErrorCodes.INVALID_ARGUMENT,
+                "update 必须使用更新操作符（如 $set, $inc 等）",
+                [{ field: "update", type: "object.invalid", message: "请使用 $set, $inc, $push 等更新操作符" }]
+            );
+        }
+
+        // 2. 构建操作上下文
+        const operation = "updateMany";
+        const ns = `${databaseName}.${collectionName}`;
+
+        try {
+            // 3. 执行更新操作
+            const result = await nativeCollection.updateMany(filter, update, options);
+
+            // 4. 自动失效缓存（只要有匹配，就失效缓存）
+            if (cache && result.matchedCount > 0) {
+                try {
+                    // 使用标准命名空间模式删除该集合的所有缓存
+                    const ns = {
+                        iid: instanceId,
+                        type: "mongodb",
+                        db: databaseName,
+                        collection: collectionName
+                    };
+                    const pattern = CacheFactory.buildNamespacePattern(ns);
+
+                    // 检查是否在事务中
+                    if (isInTransaction(options)) {
+                        // 事务中：调用 Transaction 的 recordInvalidation 方法
+                        const tx = getTransactionFromSession(options.session);
+                        if (tx && typeof tx.recordInvalidation === 'function') {
+                            // 🚀 传递 metadata 支持文档级别锁
+                            await tx.recordInvalidation(pattern, {
+                                operation: 'write',
+                                query: filter,
+                                collection: collectionName
+                            });
+                            logger.debug(`[${operation}] 事务中失效缓存: ${ns.db}.${ns.collection}`);
+                        } else {
+                            const deleted = await cache.delPattern(pattern);
+                            if (deleted > 0) {
+                                logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
+                            }
+                        }
+                    } else {
+                        // 非事务：直接失效缓存
+                        const deleted = await cache.delPattern(pattern);
+                        if (deleted > 0) {
+                            logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
+                        }
+                    }
+                } catch (cacheErr) {
+                    // 缓存失效失败不影响写操作
+                    logger.warn(`[${operation}] 缓存失效失败: ${cacheErr.message}`, { ns: `${databaseName}.${collectionName}`, error: cacheErr });
+                }
+            }
+
+            // 5. 记录慢操作日志
+            const duration = Date.now() - startTime;
+            const slowQueryMs = defaults.slowQueryMs || 1000;
+            if (duration > slowQueryMs) {
+                logger.warn(`[${operation}] 慢操作警告`, {
+                    ns,
+                    duration,
+                    threshold: slowQueryMs,
+                    filterKeys: Object.keys(filter),
+                    updateKeys: Object.keys(update),
+                    matchedCount: result.matchedCount,
+                    modifiedCount: result.modifiedCount,
+                    upserted: result.upsertedId ? true : false,
+                    comment: options.comment
+                });
+            } else {
+                logger.debug(`[${operation}] 操作完成`, {
+                    ns,
+                    duration,
+                    matchedCount: result.matchedCount,
+                    modifiedCount: result.modifiedCount,
+                    upserted: result.upsertedId ? true : false
+                });
+            }
+
+            return result;
+
+        } catch (error) {
+            // 6. 错误处理
+            const duration = Date.now() - startTime;
+
+            logger.error(`[${operation}] 操作失败`, {
+                ns,
+                duration,
+                error: error.message,
+                code: error.code,
+                filterKeys: Object.keys(filter),
+                updateKeys: Object.keys(update)
+            });
+
+            // 识别特定错误类型
+            if (error.code === 11000) {
+                // MongoDB 重复键错误（可能在 upsert 时发生）
+                throw createError(
+                    ErrorCodes.DUPLICATE_KEY,
+                    "批量更新失败：违反唯一性约束",
+                    [{ field: "_id", message: error.message }],
+                    error
+                );
+            }
+
+            // 其他错误
+            throw createError(
+                ErrorCodes.WRITE_ERROR,
+                `updateMany 操作失败: ${error.message}`,
+                null,
+                error
+            );
+        }
+    };
+
+    return { updateMany };
+}
+
+module.exports = { createUpdateManyOps };
+

package/lib/mongodb/writes/update-one.js

@@ -0,0 +1,207 @@
+/**
+ * updateOne 操作实现
+ * 更新单个匹配的文档
+ */
+
+const { createError, ErrorCodes } = require("../../errors");
+const CacheFactory = require("../../cache");
+const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+
+/**
+ * 创建 updateOne 操作
+ * @param {Object} context - 模块上下文
+ * @param {Object} context.db - MongoDB 数据库实例
+ * @param {Object} context.cache - 缓存实例
+ * @param {Object} context.logger - 日志实例
+ * @param {Object} context.defaults - 默认配置
+ * @param {string} context.collection - 集合名称
+ * @param {string} context.effectiveDbName - 数据库名称
+ * @param {string} context.instanceId - 实例ID
+ * @returns {Object} 包含 updateOne 方法的对象
+ */
+function createUpdateOneOps(context) {
+    const { db, cache, logger, defaults, collection, effectiveDbName: databaseName, instanceId } = context;
+
+    // 提取集合名称和原生 collection 对象
+    const collectionName = collection.collectionName;
+    const nativeCollection = collection;
+
+    /**
+     * 更新单个文档
+     * @param {Object} filter - 筛选条件（必需）
+     * @param {Object} update - 更新操作（必需，使用更新操作符如 $set）
+     * @param {Object} [options] - 操作选项
+     * @param {boolean} [options.upsert=false] - 不存在时是否插入
+     * @param {Object} [options.writeConcern] - 写关注选项
+     * @param {boolean} [options.bypassDocumentValidation] - 是否绕过文档验证
+     * @param {string} [options.comment] - 操作注释（用于日志追踪）
+     * @param {Object} [options.collation] - 排序规则
+     * @param {Array|Object} [options.arrayFilters] - 数组过滤器
+     * @param {Object} [options.hint] - 索引提示
+     * @returns {Promise<Object>} 更新结果 { acknowledged, matchedCount, modifiedCount, upsertedId?, upsertedCount? }
+     * @throws {Error} 当参数无效时
+     *
+     * @example
+     * const result = await collection("users").updateOne(
+     *     { userId: "user123" },
+     *     { $set: { status: "active", updatedAt: new Date() } }
+     * );
+     * console.log("Modified:", result.modifiedCount);
+     *
+     * @example
+     * // 使用 upsert 选项
+     * const result = await collection("users").updateOne(
+     *     { userId: "user123" },
+     *     { $set: { name: "Alice", age: 25 } },
+     *     { upsert: true }
+     * );
+     */
+    const updateOne = async function updateOne(filter, update, options = {}) {
+        const startTime = Date.now();
+
+        // 1. 参数验证
+        if (!filter || typeof filter !== "object" || Array.isArray(filter)) {
+            throw createError(
+                ErrorCodes.INVALID_ARGUMENT,
+                "filter 必须是对象类型",
+                [{ field: "filter", type: "object.required", message: "filter 是必需参数且必须是对象" }]
+            );
+        }
+
+        if (!update || typeof update !== "object" || Array.isArray(update)) {
+            throw createError(
+                ErrorCodes.INVALID_ARGUMENT,
+                "update 必须是对象类型",
+                [{ field: "update", type: "object.required", message: "update 是必需参数且必须是对象" }]
+            );
+        }
+
+        // 验证 update 包含更新操作符（防止整体替换）
+        const updateKeys = Object.keys(update);
+        if (updateKeys.length > 0 && !updateKeys.some(key => key.startsWith("$"))) {
+            throw createError(
+                ErrorCodes.INVALID_ARGUMENT,
+                "update 必须使用更新操作符（如 $set, $inc 等）",
+                [{ field: "update", type: "object.invalid", message: "请使用 $set, $inc, $push 等更新操作符，或使用 replaceOne 进行整体替换" }]
+            );
+        }
+
+        // 2. 构建操作上下文
+        const operation = "updateOne";
+        const ns = `${databaseName}.${collectionName}`;
+
+        try {
+            // 3. 执行更新操作
+            const result = await nativeCollection.updateOne(filter, update, options);
+
+            // 4. 自动失效缓存
+            if (cache && result.modifiedCount > 0) {
+                try {
+                    // 使用标准命名空间模式删除该集合的所有缓存
+                    const ns = {
+                        iid: instanceId,
+                        type: "mongodb",
+                        db: databaseName,
+                        collection: collectionName
+                    };
+                    const pattern = CacheFactory.buildNamespacePattern(ns);
+
+                    // 检查是否在事务中
+                    if (isInTransaction(options)) {
+                        // 事务中：调用 Transaction 的 recordInvalidation 方法
+                        // 这会立即失效缓存 + 添加缓存锁
+                        const tx = getTransactionFromSession(options.session);
+                        if (tx && typeof tx.recordInvalidation === 'function') {
+                            // 🚀 传递 metadata 支持文档级别锁和只读优化
+                            await tx.recordInvalidation(pattern, {
+                                operation: 'write',
+                                query: filter,
+                                collection: collectionName
+                            });
+                            logger.debug(`[${operation}] 事务中失效缓存: ${ns.db}.${ns.collection}`);
+                        } else {
+                            // 降级处理：直接失效缓存
+                            const deleted = await cache.delPattern(pattern);
+                            if (deleted > 0) {
+                                logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
+                            }
+                        }
+                    } else {
+                        // 非事务：直接失效缓存
+                        const deleted = await cache.delPattern(pattern);
+                        if (deleted > 0) {
+                            logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
+                        }
+                    }
+                } catch (cacheErr) {
+                    // 缓存失效失败不影响写操作
+                    logger.warn(`[${operation}] 缓存失效失败: ${cacheErr.message}`, { ns: `${databaseName}.${collectionName}`, error: cacheErr });
+                }
+            }
+
+            // 5. 记录慢操作日志
+            const duration = Date.now() - startTime;
+            const slowQueryMs = defaults.slowQueryMs || 1000;
+            if (duration > slowQueryMs) {
+                logger.warn(`[${operation}] 慢操作警告`, {
+                    ns,
+                    duration,
+                    threshold: slowQueryMs,
+                    filterKeys: Object.keys(filter),
+                    updateKeys: Object.keys(update),
+                    matchedCount: result.matchedCount,
+                    modifiedCount: result.modifiedCount,
+                    upserted: result.upsertedId ? true : false,
+                    comment: options.comment
+                });
+            } else {
+                logger.debug(`[${operation}] 操作完成`, {
+                    ns,
+                    duration,
+                    matchedCount: result.matchedCount,
+                    modifiedCount: result.modifiedCount,
+                    upserted: result.upsertedId ? true : false
+                });
+            }
+
+            return result;
+
+        } catch (error) {
+            // 6. 错误处理
+            const duration = Date.now() - startTime;
+
+            logger.error(`[${operation}] 操作失败`, {
+                ns,
+                duration,
+                error: error.message,
+                code: error.code,
+                filterKeys: Object.keys(filter),
+                updateKeys: Object.keys(update)
+            });
+
+            // 识别特定错误类型
+            if (error.code === 11000) {
+                // MongoDB 重复键错误（可能在 upsert 时发生）
+                throw createError(
+                    ErrorCodes.DUPLICATE_KEY,
+                    "更新失败：违反唯一性约束",
+                    [{ field: "_id", message: error.message }],
+                    error
+                );
+            }
+
+            // 其他错误
+            throw createError(
+                ErrorCodes.WRITE_ERROR,
+                `updateOne 操作失败: ${error.message}`,
+                null,
+                error
+            );
+        }
+    };
+
+    return { updateOne };
+}
+
+module.exports = { createUpdateOneOps };
+