mm_mysql 2.5.6 → 2.5.7

package/example/index.js

@@ -0,0 +1,40 @@
+/**
+ * mm_mysql 最小可运行示例
+ * @description 演示 Mysql 类的实例化、工厂获取实例与核心方法存在性。
+ * 注意：不会真正连接 MySQL 服务；host/user/password 为示例假值，实际使用时请替换为真实配置。
+ */
+const { Mysql, mysqlAdmin } = require('../index.js');
+
+/** 示例假配置（实际使用时替换为真实 MySQL 连接信息） */
+const CONFIG = {
+  host: '127.0.0.1',
+  port: 3306,
+  user: 'root',
+  password: 'change_me',
+  database: 'example_db'
+};
+
+/**
+ * 主函数
+ */
+function main() {
+  console.log('== mm_mysql 示例开始 ==');
+
+  // 实例化（仅合并配置，不建立真实连接）
+  const db = new Mysql(CONFIG);
+  console.log('实例化 Mysql 成功');
+  console.log('配置读取:', db.config.host + ':' + db.config.port + '/' + db.config.database);
+
+  // 通过工厂函数获取按作用域缓存的实例
+  const cache = mysqlAdmin('example', CONFIG);
+  console.log('mysqlAdmin 获取实例:', cache instanceof Mysql);
+
+  // 核心方法存在性检查（不真正执行，避免连接外部服务）
+  const METHODS = ['open', 'close', 'getConn', 'run', 'exec', 'transaction', 'db', 'table', 'healthCheck'];
+  const missing = METHODS.filter((name) => typeof cache[name] !== 'function');
+  console.log('核心方法检查:', missing.length === 0 ? '全部存在' : '缺失: ' + missing.join(','));
+
+  console.log('== mm_mysql 示例结束 ==');
+}
+
+main();

package/index.js

@@ -1,574 +1,24 @@
-const mysql = require('mysql2/promise');
-const { Base } = require('mm_expand');
-const { DB } = require('./db');
-
-/**
- * 优化版MySQL数据库操作类
- * 保持必要功能，简化过度封装，直接使用mysql2模块
- * @class Mysql
- * @augments Base
- */
-class Mysql extends Base {
-  /**
-   * 默认配置（优化版，统一使用连接池）
-   */
-  static config = {
-    name: 'default',
-    host: '127.0.0.1',
-    port: 3306,
-    user: 'root',
-    password: 'Asd159357',
-    database: '',
-    charset: 'utf8mb4',
-    timezone: '+08:00',
-    connect_timeout: 15000,
-
-    // 连接池优化配置（针对高并发写入场景）
-    connection_limit: 100,           // 减少连接数，避免资源竞争
-    acquire_timeout: 30000,          // 延长获取连接超时时间
-    wait_for_connections: true,      // 保持连接等待机制
-    idle_timeout: 300000,            // 延长空闲连接超时时间(5分钟)
-    max_idle: 30,                    // 减少最大空闲连接数
-    queue_timeout: 60000,            // 队列超时时间
-  };
-
-  /**
-   * 构造函数（统一使用连接池）
-   * @param {object} config - 配置对象
-   */
-  constructor(config = {}) {
-    super(config);
-    this._pool = null;
-    // 移除单连接支持，统一使用连接池
-
-    // 错误信息（注意：同 scope 下为单例共享，并发时以最后一次写入为准）
-    this.error = null;
-    // 最近执行的SQL语句
-    this.sql = '';
-  }
-}
-
-/**
- * 获取MySQL2支持的配置参数
- * 根据连接类型（连接池或单连接）过滤参数，避免警告
- * @param {boolean} is_pool - 是否为连接池配置
- * @returns {object} 过滤后的配置对象
- */
-Mysql.prototype._getValidConfig = function (is_pool = false) {
-  // 基础连接参数（适用于所有连接类型）
-  let base_map = {
-    'host': 'host',
-    'port': 'port',
-    'user': 'user',
-    'password': 'password',
-    'database': 'database',
-    'charset': 'charset',
-    'timezone': 'timezone',
-    'connect_timeout': 'connectTimeout'
-  };
-
-  // 连接池专用参数
-  let pool_map = {
-    'connection_limit': 'connectionLimit',
-    'wait_for_connections': 'waitForConnections',
-    'idle_timeout': 'idleTimeout',
-    'max_idle': 'maxIdle'
-  };
-
-  let config = {};
-
-  // 添加基础参数
-  for (let key in base_map) {
-    if (this.config[key] !== undefined) {
-      config[base_map[key]] = this.config[key];
-    }
-  }
-
-  // 如果是连接池，添加连接池专用参数
-  if (is_pool) {
-    for (let key in pool_map) {
-      if (this.config[key] !== undefined) {
-        config[pool_map[key]] = this.config[key];
-      }
-    }
-  }
-  // 如果是单连接，确保不包含任何连接池专用参数
-  else {
-    // 移除所有连接池专用参数，避免mysql2内部警告
-    for (let 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 {
-    // 统一使用连接池模式
-    let valid_config = this._getValidConfig(true);
-    this._pool = mysql.createPool(valid_config);
-
-    // 测试连接池连接
-    let conn = await this._pool.getConnection();
-    conn.release();
-    return true;
-  } catch (error) {
-    this.log('error', '数据库连接池创建失败', error);
-    return false;
-  }
-};
-
-/**
- * 关闭数据库连接（统一使用连接池）
- * @returns {Promise<boolean>}
- */
-Mysql.prototype.close = async function () {
-  if (!this._pool) {
-    return true;
-  }
-  try {
-    await this._pool.end();
-    this._pool = null;
-    this.log('info', '数据库连接池已关闭');
-    return true;
-  } catch (error) {
-    this.log('error', '关闭连接池失败', error);
-    return false;
-  }
-};
-
-/**
-   * 获取数据库连接（统一使用连接池）
-   * @returns {Promise<object>}
-   * @throws {TypeError} 当连接池不存在时
-   */
-Mysql.prototype.getConn = async function () {
-  // 连接池不存在则创建
-  if (!this._pool) {
-    await this.open();
-  }
-  // 连接池可能已被外部关闭，检测并重建
-  if (this._pool._closed) {
-    await this.open();
-  }
-
-  return await this._pool.getConnection();
-};
-
-/**
- * 执行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;
-  this.sql = '';
-  let conn = null;
-  let ret = [];
-  try {
-    conn = await this.getConn();
-    this.sql = sql;
-    let [rows] = await conn.query(sql, params);
-    ret = rows;
-  } catch (err) {
-    console.error('SQL执行失败', err);
-    this.sql = err.sql || sql;
-    this.error = {
-      code: err.errno,
-      message: err.sqlMessage
-    };
-  }
-  finally {
-    await releaseConn(conn);
-  }
-  return ret;
-};
-
-/**
- * 执行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;
-  this.sql = '';
-  let conn = null;
-  let ret = 0;
-  try {
-    conn = await this.getConn();
-    this.sql = sql;
-    let [result] = await conn.execute(sql, params);
-    ret = result.insertId || result.affectedRows || result.changedRows || 1;
-  } catch (error) {
-    console.error('SQL执行失败', error);
-    this.sql = error.sql || sql;
-    this.error = {
-      code: error.errno,
-      message: error.sqlMessage
-    };
-  }
-  finally {
-    await releaseConn(conn);
-  }
-  return ret;
-};
-
-/**
- * 执行多语句SQL脚本（专用于导入）
- * 通过独立连接执行，不影响连接池默认配置
- * @param {string} sql - SQL脚本内容，可含多条以分号分隔的语句
- * @returns {Promise<object>} 执行结果统计对象
- * @throws {TypeError} 当sql参数无效时
- */
-Mysql.prototype.runSql = async function (sql) {
-  // 参数校验
-  if (typeof sql !== 'string' || sql.trim() === '') {
-    throw new TypeError('sql must be non-empty string');
-  }
-
-  let conn = null;
-  let ret = { success: false, statements: 0, affected_rows: 0, error: null };
-  try {
-    // 创建专用连接，仅导入连接开启多语句支持
-    let valid_config = this._getValidConfig(false);
-    valid_config.multipleStatements = true;
-    conn = await mysql.createConnection(valid_config);
-
-    // 执行整段SQL脚本
-    let [results] = await conn.query(sql);
-    // 统计语句数和受影响行数
-    if (Array.isArray(results)) {
-      ret.statements = results.length;
-      for (let item of results) {
-        ret.affected_rows += item.affectedRows || 0;
-      }
-    } else {
-      ret.statements = 1;
-      ret.affected_rows = results.affectedRows || 0;
-    }
-    ret.success = true;
-  } catch (error) {
-    this.error = {
-      code: error.errno,
-      message: error.sqlMessage || error.message
-    };
-    this.sql = error.sql || sql;
-    ret.error = this.error.message;
-  } finally {
-    if (conn) {
-      try {
-        await conn.end();
-      } catch (end_error) {
-        this.log('error', '关闭导入连接失败', end_error);
-      }
-    }
-  }
-  return ret;
-};
-
-/**
- * 开始事务（优化版）
- * @returns {Promise<object>} 事务连接对象
- */
-Mysql.prototype.beginTransaction = async function () {
-  let conn = await this.getConn();
-
-  try {
-    await conn.beginTransaction();
-
-    let ended = false;
-
-    return {
-      connection: conn,
-      commit: async () => {
-        if (ended) return;
-        await conn.commit();
-        ended = true;
-        await releaseConn(conn);
-      },
-      rollback: async () => {
-        if (ended) return;
-        await conn.rollback();
-        ended = true;
-        await releaseConn(conn);
-      },
-      _is_ended: () => ended
-    };
-  } catch (error) {
-    // 如果事务开始失败，确保连接被释放
-    await releaseConn(conn);
-    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 = await this.beginTransaction();
-
-  try {
-    let result = await callback(transaction);
-
-    // 如果事务未结束，自动提交
-    if (!transaction._is_ended()) {
-      await transaction.commit();
-    }
-
-    return result;
-  } catch (error) {
-    // 如果事务未结束，自动回滚
-    if (!transaction._is_ended()) {
-      await transaction.rollback().catch(() => {
-        // 简化错误处理，避免频繁日志
-      });
-    }
-
-    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}`;
-    let params = [];
-
-    // 处理条件
-    if (Object.keys(condition).length > 0) {
-      let whereClauses = [];
-      for (let [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) {
-      return {
-        status: 'error',
-        message: '数据库连接未初始化'
-      };
-    }
-
-    // 执行简单的查询来检查连接状态
-    let 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);
-};
-
-/**
- * 获取表管理器（语法糖，等同于 db().new(name, key)）
- * @param {string} name 表名
- * @param {string} key 主键字段名
- * @returns {object} DB表管理器实例
- */
-Mysql.prototype.table = function (name, key) {
-  if (typeof name !== 'string' || name.trim() === '') {
-    throw new TypeError('name must be non-empty string');
-  }
-  var db = this.db();
-  db.table = name;
-  if (key) {
-    db.key = key;
-  }
-  return db;
-};
-
-/**
- * 初始化MySQL服务（保持兼容性）
- * @returns {Promise<void>}
- */
-Mysql.prototype.init = async function () {
-  await this.open();
-};
-
-/**
- * 导出模块
- */
-exports.Mysql = Mysql;
-
-/**
- * 确保连接池对象存在
- */
-if (!$.pool) {
-  $.pool = {};
-}
-if (!$.pool.mysql) {
-  $.pool.mysql = {};
-}
-
-/**
- * @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];
-}
-
-/**
- * 安全释放数据库连接
- * @param {object} conn - 数据库连接对象
- * @returns {Promise<void>}
- */
-async function releaseConn(conn) {
-  if (!conn) return;
-
-  try {
-    if (typeof conn.release === 'function') {
-      await conn.release();
-    }
-  } catch (release_err) {
-    $.log.error('释放连接失败', release_err);
-  }
-};
-
-/**
- * @module 导出Mysql管理器
- */
-exports.mysqlAdmin = mysqlAdmin;
+/**
+ * mm_mysql MySQL数据库模块
+ * @description 参考 mm_redis 结构，index.js 为薄包装，类定义在 lib/mysql.js
+ */
+const Mysql = require('./lib/mysql');
+const Admin = require('mm_corejs').Admin;
+
+/**
+ * Mysql 管理器实例（Admin 工厂）
+ * 支持 os.js 调用：require('mm_mysql').admin.setServer(os) -> admin.get('os', config)
+ */
+let admin = new Admin();
+admin.setClass(Mysql);
+
+module.exports = {
+  Mysql,
+  admin,
+  mysqlAdmin(scope, config) {
+    if (!scope) {
+      scope = 'os';
+    }
+    return admin.get(scope, config);
+  }
+};

package/lib/mysql.js

@@ -0,0 +1,532 @@
+const mysql = require('mysql2/promise');
+const { Base } = require('mm_mod');
+const { DB } = require('./db');
+
+/**
+ * 优化版MySQL数据库操作类
+ * 保持必要功能，简化过度封装，直接使用mysql2模块
+ * @class Mysql
+ * @augments Base
+ */
+class Mysql extends Base {
+  /**
+   * 默认配置（优化版，统一使用连接池）
+   */
+  static config = {
+    name: 'default',
+    host: '127.0.0.1',
+    port: 3306,
+    user: 'root',
+    password: 'Asd159357',
+    database: '',
+    charset: 'utf8mb4',
+    timezone: '+08:00',
+    connect_timeout: 15000,
+
+    // 连接池优化配置（针对高并发写入场景）
+    connection_limit: 100,           // 减少连接数，避免资源竞争
+    acquire_timeout: 30000,          // 延长获取连接超时时间
+    wait_for_connections: true,      // 保持连接等待机制
+    idle_timeout: 300000,            // 延长空闲连接超时时间(5分钟)
+    max_idle: 30,                    // 减少最大空闲连接数
+    queue_timeout: 60000,            // 队列超时时间
+  };
+
+  /**
+   * 构造函数（统一使用连接池）
+   * @param {object} config - 配置对象
+   */
+  constructor(config = {}) {
+    super(config);
+    this._pool = null;
+    // 移除单连接支持，统一使用连接池
+
+    // 错误信息（注意：同 scope 下为单例共享，并发时以最后一次写入为准）
+    this.error = null;
+    // 最近执行的SQL语句
+    this.sql = '';
+  }
+}
+
+/**
+ * 获取MySQL2支持的配置参数
+ * 根据连接类型（连接池或单连接）过滤参数，避免警告
+ * @param {boolean} is_pool - 是否为连接池配置
+ * @returns {object} 过滤后的配置对象
+ */
+Mysql.prototype._getValidConfig = function (is_pool = false) {
+  // 基础连接参数（适用于所有连接类型）
+  let base_map = {
+    'host': 'host',
+    'port': 'port',
+    'user': 'user',
+    'password': 'password',
+    'database': 'database',
+    'charset': 'charset',
+    'timezone': 'timezone',
+    'connect_timeout': 'connectTimeout'
+  };
+
+  // 连接池专用参数
+  let pool_map = {
+    'connection_limit': 'connectionLimit',
+    'wait_for_connections': 'waitForConnections',
+    'idle_timeout': 'idleTimeout',
+    'max_idle': 'maxIdle'
+  };
+
+  let config = {};
+
+  // 添加基础参数
+  for (let key in base_map) {
+    if (this.config[key] !== undefined) {
+      config[base_map[key]] = this.config[key];
+    }
+  }
+
+  // 如果是连接池，添加连接池专用参数
+  if (is_pool) {
+    for (let key in pool_map) {
+      if (this.config[key] !== undefined) {
+        config[pool_map[key]] = this.config[key];
+      }
+    }
+  }
+  // 如果是单连接，确保不包含任何连接池专用参数
+  else {
+    // 移除所有连接池专用参数，避免mysql2内部警告
+    for (let 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 {
+    // 统一使用连接池模式
+    let valid_config = this._getValidConfig(true);
+    this._pool = mysql.createPool(valid_config);
+
+    // 测试连接池连接
+    let conn = await this._pool.getConnection();
+    conn.release();
+    return true;
+  } catch (error) {
+    this.log('error', '数据库连接池创建失败', error);
+    return false;
+  }
+};
+
+/**
+ * 关闭数据库连接（统一使用连接池）
+ * @returns {Promise<boolean>}
+ */
+Mysql.prototype.close = async function () {
+  if (!this._pool) {
+    return true;
+  }
+  try {
+    await this._pool.end();
+    this._pool = null;
+    this.log('info', '数据库连接池已关闭');
+    return true;
+  } catch (error) {
+    this.log('error', '关闭连接池失败', error);
+    return false;
+  }
+};
+
+/**
+   * 获取数据库连接（统一使用连接池）
+   * @returns {Promise<object>}
+   * @throws {TypeError} 当连接池不存在时
+   */
+Mysql.prototype.getConn = async function () {
+  // 连接池不存在则创建
+  if (!this._pool) {
+    await this.open();
+  }
+  // 连接池可能已被外部关闭，检测并重建
+  if (this._pool._closed) {
+    await this.open();
+  }
+
+  return await this._pool.getConnection();
+};
+
+/**
+ * 执行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;
+  this.sql = '';
+  let conn = null;
+  let ret = [];
+  try {
+    conn = await this.getConn();
+    this.sql = sql;
+    let [rows] = await conn.query(sql, params);
+    ret = rows;
+  } catch (err) {
+    console.error('SQL执行失败', err);
+    this.sql = err.sql || sql;
+    this.error = {
+      code: err.errno,
+      message: err.sqlMessage
+    };
+  }
+  finally {
+    await releaseConn(conn);
+  }
+  return ret;
+};
+
+/**
+ * 执行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;
+  this.sql = '';
+  let conn = null;
+  let ret = 0;
+  try {
+    conn = await this.getConn();
+    this.sql = sql;
+    let [result] = await conn.execute(sql, params);
+    ret = result.insertId || result.affectedRows || result.changedRows || 1;
+  } catch (error) {
+    console.error('SQL执行失败', error);
+    this.sql = error.sql || sql;
+    this.error = {
+      code: error.errno,
+      message: error.sqlMessage
+    };
+  }
+  finally {
+    await releaseConn(conn);
+  }
+  return ret;
+};
+
+/**
+ * 执行多语句SQL脚本（专用于导入）
+ * 通过独立连接执行，不影响连接池默认配置
+ * @param {string} sql - SQL脚本内容，可含多条以分号分隔的语句
+ * @returns {Promise<object>} 执行结果统计对象
+ * @throws {TypeError} 当sql参数无效时
+ */
+Mysql.prototype.runSql = async function (sql) {
+  // 参数校验
+  if (typeof sql !== 'string' || sql.trim() === '') {
+    throw new TypeError('sql must be non-empty string');
+  }
+
+  let conn = null;
+  let ret = { success: false, statements: 0, affected_rows: 0, error: null };
+  try {
+    // 创建专用连接，仅导入连接开启多语句支持
+    let valid_config = this._getValidConfig(false);
+    valid_config.multipleStatements = true;
+    conn = await mysql.createConnection(valid_config);
+
+    // 执行整段SQL脚本
+    let [results] = await conn.query(sql);
+    // 统计语句数和受影响行数
+    if (Array.isArray(results)) {
+      ret.statements = results.length;
+      for (let item of results) {
+        ret.affected_rows += item.affectedRows || 0;
+      }
+    } else {
+      ret.statements = 1;
+      ret.affected_rows = results.affectedRows || 0;
+    }
+    ret.success = true;
+  } catch (error) {
+    this.error = {
+      code: error.errno,
+      message: error.sqlMessage || error.message
+    };
+    this.sql = error.sql || sql;
+    ret.error = this.error.message;
+  } finally {
+    if (conn) {
+      try {
+        await conn.end();
+      } catch (end_error) {
+        this.log('error', '关闭导入连接失败', end_error);
+      }
+    }
+  }
+  return ret;
+};
+
+/**
+ * 开始事务（优化版）
+ * @returns {Promise<object>} 事务连接对象
+ */
+Mysql.prototype.beginTransaction = async function () {
+  let conn = await this.getConn();
+
+  try {
+    await conn.beginTransaction();
+
+    let ended = false;
+
+    return {
+      connection: conn,
+      commit: async () => {
+        if (ended) return;
+        await conn.commit();
+        ended = true;
+        await releaseConn(conn);
+      },
+      rollback: async () => {
+        if (ended) return;
+        await conn.rollback();
+        ended = true;
+        await releaseConn(conn);
+      },
+      _is_ended: () => ended
+    };
+  } catch (error) {
+    // 如果事务开始失败，确保连接被释放
+    await releaseConn(conn);
+    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 = await this.beginTransaction();
+
+  try {
+    let result = await callback(transaction);
+
+    // 如果事务未结束，自动提交
+    if (!transaction._is_ended()) {
+      await transaction.commit();
+    }
+
+    return result;
+  } catch (error) {
+    // 如果事务未结束，自动回滚
+    if (!transaction._is_ended()) {
+      await transaction.rollback().catch(() => {
+        // 简化错误处理，避免频繁日志
+      });
+    }
+
+    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}`;
+    let params = [];
+
+    // 处理条件
+    if (Object.keys(condition).length > 0) {
+      let whereClauses = [];
+      for (let [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) {
+      return {
+        status: 'error',
+        message: '数据库连接未初始化'
+      };
+    }
+
+    // 执行简单的查询来检查连接状态
+    let 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);
+};
+
+/**
+ * 获取表管理器（语法糖，等同于 db().new(name, key)）
+ * @param {string} name 表名
+ * @param {string} key 主键字段名
+ * @returns {object} DB表管理器实例
+ */
+Mysql.prototype.table = function (name, key) {
+  if (typeof name !== 'string' || name.trim() === '') {
+    throw new TypeError('name must be non-empty string');
+  }
+  var db = this.db();
+  db.table = name;
+  if (key) {
+    db.key = key;
+  }
+  return db;
+};
+
+/**
+ * 初始化钩子（由 Lifecycle.init 模板方法调用，保证状态机流转到 inited）
+ * @returns {Promise<void>}
+ */
+Mysql.prototype.onInit = async function () {
+  await this.open();
+};
+
+/**
+ * 安全释放数据库连接
+ * @param {object} conn - 数据库连接对象
+ * @returns {Promise<void>}
+ */
+async function releaseConn(conn) {
+  if (!conn) return;
+
+  try {
+    if (typeof conn.release === 'function') {
+      await conn.release();
+    }
+  } catch (release_err) {
+    console.error('释放连接失败', release_err);
+  }
+};
+
+module.exports = Mysql;

package/{sql.js → lib/sql.js}

@@ -4,7 +4,8 @@
  * @version 1.2
  */
 const SqlString = require('sqlstring');
-const { Base } = require('mm_expand');
+const { Base } = require('mm_mod');
+const { loadText, hasFile } = require('mm_helper');
 
 function escape(value, stringifyObjects, timeZone) {
   return SqlString.escape(value, stringifyObjects, timeZone);
@@ -1233,7 +1234,6 @@ Sql.prototype.tplBody = function (param_dt, sql_dt) {
  * @returns {Promise<boolean>} 是否加载成功
  */
 Sql.prototype.load = async function (file) {
-
   await this._logLoadStart(file);
   await this._validateFile(file);
   let sql_stmts = await this._readAndSplitSql(file);
@@ -1259,7 +1259,7 @@ Sql.prototype._logLoadStart = async function (file) {
  * @returns {Promise<void>}
  */
 Sql.prototype._validateFile = async function (file) {
-  if (!file.hasFile()) {
+  if (!hasFile(file)) {
     throw new Error(`SQL文件不存在: ${file}`);
   }
 };
@@ -1270,7 +1270,7 @@ Sql.prototype._validateFile = async function (file) {
  * @returns {Promise<string[]>} SQL语句数组
  */
 Sql.prototype._readAndSplitSql = async function (file) {
-  let sql_content = await $.file.readText(file);
+  let sql_content = loadText(file);
   if (!sql_content || sql_content.trim() === '') {
     throw new Error(`SQL文件内容为空: ${file}`);
   }

package/package.json

@@ -1,10 +1,12 @@
 {
 	"name": "mm_mysql",
-	"version": "2.5.6",
+	"version": "2.5.7",
 	"description": "这是超级美眉mysql帮助函数模块，用于便捷操作mysql，使用await方式，可以避免嵌套函数",
 	"main": "index.js",
 	"dependencies": {
-		"mm_expand": "^2.5.4",
+		"mm_corejs": "^1.1.4",
+		"mm_mod": "^1.0.1",
+		"mm_helper": "^1.0.0",
 		"mysql2": "^3.24.2",
 		"sqlstring": "^2.3.3"
 	},
@@ -19,6 +21,9 @@
 		"url": "https://gitee.com/qiuwenwu91/mm_mysql.git"
 	},
 	"keywords": [
+		"mm_mod",
+		"mm_adapter",
+		"mm_persist",
 		"mysql",
 		"async",
 		"await",
@@ -30,6 +35,8 @@
 		"sql",
 		"db"
 	],
+	"layer": "adapter",
+	"group": "persist",
 	"author": "qww",
 	"license": "ISC",
 	"engines": {
@@ -38,6 +45,6 @@
 	"devDependencies": {
 		"eslint": "^10.9.1",
 		"eslint-plugin-jsdoc": "^64.2.1",
-		"mm_eslint": "^1.7.6"
+		"mm_eslint": "^1.7.7"
 	}
 }

package/test.js

@@ -40,24 +40,30 @@ class TestMysql {
 TestMysql.prototype._init = async function() {
   try {
     console.log('=== 初始化测试环境（优化版） ===');
-        
+
     // 直接使用指定数据库，避免重复连接
     if (!this.config.database) {
       this.config.database = 'test_db';
     }
-        
+
+    // 先以空 database 连接并创建测试数据库，避免 Unknown database 报错
+    const bootstrap = new Mysql({ ...this.config, database: '' });
+    await bootstrap.open();
+    await bootstrap.exec(`CREATE DATABASE IF NOT EXISTS ${this.config.database}`);
+    await bootstrap.close();
+
     // 创建Mysql实例
     this._mysql = new Mysql(this.config);
-        
+
     // 连接数据库
     await this._mysql.open();
-        
+
     // 创建测试数据库（如果不存在）
     await this._createTestDatabase();
-        
+
     // 创建测试表
     await this._createTestTable();
-        
+
     console.log('测试环境初始化完成');
     return true;
   } catch (error) {