monsqlize 1.0.0 → 1.0.2

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

@@ -3,9 +3,10 @@
  * 更新单个匹配的文档
  */
 
-const { createError, ErrorCodes } = require("../../errors");
-const CacheFactory = require("../../cache");
-const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+const { createError, ErrorCodes } = require('../../errors');
+const CacheFactory = require('../../cache');
+const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
+const { convertObjectIdStrings, convertUpdateDocument } = require('../../utils/objectid-converter');
 
 /**
  * 创建 updateOne 操作
@@ -60,39 +61,54 @@ function createUpdateOneOps(context) {
         const startTime = Date.now();
 
         // 1. 参数验证
-        if (!filter || typeof filter !== "object" || Array.isArray(filter)) {
+        if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
             throw createError(
                 ErrorCodes.INVALID_ARGUMENT,
-                "filter 必须是对象类型",
-                [{ field: "filter", type: "object.required", message: "filter 是必需参数且必须是对象" }]
+                'filter 必须是对象类型',
+                [{ field: 'filter', type: 'object.required', message: 'filter 是必需参数且必须是对象' }]
             );
         }
 
-        if (!update || typeof update !== "object" || Array.isArray(update)) {
+        if (!update || typeof update !== 'object' || Array.isArray(update)) {
             throw createError(
                 ErrorCodes.INVALID_ARGUMENT,
-                "update 必须是对象类型",
-                [{ field: "update", type: "object.required", message: "update 是必需参数且必须是对象" }]
+                'update 必须是对象类型',
+                [{ field: 'update', type: 'object.required', message: 'update 是必需参数且必须是对象' }]
             );
         }
 
         // 验证 update 包含更新操作符（防止整体替换）
         const updateKeys = Object.keys(update);
-        if (updateKeys.length > 0 && !updateKeys.some(key => key.startsWith("$"))) {
+        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 进行整体替换" }]
+                'update 必须使用更新操作符（如 $set, $inc 等）',
+                [{ field: 'update', type: 'object.invalid', message: '请使用 $set, $inc, $push 等更新操作符，或使用 replaceOne 进行整体替换' }]
             );
         }
 
+        // ✅ v1.3.0: 自动转换 ObjectId 字符串
+        const convertedFilter = convertObjectIdStrings(filter, 'filter', 0, new WeakSet(), {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        });
+
+        const convertedUpdate = convertUpdateDocument(update, {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        });
+
         // 2. 构建操作上下文
-        const operation = "updateOne";
+        const operation = 'updateOne';
         const ns = `${databaseName}.${collectionName}`;
 
         try {
             // 3. 执行更新操作
-            const result = await nativeCollection.updateOne(filter, update, options);
+            const result = await nativeCollection.updateOne(convertedFilter, convertedUpdate, options);
 
             // 4. 自动失效缓存
             if (cache && result.modifiedCount > 0) {
@@ -100,7 +116,7 @@ function createUpdateOneOps(context) {
                     // 使用标准命名空间模式删除该集合的所有缓存
                     const ns = {
                         iid: instanceId,
-                        type: "mongodb",
+                        type: 'mongodb',
                         db: databaseName,
                         collection: collectionName
                     };
@@ -184,8 +200,8 @@ function createUpdateOneOps(context) {
                 // MongoDB 重复键错误（可能在 upsert 时发生）
                 throw createError(
                     ErrorCodes.DUPLICATE_KEY,
-                    "更新失败：违反唯一性约束",
-                    [{ field: "_id", message: error.message }],
+                    '更新失败：违反唯一性约束',
+                    [{ field: '_id', message: error.message }],
                     error
                 );
             }

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

@@ -4,7 +4,8 @@
  */
 
 const { createError, ErrorCodes } = require('../../errors');
-const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
 
 /**
  * 创建 upsertOne 操作
@@ -68,11 +69,26 @@ function createUpsertOneOps(context) {
             );
         }
 
+        // ✅ v1.3.0: 自动转换 ObjectId 字符串
+        const convertedFilter = convertObjectIdStrings(filter, 'filter', 0, new WeakSet(), {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        });
+
+        const convertedUpdate = convertObjectIdStrings(update, 'document', 0, new WeakSet(), {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        });
+
         // 2. 检查 update 是否包含更新操作符
-        const hasOperator = Object.keys(update).some(key => key.startsWith('$'));
+        const hasOperator = Object.keys(convertedUpdate).some(key => key.startsWith('$'));
 
         // 如果没有操作符，自动包装为 $set
-        const updateDoc = hasOperator ? update : { $set: update };
+        const updateDoc = hasOperator ? convertedUpdate : { $set: convertedUpdate };
 
         // 3. 构建选项
         const maxTimeMS = options.maxTimeMS !== undefined ? options.maxTimeMS : defaults.maxTimeMS;
@@ -84,7 +100,7 @@ function createUpsertOneOps(context) {
         // 4. 执行 updateOne 操作
         let result;
         try {
-            result = await collection.updateOne(filter, updateDoc, driverOpts);
+            result = await collection.updateOne(convertedFilter, updateDoc, driverOpts);
         } catch (error) {
             // 统一错误处理
             if (error.code === 11000) {
@@ -146,7 +162,7 @@ function createUpsertOneOps(context) {
                     operation: 'upsertOne',
                     durationMs: duration,
                     iid: instanceId,
-                    type: type,
+                    type,
                     db: effectiveDbName,
                     collection: collection.collectionName,
                     matchedCount: result.matchedCount,
@@ -154,7 +170,7 @@ function createUpsertOneOps(context) {
                     upsertedId: result.upsertedId,
                     filter: mongoSlowLogShaper?.sanitize ? mongoSlowLogShaper.sanitize(filter) : filter,
                     update: mongoSlowLogShaper?.sanitize ? mongoSlowLogShaper.sanitize(updateDoc) : updateDoc,
-                    comment: comment
+                    comment
                 };
                 logger?.warn?.('🐌 Slow query: upsertOne', meta);
                 emit?.('slow-query', meta);
@@ -166,11 +182,11 @@ function createUpsertOneOps(context) {
         // 7. 日志记录
         logger?.debug?.('[upsertOne] 操作完成', {
             ns: `${effectiveDbName}.${collection.collectionName}`,
-            duration: duration,
+            duration,
             matchedCount: result.matchedCount,
             modifiedCount: result.modifiedCount,
             upsertedId: result.upsertedId === null ? undefined : result.upsertedId,
-            upsertedCount: upsertedCount
+            upsertedCount
         });
 
         // 8. 返回结果
@@ -179,7 +195,7 @@ function createUpsertOneOps(context) {
             matchedCount: result.matchedCount,
             modifiedCount: result.modifiedCount,
             upsertedId: result.upsertedId === null ? undefined : result.upsertedId,
-            upsertedCount: upsertedCount
+            upsertedCount
         };
     };
 

package/lib/operators.js

@@ -327,4 +327,4 @@ module.exports = {
         '$setReadConcern': { mysql: '' },
         '$setReadPref':    { mysql: '' }
     }
-}
+};

package/lib/redis-cache-adapter.js

@@ -1,13 +1,13 @@
 /**
  * Redis 缓存适配器：将 Redis 封装为 CacheLike 接口
  * 支持直接传入 Redis URL 字符串或 ioredis 实例
- * 
+ *
  * @example
  * const { createRedisCacheAdapter } = require('monsqlize/lib/redis-cache-adapter');
- * 
+ *
  * // 方式 1：传入 URL 字符串（推荐）
  * const cache = createRedisCacheAdapter('redis://localhost:6379/0');
- * 
+ *
  * // 方式 2：传入 ioredis 实例
  * const Redis = require('ioredis');
  * const redis = new Redis('redis://localhost:6379/0');

package/lib/slow-query-log/base-storage.js

@@ -0,0 +1,69 @@
+/**
+ * 慢查询日志存储接口
+ * 所有存储适配器必须实现此接口
+ *
+ * @version 1.3.0
+ * @since 2025-12-22
+ */
+
+class ISlowQueryLogStorage {
+  /**
+   * 初始化存储（创建集合/表、索引等）
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    throw new Error('ISlowQueryLogStorage.initialize() must be implemented');
+  }
+
+  /**
+   * 保存单条慢查询日志
+   * @param {Object} log - 慢查询日志对象
+   * @param {string} log.db - 数据库名
+   * @param {string} log.collection - 集合名
+   * @param {string} log.operation - 操作类型
+   * @param {Object} log.queryShape - 查询模式（已脱敏）
+   * @param {number} log.executionTimeMs - 执行时间（毫秒）
+   * @param {Date} log.timestamp - 时间戳
+   * @param {Object} [log.metadata] - 扩展元数据
+   * @returns {Promise<void>}
+   */
+  async save(log) {
+    throw new Error('ISlowQueryLogStorage.save() must be implemented');
+  }
+
+  /**
+   * 批量保存慢查询日志
+   * @param {Object[]} logs - 慢查询日志数组
+   * @returns {Promise<void>}
+   */
+  async saveBatch(logs) {
+    throw new Error('ISlowQueryLogStorage.saveBatch() must be implemented');
+  }
+
+  /**
+   * 查询慢查询日志
+   * @param {Object} filter - 查询条件
+   * @param {string} [filter.db] - 数据库名
+   * @param {string} [filter.collection] - 集合名
+   * @param {string} [filter.operation] - 操作类型
+   * @param {Object} options - 查询选项
+   * @param {Object} [options.sort] - 排序规则
+   * @param {number} [options.limit] - 限制数量
+   * @param {number} [options.skip] - 跳过数量
+   * @returns {Promise<Object[]>}
+   */
+  async query(filter, options) {
+    throw new Error('ISlowQueryLogStorage.query() must be implemented');
+  }
+
+  /**
+   * 关闭连接
+   * @returns {Promise<void>}
+   */
+  async close() {
+    throw new Error('ISlowQueryLogStorage.close() must be implemented');
+  }
+}
+
+module.exports = { ISlowQueryLogStorage };
+

package/lib/slow-query-log/batch-queue.js

@@ -0,0 +1,96 @@
+/**
+ * 批量队列管理器
+ * 用于批量写入慢查询日志，优化性能
+ *
+ * @version 1.3.0
+ * @since 2025-12-22
+ */
+
+class BatchQueue {
+  /**
+   * 创建批量队列
+   * @param {Object} storage - 存储适配器实例
+   * @param {Object} options - 队列配置
+   * @param {number} [options.batchSize=10] - 批量大小
+   * @param {number} [options.flushInterval=5000] - 刷新间隔（毫秒）
+   * @param {number} [options.maxBufferSize=100] - 最大缓冲区大小
+   * @param {Object} [logger] - 日志记录器
+   */
+  constructor(storage, options = {}, logger) {
+    this.storage = storage;
+    this.buffer = [];
+    this.batchSize = options.batchSize || 10;
+    this.flushInterval = options.flushInterval || 5000;
+    this.maxBufferSize = options.maxBufferSize || 100;
+    this.timer = null;
+    this.flushing = false;
+    this.logger = logger || console;
+  }
+
+  /**
+   * 添加日志到队列
+   * @param {Object} log - 慢查询日志对象
+   * @returns {Promise<void>}
+   */
+  async add(log) {
+    this.buffer.push(log);
+
+    // 防止内存溢出：达到最大缓冲区，立即刷新
+    if (this.buffer.length >= this.maxBufferSize) {
+      await this.flush();
+      return;
+    }
+
+    // 达到批量大小，立即刷新
+    if (this.buffer.length >= this.batchSize) {
+      await this.flush();
+    } else if (!this.timer) {
+      // 启动定时器（防止数据积压）
+      this.timer = setTimeout(() => this.flush(), this.flushInterval);
+    }
+  }
+
+  /**
+   * 刷新队列（批量写入）
+   * @returns {Promise<void>}
+   */
+  async flush() {
+    // 防止并发刷新
+    if (this.flushing || this.buffer.length === 0) {
+      return;
+    }
+
+    this.flushing = true;
+    const logs = this.buffer.splice(0);  // 清空缓冲区
+    clearTimeout(this.timer);
+    this.timer = null;
+
+    try {
+      // 批量写入
+      await this.storage.saveBatch(logs);
+      if (this.logger.debug) {
+        this.logger.debug(`[SlowQueryLog] Batch flushed: ${logs.length} logs`);
+      }
+    } catch (err) {
+      // ⚠️ 失败不阻塞主流程，仅记录错误
+      if (this.logger.error) {
+        this.logger.error('[SlowQueryLog] Failed to save slow query logs batch:', err);
+      }
+    } finally {
+      this.flushing = false;
+    }
+  }
+
+  /**
+   * 关闭队列（确保数据不丢失）
+   * @returns {Promise<void>}
+   */
+  async close() {
+    clearTimeout(this.timer);
+    this.timer = null;
+    await this.flush();  // 最后刷新一次
+  }
+}
+
+module.exports = { BatchQueue };
+

package/lib/slow-query-log/config-manager.js

@@ -0,0 +1,195 @@
+/**
+ * 慢查询日志配置管理器
+ * 负责配置合并、验证和默认值处理
+ *
+ * @version 1.3.0
+ * @since 2025-12-22
+ */
+
+// 默认配置
+const DEFAULT_CONFIG = {
+  enabled: false,
+
+  storage: {
+    type: null,  // null = 自动推断
+    useBusinessConnection: true,
+    uri: null,
+
+    mongodb: {
+      database: 'admin',
+      collection: 'slow_query_logs',
+      ttl: 7 * 24 * 3600,  // 7天
+      ttlField: 'lastSeen'
+    }
+  },
+
+  deduplication: {
+    enabled: true,
+    strategy: 'aggregate',
+    keepRecentExecutions: 0
+  },
+
+  batch: {
+    enabled: true,
+    size: 10,
+    interval: 5000,
+    maxBufferSize: 100
+  },
+
+  filter: {
+    excludeDatabases: [],
+    excludeCollections: [],
+    excludeOperations: [],
+    minExecutionTimeMs: 0
+  },
+
+  advanced: {
+    autoCreateIndexes: true,
+    validateConnection: true,
+    errorHandling: 'log',  // log | throw | silent
+    debug: false
+  }
+};
+
+class SlowQueryLogConfigManager {
+  /**
+   * 合并用户配置与默认配置
+   * @param {*} userConfig - 用户配置（可以是boolean或object）
+   * @param {string} businessType - 业务库类型
+   * @returns {Object} 合并后的完整配置
+   */
+  static mergeConfig(userConfig, businessType) {
+    // 场景1：未配置（默认禁用）
+    if (userConfig === undefined || userConfig === null) {
+      return { ...deepClone(DEFAULT_CONFIG), enabled: false };
+    }
+
+    // 场景2：boolean快捷配置
+    if (typeof userConfig === 'boolean') {
+      const config = deepClone(DEFAULT_CONFIG);
+      config.enabled = userConfig;
+
+      // 自动推断storage.type
+      if (userConfig && businessType) {
+        config.storage.type = businessType;
+      }
+
+      return config;
+    }
+
+    // 场景3：对象配置（深度合并）
+    if (typeof userConfig === 'object') {
+      const merged = deepMerge(deepClone(DEFAULT_CONFIG), userConfig);
+
+      // 智能推断：如果提供了storage配置，自动启用
+      if (userConfig.storage && merged.enabled === false) {
+        merged.enabled = true;
+      }
+
+      // 自动推断storage.type
+      if (merged.storage.type === null && businessType) {
+        if (merged.storage.useBusinessConnection) {
+          merged.storage.type = businessType;
+        } else {
+          merged.storage.type = 'mongodb';  // 独立连接默认MongoDB
+        }
+      }
+
+      return merged;
+    }
+
+    throw new Error('Invalid slowQueryLog config type. Expected boolean or object');
+  }
+
+  /**
+   * 验证配置合法性
+   * @param {Object} config - 配置对象
+   * @param {string} businessType - 业务库类型
+   * @throws {Error} 配置错误时抛出异常
+   */
+  static validate(config, businessType) {
+    const { storage } = config;
+
+    // 验证storage.type
+    const validTypes = ['mongodb', 'postgresql', 'mysql', 'file', 'custom'];
+    if (storage.type && !validTypes.includes(storage.type)) {
+      throw new Error(
+        `Invalid storage.type: ${storage.type}. ` +
+        `Valid types are: ${validTypes.join(', ')}`
+      );
+    }
+
+    // 验证复用连接的类型一致性
+    if (storage.useBusinessConnection === true) {
+      if (storage.type && storage.type !== businessType) {
+        throw new Error(
+          `Cannot use business connection when storage type (${storage.type}) ` +
+          `differs from business type (${businessType}). ` +
+          `Set useBusinessConnection=false and provide storage.uri`
+        );
+      }
+    } else {
+      // 验证独立连接的uri
+      if (!storage.uri) {
+        throw new Error(
+          'storage.uri is required when useBusinessConnection=false'
+        );
+      }
+    }
+
+    // 验证deduplication.strategy
+    const validStrategies = ['aggregate', 'none'];
+    if (!validStrategies.includes(config.deduplication.strategy)) {
+      throw new Error(
+        `Invalid deduplication.strategy: ${config.deduplication.strategy}. ` +
+        `Valid strategies are: ${validStrategies.join(', ')}`
+      );
+    }
+
+    // 验证TTL
+    if (storage.mongodb.ttl < 0) {
+      throw new Error('storage.mongodb.ttl must be positive');
+    }
+
+    // 验证batch配置
+    if (config.batch.size < 1 || config.batch.size > 1000) {
+      throw new Error('batch.size must be between 1 and 1000');
+    }
+
+    if (config.batch.interval < 100) {
+      throw new Error('batch.interval must be >= 100ms');
+    }
+
+    return true;
+  }
+}
+
+/**
+ * 深度克隆对象
+ * @param {Object} obj - 源对象
+ * @returns {Object} 克隆后的对象
+ */
+function deepClone(obj) {
+  return JSON.parse(JSON.stringify(obj));
+}
+
+/**
+ * 深度合并对象
+ * @param {Object} target - 目标对象
+ * @param {Object} source - 源对象
+ * @returns {Object} 合并后的对象
+ */
+function deepMerge(target, source) {
+  for (const key in source) {
+    if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+      target[key] = target[key] || {};
+      deepMerge(target[key], source[key]);
+    } else {
+      target[key] = source[key];
+    }
+  }
+  return target;
+}
+
+module.exports = { SlowQueryLogConfigManager, DEFAULT_CONFIG };
+