mm_mysql 2.2.4 → 2.2.6

package/index.js

@@ -1,602 +1,602 @@
-const mysql = require('mysql2/promise');
-const { Base } = require('mm_expand');
-const { DB } = require('./db');
-
-/**
- * 优化版MySQL数据库操作类
- * 保持必要功能，简化过度封装，直接使用mysql2模块
- * @class Mysql
- * @extends Base
- */
-class Mysql extends Base {
-    /**
-     * 默认配置
-     * MySQL2支持的连接池配置参数：
-     * - host, port, user, password, database
-     * - charset, timezone, connect_timeout
-     * - connection_limit, acquire_timeout, wait_for_connections
-     * - queueLimit参数在MySQL2中可能不被支持，已移除
-     */
-    static default_config = {
-        host: '127.0.0.1',
-        port: 3306,
-        user: 'root',
-        password: 'Asd159357',
-        database: '',
-        charset: 'utf8mb4',
-        timezone: '+08:00',
-        connect_timeout: 20000,
-        connection_limit: 10,
-        acquire_timeout: 20000,
-        wait_for_connections: true
-    };
-
-    /**
-     * 构造函数
-     * @param {Object} config - 配置对象
-     */
-    constructor(config = {}) {
-        super(Object.assign({}, Mysql.default_config, config));
-        this._pool = null;
-        this._connection = null;
-        this._usePool = this.config.connection_limit > 1;
-    }
-}
-
-/**
- * 获取MySQL2支持的配置参数
- * 根据连接类型（连接池或单连接）过滤参数，避免警告
- * @param {boolean} is_pool - 是否为连接池配置
- * @returns {Object} 过滤后的配置对象
- */
-Mysql.prototype._getValidConfig = function (is_pool = false) {
-    // 基础连接参数（适用于所有连接类型）
-    const base_map = {
-        'host': 'host',
-        'port': 'port',
-        'user': 'user',
-        'password': 'password',
-        'database': 'database',
-        'charset': 'charset',
-        'timezone': 'timezone',
-        'connect_timeout': 'connectTimeout'
-    };
-
-    // 连接池专用参数
-    const pool_map = {
-        'connection_limit': 'connectionLimit',
-        'wait_for_connections': 'waitForConnections',
-        'idle_timeout': 'idleTimeout',
-        'max_idle': 'maxIdle'
-    };
-
-    const config = {};
-
-    // 添加基础参数
-    for (const key in base_map) {
-        if (this.config[key] !== undefined) {
-            config[base_map[key]] = this.config[key];
-        }
-    }
-
-    // 如果是连接池，添加连接池专用参数
-    if (is_pool) {
-        for (const key in pool_map) {
-            if (this.config[key] !== undefined) {
-                config[pool_map[key]] = this.config[key];
-            }
-        }
-    }
-    // 如果是单连接，确保不包含任何连接池专用参数
-    else {
-        // 移除所有连接池专用参数，避免mysql2内部警告
-        for (const key in pool_map) {
-            if (pool_map[key] in config) {
-                delete config[pool_map[key]];
-            }
-        }
-    }
-
-    return config;
-};
-
-/**
- * 打开数据库连接
- * @returns {Promise<boolean>}
- * @throws {TypeError} 当配置参数无效时
- */
-Mysql.prototype.open = async function () {
-    // 参数校验
-    if (!this.config || typeof this.config !== 'object') {
-        throw new TypeError('config must be object');
-    }
-
-    try {
-        if (this._usePool) {
-            // 根据连接类型获取对应的配置参数
-            const valid_config = this._getValidConfig(this._usePool);
-            this._pool = mysql.createPool(valid_config);
-            // 测试连接池连接
-            const conn = await this._pool.getConnection();
-            conn.release();
-        } else {
-            const valid_config = this._getValidConfig(this._usePool);
-            this._connection = await mysql.createConnection(valid_config);
-        }
-
-        this.logger('info', '数据库连接成功');
-        return true;
-    } catch (error) {
-        this.logger('error', '数据库连接失败', error);
-        return false;
-    }
-};
-
-/**
- * 关闭数据库连接
- * @returns {Promise<boolean>}
- */
-Mysql.prototype.close = async function () {
-    try {
-        if (this._pool) {
-            await this._pool.end();
-            this._pool = null;
-        }
-        if (this._connection) {
-            await this._connection.end();
-            this._connection = null;
-        }
-
-        this.logger('info', '数据库连接已关闭');
-        return true;
-    } catch (error) {
-        this.logger('error', '关闭连接失败', error);
-        return false;
-    }
-};
-
-/**
- * 安全释放数据库连接
- * @param {Object} conn - 数据库连接对象
- * @param {boolean} is_pool_conn - 是否为连接池连接
- * @returns {Promise<void>}
- */
-async function safeReleaseConnection(conn, is_pool_conn) {
-    if (!conn) return;
-
-    try {
-        if (is_pool_conn && typeof conn.release === 'function') {
-            await conn.release();
-        }
-    } catch (release_err) {
-       $.log.error('释放连接失败', release_err);
-    }
-};
-
-/**
- * 获取数据库连接（改进版）
- * @returns {Promise<Object>}
- * @throws {TypeError} 当连接池或连接不存在时
- */
-Mysql.prototype.getConn = async function () {
-    // 参数校验
-    if (!this._pool && !this._connection) {
-        await this.open();
-    }
-
-    try {
-        if (this._usePool) {
-            const conn = await this._pool.getConnection();
-            return conn;
-        } else {
-            return this._connection;
-        }
-    } catch (error) {
-        this.logger('error', '获取连接失败', error);
-    }
-    return null;
-};
-
-/**
- * 执行SQL查询（改进版）
- * @param {String} sql - SQL语句
- * @param {Array} params - 参数数组
- * @returns {Promise<Object>}
- * @throws {TypeError} 当sql参数无效时
- */
-Mysql.prototype.run = async function (sql, params = []) {
-    // 参数校验
-    if (typeof sql !== 'string' || sql.trim() === '') {
-        throw new TypeError('sql must be non-empty string');
-    }
-    if (!Array.isArray(params)) {
-        throw new TypeError('params must be array');
-    }
-
-    this.error = null;
-    let conn = null;
-    let is_pool_conn = false;
-    let connection_released = false;
-
-    try {
-        // 获取连接
-        conn = await this.getConn();
-        is_pool_conn = this._usePool;
-
-        // 直接使用mysql2的query方法
-        const [rows] = await conn.query(sql, params);
-        return rows;
-    } catch (err) {
-        this.sql = err.sql;
-        this.error = {
-            code: err.errno,
-            message: err.sqlMessage
-        };
-        // 在错误情况下也要确保连接释放
-        try {
-            await safeReleaseConnection(conn, is_pool_conn);
-        } catch (release_err) {
-            this.logger('error', '释放连接失败', release_err);
-        }
-        connection_released = true;
-    } finally {
-        // 确保连接被释放，避免资源泄漏
-        if (!connection_released) {
-            try {
-                await safeReleaseConnection(conn, is_pool_conn);
-            } catch (release_err) {
-                this.logger('error', '释放连接失败', release_err);
-            }
-        }
-    }
-    return [];
-};
-
-/**
- * 执行SQL语句（改进版）
- * @param {String} sql - SQL语句
- * @param {Array} params - 参数数组
- * @returns {Promise<Object>}
- * @throws {TypeError} 当sql参数无效时
- */
-Mysql.prototype.exec = async function (sql, params = []) {
-    // 参数校验
-    if (typeof sql !== 'string' || sql.trim() === '') {
-        throw new TypeError('sql must be non-empty string');
-    }
-    if (!Array.isArray(params)) {
-        throw new TypeError('params must be array');
-    }
-    this.error = null;
-    let conn = null;
-    let is_pool_conn = false;
-    let connection_released = false;
-
-    try {
-        // 获取连接
-        conn = await this.getConn();
-        is_pool_conn = this._usePool;
-
-        // 直接使用mysql2的execute方法
-        const [result] = await conn.execute(sql, params);
-        return result.insertId || result.affectedRows || result.changedRows || 1;
-    } catch (error) {
-        this.logger('error', 'SQL执行失败', error);
-        this.sql = error.sql;
-        this.error = {
-            code: error.errno,
-            message: error.sqlMessage
-        };
-        // 在错误情况下也要确保连接释放
-        try {
-            await safeReleaseConnection(conn, is_pool_conn);
-        } catch (release_err) {
-            this.logger('error', '释放连接失败', release_err);
-        }
-        connection_released = true;
-    } finally {
-        // 确保连接被释放，避免资源泄漏
-        if (!connection_released) {
-            try {
-                await safeReleaseConnection(conn, is_pool_conn);
-            } catch (release_err) {
-                this.logger('error', '释放连接失败', release_err);
-            }
-        }
-    }
-    return 0;
-};
-
-/**
- * 开始事务（改进版）
- * @returns {Promise<Object>} 事务连接对象
- */
-Mysql.prototype.beginTransaction = async function () {
-    let conn = null;
-    let transaction_committed = false;
-    let transaction_rolled_back = false;
-
-    try {
-        conn = await this.getConn();
-        await conn.beginTransaction();
-
-        return {
-            connection: conn,
-            commit: async () => {
-                if (transaction_committed || transaction_rolled_back) {
-                    this.logger('warn', '事务已结束，无需重复提交');
-                    return;
-                }
-                await conn.commit();
-                transaction_committed = true;
-                try {
-                    await safeReleaseConnection(conn, this._usePool);
-                } catch (release_err) {
-                    this.logger('error', '提交时释放连接失败', release_err);
-                }
-            },
-            rollback: async () => {
-                if (transaction_committed || transaction_rolled_back) {
-                    this.logger('warn', '事务已结束，无需重复回滚');
-                    return;
-                }
-                await conn.rollback();
-                transaction_rolled_back = true;
-                try {
-                    await safeReleaseConnection(conn, this._usePool);
-                } catch (release_err) {
-                    this.logger('error', '回滚时释放连接失败', release_err);
-                }
-            },
-            _is_ended: () => transaction_committed || transaction_rolled_back
-        };
-    } catch (error) {
-        // 如果事务开始失败，确保连接被释放
-        try {
-            await safeReleaseConnection(conn, this._usePool);
-        } catch (release_err) {
-            this.logger('error', '释放连接失败', release_err);
-        }
-        this.logger('error', '事务开始失败', error);
-        throw error;
-    }
-};
-
-/**
- * 在事务中执行多个操作（改进版）
- * @param {Function} callback - 包含事务操作的回调函数
- * @returns {Promise<*>} 回调函数的返回值
- * @throws {TypeError} 当callback参数无效时
- */
-Mysql.prototype.transaction = async function (callback) {
-    // 参数校验
-    if (typeof callback !== 'function') {
-        throw new TypeError('callback must be function');
-    }
-
-    let transaction = null;
-    let transaction_executed = false;
-
-    try {
-        transaction = await this.beginTransaction();
-        const result = await callback(transaction);
-
-        // 检查事务是否已由用户手动提交/回滚
-        if (transaction._is_ended && !transaction._is_ended()) {
-            await transaction.commit();
-        }
-
-        transaction_executed = true;
-        return result;
-    } catch (error) {
-        if (transaction && !transaction_executed) {
-            // 只有在事务未成功执行的情况下才回滚
-            if (transaction._is_ended && !transaction._is_ended()) {
-                await transaction.rollback().catch(err => {
-                    this.logger('error', '事务回滚失败', err);
-                });
-            }
-        }
-
-        this.logger('error', '事务执行失败', error);
-        throw error; // 重新抛出错误，让调用方知道事务失败
-    }
-};
-
-/**
- * 读取整张表的数据（改进版）
- * @param {String} table - 表名
- * @param {Object} condition - 查询条件
- * @param {Object} options - 选项（orderBy, limit, offset等）
- * @returns {Promise<Array>}
- * @throws {TypeError} 当table参数无效时
- */
-Mysql.prototype.read = async function (table, condition = {}, options = {}) {
-    // 参数校验
-    if (typeof table !== 'string' || table.trim() === '') {
-        throw new TypeError('table must be non-empty string');
-    }
-    if (condition && typeof condition !== 'object') {
-        throw new TypeError('condition must be object');
-    }
-    if (options && typeof options !== 'object') {
-        throw new TypeError('options must be object');
-    }
-
-    try {
-        let sql = `SELECT * FROM ${table}`;
-        const params = [];
-
-        // 处理条件
-        if (Object.keys(condition).length > 0) {
-            const whereClauses = [];
-            for (const [field, value] of Object.entries(condition)) {
-                whereClauses.push(`${field} = ?`);
-                params.push(value);
-            }
-            sql += ` WHERE ${whereClauses.join(' AND ')}`;
-        }
-
-        // 处理排序
-        if (options.orderBy) {
-            sql += ` ORDER BY ${options.orderBy}`;
-        }
-
-        // 处理分页
-        if (options.limit) {
-            sql += ` LIMIT ${options.limit}`;
-        }
-
-        if (options.offset) {
-            sql += ` OFFSET ${options.offset}`;
-        }
-
-        // 执行查询
-        return await this.run(sql, params);
-    } catch (error) {
-        this.logger('error', '查询失败', error);
-        throw error; // 重新抛出错误，让调用方知道查询失败
-    }
-};
-
-/**
- * 获取连接池状态信息
- * @returns {Object} 连接池状态对象
- */
-Mysql.prototype.getPoolStats = function () {
-    if (!this._pool) {
-        return {
-            status: 'not_initialized',
-            message: '连接池未初始化'
-        };
-    }
-
-    return {
-        status: 'healthy'
-    };
-};
-
-/**
- * 健康检查
- * @returns {Promise<Object>} 健康检查结果
- */
-Mysql.prototype.healthCheck = async function () {
-    try {
-        if (!this._pool && !this._connection) {
-            return {
-                status: 'error',
-                message: '数据库连接未初始化'
-            };
-        }
-
-        // 执行简单的查询来检查连接状态
-        const result = await this.run('SELECT 1 as health_check');
-
-        if (result && result.length > 0 && result[0].health_check === 1) {
-            return {
-                status: 'healthy',
-                message: '数据库连接正常',
-                ...this.getPoolStats()
-            };
-        } else {
-            return {
-                status: 'error',
-                message: '健康检查查询失败'
-            };
-        }
-    } catch (error) {
-        this.logger('error', '健康检查失败', error);
-        return {
-            status: 'error',
-            message: `健康检查失败: ${error.message}`
-        };
-    }
-};
-
-/**
- * 获取数据库管理器（保持兼容性）
- * @returns {Object} DB实例
- */
-Mysql.prototype.db = function () {
-    return new DB(this);
-};
-
-/**
- * 初始化MySQL服务（保持兼容性）
- * @returns {Promise<void>}
- */
-Mysql.prototype.init = async function () {
-    await this.open();
-};
-
-/**
- * 导出模块
- */
-exports.Mysql = Mysql;
-
-/**
- * 确保连接池对象存在
- */
-if (!$.pool) {
-    $.pool = {};
-}
-if (!$.pool.mysql) {
-    $.pool.mysql = {};
-}
-
-/**
- * 全局锁对象，用于线程安全
- */
-if (!$.pool.mysql._locks) {
-    $.pool.mysql._locks = {};
-}
-
-/**
- * 获取锁
- * @param {string} key - 锁的键名
- * @returns {Promise<Function>} 释放锁的函数
- */
-function _acquireLock(key) {
-    if (!$.pool.mysql._locks[key]) {
-        $.pool.mysql._locks[key] = Promise.resolve();
-    }
-
-    let release;
-    const lockPromise = $.pool.mysql._locks[key].then(() => {
-        return new Promise(resolve => {
-            release = resolve;
-        });
-    });
-
-    $.pool.mysql._locks[key] = lockPromise;
-    return lockPromise.then(() => release);
-}
-
-/**
- * @description Mysql管理器，用于创建缓存（线程安全版）
- * @param {String} scope 作用域
- * @param {Object} config 配置参数
- * @return {Object} 返回一个Mysql类实例
- */
-function mysqlAdmin(scope, config) {
-    if (!scope) {
-        scope = 'sys';
-    }
-
-    // 检查是否已存在实例
-    if ($.pool.mysql[scope]) {
-        return $.pool.mysql[scope];
-    }
-
-    // 同步方式创建实例（无需锁，因为Node.js是单线程的）
-    if (!$.pool.mysql[scope]) {
-        $.pool.mysql[scope] = new Mysql(config);
-    }
-
-    return $.pool.mysql[scope];
-}
-
-/**
- * @module 导出Mysql管理器
- */
+const mysql = require('mysql2/promise');
+const { Base } = require('mm_expand');
+const { DB } = require('./db');
+
+/**
+ * 优化版MySQL数据库操作类
+ * 保持必要功能，简化过度封装，直接使用mysql2模块
+ * @class Mysql
+ * @augments Base
+ */
+class Mysql extends Base {
+  /**
+   * 默认配置
+   * MySQL2支持的连接池配置参数：
+   * - host, port, user, password, database
+   * - charset, timezone, connect_timeout
+   * - connection_limit, acquire_timeout, wait_for_connections
+   * - queueLimit参数在MySQL2中可能不被支持，已移除
+   */
+  static default_config = {
+    host: '127.0.0.1',
+    port: 3306,
+    user: 'root',
+    password: 'Asd159357',
+    database: '',
+    charset: 'utf8mb4',
+    timezone: '+08:00',
+    connect_timeout: 20000,
+    connection_limit: 10,
+    acquire_timeout: 20000,
+    wait_for_connections: true
+  };
+
+  /**
+   * 构造函数
+   * @param {object} config - 配置对象
+   */
+  constructor(config = {}) {
+    super({ ...Mysql.default_config, ...config});
+    this._pool = null;
+    this._connection = null;
+    this._usePool = this.config.connection_limit > 1;
+  }
+}
+
+/**
+ * 获取MySQL2支持的配置参数
+ * 根据连接类型（连接池或单连接）过滤参数，避免警告
+ * @param {boolean} is_pool - 是否为连接池配置
+ * @returns {object} 过滤后的配置对象
+ */
+Mysql.prototype._getValidConfig = function (is_pool = false) {
+  // 基础连接参数（适用于所有连接类型）
+  const base_map = {
+    'host': 'host',
+    'port': 'port',
+    'user': 'user',
+    'password': 'password',
+    'database': 'database',
+    'charset': 'charset',
+    'timezone': 'timezone',
+    'connect_timeout': 'connectTimeout'
+  };
+
+  // 连接池专用参数
+  const pool_map = {
+    'connection_limit': 'connectionLimit',
+    'wait_for_connections': 'waitForConnections',
+    'idle_timeout': 'idleTimeout',
+    'max_idle': 'maxIdle'
+  };
+
+  const config = {};
+
+  // 添加基础参数
+  for (const key in base_map) {
+    if (this.config[key] !== undefined) {
+      config[base_map[key]] = this.config[key];
+    }
+  }
+
+  // 如果是连接池，添加连接池专用参数
+  if (is_pool) {
+    for (const key in pool_map) {
+      if (this.config[key] !== undefined) {
+        config[pool_map[key]] = this.config[key];
+      }
+    }
+  }
+  // 如果是单连接，确保不包含任何连接池专用参数
+  else {
+    // 移除所有连接池专用参数，避免mysql2内部警告
+    for (const key in pool_map) {
+      if (pool_map[key] in config) {
+        delete config[pool_map[key]];
+      }
+    }
+  }
+
+  return config;
+};
+
+/**
+ * 打开数据库连接
+ * @returns {Promise<boolean>}
+ * @throws {TypeError} 当配置参数无效时
+ */
+Mysql.prototype.open = async function () {
+  // 参数校验
+  if (!this.config || typeof this.config !== 'object') {
+    throw new TypeError('config must be object');
+  }
+
+  try {
+    if (this._usePool) {
+      // 根据连接类型获取对应的配置参数
+      const valid_config = this._getValidConfig(this._usePool);
+      this._pool = mysql.createPool(valid_config);
+      // 测试连接池连接
+      const conn = await this._pool.getConnection();
+      conn.release();
+    } else {
+      const valid_config = this._getValidConfig(this._usePool);
+      this._connection = await mysql.createConnection(valid_config);
+    }
+
+    this.log('info', '数据库连接成功');
+    return true;
+  } catch (error) {
+    this.log('error', '数据库连接失败', error);
+    return false;
+  }
+};
+
+/**
+ * 关闭数据库连接
+ * @returns {Promise<boolean>}
+ */
+Mysql.prototype.close = async function () {
+  try {
+    if (this._pool) {
+      await this._pool.end();
+      this._pool = null;
+    }
+    if (this._connection) {
+      await this._connection.end();
+      this._connection = null;
+    }
+
+    this.log('info', '数据库连接已关闭');
+    return true;
+  } catch (error) {
+    this.log('error', '关闭连接失败', error);
+    return false;
+  }
+};
+
+/**
+ * 安全释放数据库连接
+ * @param {object} conn - 数据库连接对象
+ * @param {boolean} is_pool_conn - 是否为连接池连接
+ * @returns {Promise<void>}
+ */
+async function safeReleaseConnection(conn, is_pool_conn) {
+  if (!conn) return;
+
+  try {
+    if (is_pool_conn && typeof conn.release === 'function') {
+      await conn.release();
+    }
+  } catch (release_err) {
+    $.log.error('释放连接失败', release_err);
+  }
+};
+
+/**
+ * 获取数据库连接（改进版）
+ * @returns {Promise<object>}
+ * @throws {TypeError} 当连接池或连接不存在时
+ */
+Mysql.prototype.getConn = async function () {
+  // 参数校验
+  if (!this._pool && !this._connection) {
+    await this.open();
+  }
+
+  try {
+    if (this._usePool) {
+      const conn = await this._pool.getConnection();
+      return conn;
+    } else {
+      return this._connection;
+    }
+  } catch (error) {
+    this.log('error', '获取连接失败', error);
+  }
+  return null;
+};
+
+/**
+ * 执行SQL查询（改进版）
+ * @param {string} sql - SQL语句
+ * @param {Array} params - 参数数组
+ * @returns {Promise<object>}
+ * @throws {TypeError} 当sql参数无效时
+ */
+Mysql.prototype.run = async function (sql, params = []) {
+  // 参数校验
+  if (typeof sql !== 'string' || sql.trim() === '') {
+    throw new TypeError('sql must be non-empty string');
+  }
+  if (!Array.isArray(params)) {
+    throw new TypeError('params must be array');
+  }
+
+  this.error = null;
+  let conn = null;
+  let is_pool_conn = false;
+  let connection_released = false;
+
+  try {
+    // 获取连接
+    conn = await this.getConn();
+    is_pool_conn = this._usePool;
+
+    // 直接使用mysql2的query方法
+    const [rows] = await conn.query(sql, params);
+    return rows;
+  } catch (err) {
+    this.sql = err.sql;
+    this.error = {
+      code: err.errno,
+      message: err.sqlMessage
+    };
+    // 在错误情况下也要确保连接释放
+    try {
+      await safeReleaseConnection(conn, is_pool_conn);
+    } catch (release_err) {
+      this.log('error', '释放连接失败', release_err);
+    }
+    connection_released = true;
+  } finally {
+    // 确保连接被释放，避免资源泄漏
+    if (!connection_released) {
+      try {
+        await safeReleaseConnection(conn, is_pool_conn);
+      } catch (release_err) {
+        this.log('error', '释放连接失败', release_err);
+      }
+    }
+  }
+  return [];
+};
+
+/**
+ * 执行SQL语句（改进版）
+ * @param {string} sql - SQL语句
+ * @param {Array} params - 参数数组
+ * @returns {Promise<object>}
+ * @throws {TypeError} 当sql参数无效时
+ */
+Mysql.prototype.exec = async function (sql, params = []) {
+  // 参数校验
+  if (typeof sql !== 'string' || sql.trim() === '') {
+    throw new TypeError('sql must be non-empty string');
+  }
+  if (!Array.isArray(params)) {
+    throw new TypeError('params must be array');
+  }
+  this.error = null;
+  let conn = null;
+  let is_pool_conn = false;
+  let connection_released = false;
+
+  try {
+    // 获取连接
+    conn = await this.getConn();
+    is_pool_conn = this._usePool;
+
+    // 直接使用mysql2的execute方法
+    const [result] = await conn.execute(sql, params);
+    return result.insertId || result.affectedRows || result.changedRows || 1;
+  } catch (error) {
+    this.log('error', 'SQL执行失败', error);
+    this.sql = error.sql;
+    this.error = {
+      code: error.errno,
+      message: error.sqlMessage
+    };
+    // 在错误情况下也要确保连接释放
+    try {
+      await safeReleaseConnection(conn, is_pool_conn);
+    } catch (release_err) {
+      this.log('error', '释放连接失败', release_err);
+    }
+    connection_released = true;
+  } finally {
+    // 确保连接被释放，避免资源泄漏
+    if (!connection_released) {
+      try {
+        await safeReleaseConnection(conn, is_pool_conn);
+      } catch (release_err) {
+        this.log('error', '释放连接失败', release_err);
+      }
+    }
+  }
+  return 0;
+};
+
+/**
+ * 开始事务（改进版）
+ * @returns {Promise<object>} 事务连接对象
+ */
+Mysql.prototype.beginTransaction = async function () {
+  let conn = null;
+  let transaction_committed = false;
+  let transaction_rolled_back = false;
+
+  try {
+    conn = await this.getConn();
+    await conn.beginTransaction();
+
+    return {
+      connection: conn,
+      commit: async () => {
+        if (transaction_committed || transaction_rolled_back) {
+          this.log('warn', '事务已结束，无需重复提交');
+          return;
+        }
+        await conn.commit();
+        transaction_committed = true;
+        try {
+          await safeReleaseConnection(conn, this._usePool);
+        } catch (release_err) {
+          this.log('error', '提交时释放连接失败', release_err);
+        }
+      },
+      rollback: async () => {
+        if (transaction_committed || transaction_rolled_back) {
+          this.log('warn', '事务已结束，无需重复回滚');
+          return;
+        }
+        await conn.rollback();
+        transaction_rolled_back = true;
+        try {
+          await safeReleaseConnection(conn, this._usePool);
+        } catch (release_err) {
+          this.log('error', '回滚时释放连接失败', release_err);
+        }
+      },
+      _is_ended: () => transaction_committed || transaction_rolled_back
+    };
+  } catch (error) {
+    // 如果事务开始失败，确保连接被释放
+    try {
+      await safeReleaseConnection(conn, this._usePool);
+    } catch (release_err) {
+      this.log('error', '释放连接失败', release_err);
+    }
+    this.log('error', '事务开始失败', error);
+    throw error;
+  }
+};
+
+/**
+ * 在事务中执行多个操作（改进版）
+ * @param {Function} callback - 包含事务操作的回调函数
+ * @returns {Promise<*>} 回调函数的返回值
+ * @throws {TypeError} 当callback参数无效时
+ */
+Mysql.prototype.transaction = async function (callback) {
+  // 参数校验
+  if (typeof callback !== 'function') {
+    throw new TypeError('callback must be function');
+  }
+
+  let transaction = null;
+  let transaction_executed = false;
+
+  try {
+    transaction = await this.beginTransaction();
+    const result = await callback(transaction);
+
+    // 检查事务是否已由用户手动提交/回滚
+    if (transaction._is_ended && !transaction._is_ended()) {
+      await transaction.commit();
+    }
+
+    transaction_executed = true;
+    return result;
+  } catch (error) {
+    if (transaction && !transaction_executed) {
+      // 只有在事务未成功执行的情况下才回滚
+      if (transaction._is_ended && !transaction._is_ended()) {
+        await transaction.rollback().catch(err => {
+          this.log('error', '事务回滚失败', err);
+        });
+      }
+    }
+
+    this.log('error', '事务执行失败', error);
+    throw error; // 重新抛出错误，让调用方知道事务失败
+  }
+};
+
+/**
+ * 读取整张表的数据（改进版）
+ * @param {string} table - 表名
+ * @param {object} condition - 查询条件
+ * @param {object} options - 选项（orderBy, limit, offset等）
+ * @returns {Promise<Array>}
+ * @throws {TypeError} 当table参数无效时
+ */
+Mysql.prototype.read = async function (table, condition = {}, options = {}) {
+  // 参数校验
+  if (typeof table !== 'string' || table.trim() === '') {
+    throw new TypeError('table must be non-empty string');
+  }
+  if (condition && typeof condition !== 'object') {
+    throw new TypeError('condition must be object');
+  }
+  if (options && typeof options !== 'object') {
+    throw new TypeError('options must be object');
+  }
+
+  try {
+    let sql = `SELECT * FROM ${table}`;
+    const params = [];
+
+    // 处理条件
+    if (Object.keys(condition).length > 0) {
+      const whereClauses = [];
+      for (const [field, value] of Object.entries(condition)) {
+        whereClauses.push(`${field} = ?`);
+        params.push(value);
+      }
+      sql += ` WHERE ${whereClauses.join(' AND ')}`;
+    }
+
+    // 处理排序
+    if (options.orderBy) {
+      sql += ` ORDER BY ${options.orderBy}`;
+    }
+
+    // 处理分页
+    if (options.limit) {
+      sql += ` LIMIT ${options.limit}`;
+    }
+
+    if (options.offset) {
+      sql += ` OFFSET ${options.offset}`;
+    }
+
+    // 执行查询
+    return await this.run(sql, params);
+  } catch (error) {
+    this.log('error', '查询失败', error);
+    throw error; // 重新抛出错误，让调用方知道查询失败
+  }
+};
+
+/**
+ * 获取连接池状态信息
+ * @returns {object} 连接池状态对象
+ */
+Mysql.prototype.getPoolStats = function () {
+  if (!this._pool) {
+    return {
+      status: 'not_initialized',
+      message: '连接池未初始化'
+    };
+  }
+
+  return {
+    status: 'healthy'
+  };
+};
+
+/**
+ * 健康检查
+ * @returns {Promise<object>} 健康检查结果
+ */
+Mysql.prototype.healthCheck = async function () {
+  try {
+    if (!this._pool && !this._connection) {
+      return {
+        status: 'error',
+        message: '数据库连接未初始化'
+      };
+    }
+
+    // 执行简单的查询来检查连接状态
+    const result = await this.run('SELECT 1 as health_check');
+
+    if (result && result.length > 0 && result[0].health_check === 1) {
+      return {
+        status: 'healthy',
+        message: '数据库连接正常',
+        ...this.getPoolStats()
+      };
+    } else {
+      return {
+        status: 'error',
+        message: '健康检查查询失败'
+      };
+    }
+  } catch (error) {
+    this.log('error', '健康检查失败', error);
+    return {
+      status: 'error',
+      message: `健康检查失败: ${error.message}`
+    };
+  }
+};
+
+/**
+ * 获取数据库管理器（保持兼容性）
+ * @returns {object} DB实例
+ */
+Mysql.prototype.db = function () {
+  return new DB(this);
+};
+
+/**
+ * 初始化MySQL服务（保持兼容性）
+ * @returns {Promise<void>}
+ */
+Mysql.prototype.init = async function () {
+  await this.open();
+};
+
+/**
+ * 导出模块
+ */
+exports.Mysql = Mysql;
+
+/**
+ * 确保连接池对象存在
+ */
+if (!$.pool) {
+  $.pool = {};
+}
+if (!$.pool.mysql) {
+  $.pool.mysql = {};
+}
+
+/**
+ * 全局锁对象，用于线程安全
+ */
+if (!$.pool.mysql._locks) {
+  $.pool.mysql._locks = {};
+}
+
+/**
+ * 获取锁
+ * @param {string} key - 锁的键名
+ * @returns {Promise<Function>} 释放锁的函数
+ */
+function _acquireLock(key) {
+  if (!$.pool.mysql._locks[key]) {
+    $.pool.mysql._locks[key] = Promise.resolve();
+  }
+
+  let release;
+  const lockPromise = $.pool.mysql._locks[key].then(() => {
+    return new Promise(resolve => {
+      release = resolve;
+    });
+  });
+
+  $.pool.mysql._locks[key] = lockPromise;
+  return lockPromise.then(() => release);
+}
+
+/**
+ * @description Mysql管理器，用于创建缓存（线程安全版）
+ * @param {string} scope 作用域
+ * @param {object} config 配置参数
+ * @returns {object} 返回一个Mysql类实例
+ */
+function mysqlAdmin(scope, config) {
+  if (!scope) {
+    scope = 'sys';
+  }
+
+  // 检查是否已存在实例
+  if ($.pool.mysql[scope]) {
+    return $.pool.mysql[scope];
+  }
+
+  // 同步方式创建实例（无需锁，因为Node.js是单线程的）
+  if (!$.pool.mysql[scope]) {
+    $.pool.mysql[scope] = new Mysql(config);
+  }
+
+  return $.pool.mysql[scope];
+}
+
+/**
+ * @module 导出Mysql管理器
+ */
 exports.mysqlAdmin = mysqlAdmin;