mm_mysql 2.5.7 → 2.6.0

package/index.js

@@ -3,22 +3,22 @@
  * @description 参考 mm_redis 结构，index.js 为薄包装，类定义在 lib/mysql.js
  */
 const Mysql = require('./lib/mysql');
-const Admin = require('mm_corejs').Admin;
+const { reg } = require('mm_admin');
 
 /**
  * Mysql 管理器实例（Admin 工厂）
  * 支持 os.js 调用：require('mm_mysql').admin.setServer(os) -> admin.get('os', config)
  */
-let admin = new Admin();
+const admin = reg('mm_mysql');
 admin.setClass(Mysql);
 
 module.exports = {
   Mysql,
   admin,
   mysqlAdmin(scope, config) {
-    if (!scope) {
-      scope = 'os';
-    }
-    return admin.get(scope, config);
+    return admin.get(scope || 'os', config);
   }
-};
+};
+/* mm-tool-logic-export 工具能力层：其它模块可 require("<pkg>").tools.<name> 直接引用 */
+Object.defineProperty(module.exports, 'tools', { enumerable: true, configurable: true,
+  get: function () { return require('./lib/tools'); } });

package/lib/mysql.js

@@ -1,6 +1,7 @@
 const mysql = require('mysql2/promise');
 const { Base } = require('mm_mod');
 const { DB } = require('./db');
+const makeQueryError = require('./query_error');
 
 /**
  * 优化版MySQL数据库操作类
@@ -194,12 +195,13 @@ Mysql.prototype.run = async function (sql, params = []) {
     let [rows] = await conn.query(sql, params);
     ret = rows;
   } catch (err) {
-    console.error('SQL执行失败', err);
+    // D-12：查询失败不能吞成空数组——「没数据」和「查询炸了」在业务层必须可区分
     this.sql = err.sql || sql;
     this.error = {
-      code: err.errno,
-      message: err.sqlMessage
+      code: err.errno || err.code,
+      message: err.sqlMessage || err.message
     };
+    throw makeQueryError(err, sql, params);
   }
   finally {
     await releaseConn(conn);
@@ -207,6 +209,7 @@ Mysql.prototype.run = async function (sql, params = []) {
   return ret;
 };
 
+
 /**
  * 执行SQL语句（优化版，支持预处理语句缓存）
  * @param {string} sql - SQL语句
@@ -232,12 +235,13 @@ Mysql.prototype.exec = async function (sql, params = []) {
     let [result] = await conn.execute(sql, params);
     ret = result.insertId || result.affectedRows || result.changedRows || 1;
   } catch (error) {
-    console.error('SQL执行失败', error);
+    // 写操作失败同样上浮：返回 0 会被当成「没有行受影响」正常结果
     this.sql = error.sql || sql;
     this.error = {
-      code: error.errno,
-      message: error.sqlMessage
+      code: error.errno || error.code,
+      message: error.sqlMessage || error.message
     };
+    throw makeQueryError(error, sql, params);
   }
   finally {
     await releaseConn(conn);

package/lib/query_error.js

@@ -0,0 +1,22 @@
+'use strict';
+
+/**
+ * 构造带上下文的数据层错误
+ *
+ * 独立函数而非实例方法：DB 包装层以 `super(sqlite.run, sqlite.exec)` 传递未绑定的方法引用，
+ * 调用时 this 指向 DB 实例而不是 SQLite 实例，任何 this.xxx 辅助方法都会失效。
+ * 用模块级函数可同时覆盖「SQLite 直接被调用」与「经 DB 包装调用」两条路径。
+ *
+ * @param {Error} cause 驱动抛出的原始异常
+ * @param {string} sql 出错的 SQL
+ * @param {Array} params 绑定参数
+ * @returns {Error} 携带 code / sql / params / cause 的错误对象
+ */
+module.exports = function makeQueryError(cause, sql, params) {
+  const error = new Error(`SQL执行失败: ${cause.message || cause}`);
+  error.code = cause.code || cause.errno;
+  error.sql = sql;
+  error.params = params;
+  error.cause = cause;
+  return error;
+};

package/lib/sql.js

@@ -237,6 +237,10 @@ Sql.prototype.delSql = function (where) {
  * @returns {Promise | object} 执行结果
  */
 Sql.prototype.setSql = function (where, set) {
+  // 空 SET 会拼出非法 SQL，按“无变更”处理
+  if (!set) {
+    return 0;
+  }
   // 使用直接拼接的方式，避免模板替换错误
   var sql = `UPDATE \`${this.table}\` SET ${set} WHERE ${where};`;
   return this.exec(sql);
@@ -646,6 +650,12 @@ Sql.prototype.set = async function (query, body, like) {
   if (!this.table || !body || typeof body !== 'object') {
     throw new Error('表名或数据未设置');
   }
+  // 待更新字段全为 undefined/null 时 toSet 会得到空串，
+  // 此时执行会产生 `UPDATE t SET  WHERE ...` 的非法 SQL，直接按“无变更”返回 0
+  if (!this.toSet(body)) {
+    this.sql = '';
+    return 0;
+  }
   let sql = this.toSetSql(query, body, like);
   this.sql = sql;
   let bl = await this.exec(sql);

package/lib/tools/index.js

@@ -0,0 +1,16 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+/** 模块能力层：懒加载工具实现，避免模块入口被 require 时加载全部实现 */
+module.exports = new Proxy({}, {
+  get(_t, key) {
+    if (typeof key !== 'string') return undefined;
+    if (!fs.existsSync(path.join(__dirname, key, 'index.js'))) return undefined;
+    return require('./' + key);
+  },
+  has(_t, key) {
+    return typeof key === 'string' && fs.existsSync(path.join(__dirname, key, 'index.js'));
+  },
+  ownKeys() { return fs.readdirSync(__dirname, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name); },
+  getOwnPropertyDescriptor(_t, key) { return this.has(_t, key) ? { enumerable: true, configurable: true } : undefined; }
+});

package/lib/tools/mysql/index.js

@@ -0,0 +1,208 @@
+/**
+ * MySQL管理器
+ * 管理 MySQL 连接和操作（基于 mm_mysql 连接池）
+ * SQL 方法: query/execute/upsert, ORM 方法: add/del/set/get/getObj/count
+ */
+async function main(params, ctx, options) {
+  const { mysqlAdmin } = require('mm_mysql');
+  var action = params.action || '';
+  var table = params.table || '';
+  var sql = params.sql || '';
+  var sql_params = params.params || [];
+  var query = params.query || {};
+  var body = params.body || {};
+  var unique = params.unique || [];
+
+  var opts = this.getOptions();
+
+  var mysql = mysqlAdmin('os', opts);
+  await mysql.open();
+
+  ctx.output = await dispatch(mysql, action, table, sql, sql_params, query, body, unique);
+  return ctx.output;
+}
+
+/**
+ * 分发 action 到对应的处理方法
+ */
+async function dispatch(mysql, action, table, sql, sql_params, query, body, unique) {
+  const SQL_METHODS = ['query', 'run', 'execute', 'exec', 'insert', 'update', 'delete'];
+  const ORM_METHODS = ['add', 'del', 'set', 'get', 'getObj', 'list', 'count'];
+
+  if (SQL_METHODS.indexOf(action) !== -1) {
+    return handleSql(mysql, action, sql, sql_params);
+  }
+  if (ORM_METHODS.indexOf(action) !== -1) {
+    return handleOrm(mysql, action, table, query, body);
+  }
+  if (action === 'upsert') {
+    return handleUpsert(mysql, table, body, unique);
+  }
+  if (action === 'batch') {
+    return handleBatch(mysql, sql_params);
+  }
+  if (action === 'runSql') {
+    return handleRunSql(mysql, sql);
+  }
+  return { error: { code: 'MGR_UNKNOWN_ACTION', message: '不支持的操作: ' + action } };
+}
+
+/**
+ * 处理 SQL 方法: query/run → SELECT, execute/exec → INSERT/UPDATE/DELETE
+ */
+async function handleSql(mysql, action, sql, sql_params) {
+  var is_query = action === 'query' || action === 'run';
+  var result = is_query ? await mysql.run(sql, sql_params) : await mysql.exec(sql, sql_params);
+
+  if (mysql.error) {
+    return _errorResult('MGR_SQL_ERROR', mysql.error.message);
+  }
+  return is_query
+    ? {
+        list: Array.isArray(result) ? result : [],
+        count: Array.isArray(result) ? result.length : 0
+      }
+    : { affected: result || 0 };
+}
+
+/**
+ * 处理 ORM 方法: add/del/set/get/getObj/count
+ */
+async function handleOrm(mysql, action, table, query, body) {
+  var db = mysql.db();
+  db.table = table;
+
+  var result;
+  switch (action) {
+    case 'add':
+      result = await db.add(body);
+      break;
+    case 'del':
+      result = await db.del(query);
+      break;
+    case 'set':
+      result = await db.set(query, body);
+      break;
+    case 'list':
+      result = await db.list(query);
+      break;
+    case 'getObj':
+      result = await db.getObj(query);
+      break;
+    case 'count':
+      result = await db.count(query);
+      break;
+  }
+
+  if (db.error) {
+    return _errorResult('MGR_ORM_ERROR', db.error.message);
+  }
+  return result;
+}
+
+/**
+ * 处理 upsert: INSERT ... ON DUPLICATE KEY UPDATE
+ */
+async function handleUpsert(mysql, table, body, unique) {
+  var upsert_sql = _buildUpsert(table, body, unique);
+  var result = await mysql.exec(upsert_sql.sql, upsert_sql.params);
+
+  if (mysql.error) {
+    return _errorResult('MGR_UPSERT_ERROR', mysql.error.message);
+  }
+  return { affected: 1, id: result || 0 };
+}
+
+/**
+ * 批量执行 SQL 列表（用于建表等初始化操作）
+ * @param {object} mysql 数据库实例
+ * @param {Array} sqls SQL 语句数组
+ * @returns {object} { affected, count }
+ */
+async function handleBatch(mysql, sqls) {
+  if (!Array.isArray(sqls) || sqls.length === 0) {
+    return { error: { code: 'MGR_BATCH_EMPTY', message: 'SQL 列表不能为空' } };
+  }
+  var affected = 0;
+  for (var i = 0; i < sqls.length; i++) {
+    var r = await mysql.exec(sqls[i], []);
+    if (mysql.error) {
+      return _errorResult('MGR_BATCH_ERROR', mysql.error.message + ' [第' + (i + 1) + '条SQL]');
+    }
+    affected += r || 0;
+  }
+  return { affected: affected, count: sqls.length };
+}
+
+/**
+ * 执行多语句 SQL 脚本（支持分号分隔的建表/插入语句）
+ * @param {object} mysql 数据库实例
+ * @param {string} sql SQL 脚本内容
+ * @returns {object} { success, statements, affected_rows }
+ */
+async function handleRunSql(mysql, sql) {
+  if (!sql) {
+    return _errorResult('MGR_SQL_EMPTY', 'SQL 语句不能为空');
+  }
+  var result = await mysql.runSql(sql);
+  if (mysql.error) {
+    return _errorResult('MGR_RUNSQL_ERROR', mysql.error.message);
+  }
+  return {
+    success: result.success,
+    statements: result.statements,
+    affected_rows: result.affected_rows
+  };
+}
+
+/**
+ * 构建错误结果对象
+ */
+function _errorResult(code, message) {
+  return { error: { code: code, message: message } };
+}
+
+/**
+ * 构建 upsert SQL (INSERT ... ON DUPLICATE KEY UPDATE)
+ * @param {string} table 表名
+ * @param {object} body 数据对象 { field: value }
+ * @param {array} unique 唯一约束字段列表（可选）
+ * @returns {object} { sql, params }
+ */
+function _buildUpsert(table, body, unique) {
+  var fields = Object.keys(body);
+  var values = [];
+  var placeholders = [];
+  for (var i = 0; i < fields.length; i++) {
+    values.push(body[fields[i]]);
+    placeholders.push('?');
+  }
+
+  var updates = [];
+  var update_fields =
+    unique.length > 0
+      ? fields.filter(function (f) {
+          return unique.indexOf(f) === -1;
+        })
+      : fields;
+  for (var j = 0; j < update_fields.length; j++) {
+    var f = update_fields[j];
+    updates.push('`' + f + '` = VALUES(`' + f + '`)');
+  }
+
+  var sql_str =
+    'INSERT INTO `' +
+    table +
+    '` (`' +
+    fields.join('`, `') +
+    '`) VALUES (' +
+    placeholders.join(', ') +
+    ')';
+  if (updates.length > 0) {
+    sql_str += ' ON DUPLICATE KEY UPDATE ' + updates.join(', ');
+  }
+
+  return { sql: sql_str, params: values };
+}
+
+module.exports = { main };

package/lib/tools/mysql_rw/index.js

@@ -0,0 +1,228 @@
+/**
+ * MySQL 读写分离管理器
+ * 基于 mm_mysql 的 mysqlAdmin 管理连接池，实现读写分离路由
+ * SQL 方法: query(SELECT→读库) / insert/update/delete(→写库)
+ * ORM 方法: add/set/del(→写库) / getObj/list/count(→读库)
+ * 读库从 replicas 随机选择一台，未配置从库时读写都走主库
+ */
+/**
+ * 判断 SQL 是否为读操作
+ * @param {string} sql SQL 语句
+ * @returns {boolean} 是否为读操作
+ */
+function _isReadOp(sql) {
+  var trimmed = sql.trim().toUpperCase();
+  return (
+    trimmed.startsWith('SELECT') ||
+    trimmed.startsWith('SHOW') ||
+    trimmed.startsWith('DESCRIBE') ||
+    trimmed.startsWith('EXPLAIN')
+  );
+}
+
+/**
+ * 选择读库(随机)
+ * @param {Array} replicas 读库配置列表
+ * @returns {object} 读库配置
+ */
+function _pickReplica(replicas) {
+  if (!replicas || replicas.length === 0) {
+    return null;
+  }
+  var idx = Math.floor(Math.random() * replicas.length);
+  return replicas[idx];
+}
+
+/**
+ * 判断操作路由: 写→master, 读→replica
+ * @param {string} action 操作类型
+ * @param {string} sql SQL 语句
+ * @returns {boolean} 是否为读操作
+ */
+function _isReadAction(action, sql) {
+  var orm_write = ['add', 'set', 'del', 'insert', 'update', 'delete'];
+  var orm_read = ['getObj', 'list', 'count'];
+  if (action === 'runSql') return false;
+  if (orm_write.indexOf(action) !== -1) return false;
+  if (orm_read.indexOf(action) !== -1) return true;
+  if (action === 'query') return true;
+  if (action === 'execute' || action === 'exec') return false;
+  if (sql) return _isReadOp(sql);
+  return false;
+}
+
+/**
+ * 从模块 options 定义中递归提取默认配置
+ * 支持扁平键(default)与嵌套对象(properties)，如 master.properties.host.default
+ * @param {object} options 模块 options 定义
+ * @returns {object} 提取的默认配置
+ */
+function _extractDefaults(options) {
+  var out = {};
+  for (var k in options) {
+    var o = options[k];
+    if (o && typeof o === 'object' && o.default !== undefined) {
+      out[k] = o.default;
+    } else if (o && typeof o === 'object' && o.properties) {
+      out[k] = _extractDefaults(o.properties);
+    }
+  }
+  return out;
+}
+
+/**
+ * 主函数
+ * @param {object} ctx 上下文
+ * @param {object} params 参数
+ * @returns {object} 执行结果
+ */
+async function main(params, ctx, options) {
+  const { mysqlAdmin } = require('mm_mysql');
+  // 从模块 options 读取主从配置，无 master 键时以扁平 options 作为主库
+  var rw_opts = _extractDefaults((this.config && this.config.options) || {});
+  var master_cfg;
+  var replicas = [];
+  if (rw_opts.master) {
+    master_cfg = rw_opts.master;
+    replicas = rw_opts.replicas || [];
+  } else {
+    master_cfg = rw_opts;
+    replicas = [];
+  }
+
+  var action = params.action || '';
+  var sql = params.sql || '';
+  var values = params.values || [];
+  var table = params.table || '';
+  var query = params.query || {};
+  var body = params.body || {};
+
+  // 读写分离路由
+  var is_read = _isReadAction(action, sql);
+  var target_cfg = master_cfg;
+  var route = 'master';
+
+  if (is_read && replicas.length > 0) {
+    var replica = _pickReplica(replicas);
+    if (replica) {
+      target_cfg = replica;
+      route = 'replica';
+    }
+  }
+
+  // SQL 方法必须提供 sql 语句
+  var SQL_ACTIONS = ['query', 'run', 'insert', 'update', 'delete', 'execute', 'exec', 'runSql'];
+  if (SQL_ACTIONS.indexOf(action) !== -1 && !sql) {
+    ctx.output = { error: { code: 'SQL_EMPTY', message: 'SQL 语句不能为空' } };
+    return ctx.output;
+  }
+
+  try {
+    // 使用 mm_mysql 的 mysqlAdmin 管理连接池（按 scope 缓存实例）
+    var scope = route === 'replica' ? 'rw_replica' : 'rw_master';
+    var mysql = mysqlAdmin(scope, target_cfg);
+    await mysql.open();
+
+    // ORM 方法: add/set/del/getObj/list/count
+    var ORM_METHODS = ['add', 'del', 'set', 'list', 'getObj', 'count'];
+    if (ORM_METHODS.indexOf(action) !== -1) {
+      if (!table) {
+        ctx.output = { error: { code: 'SQL_TABLE_EMPTY', message: 'ORM 操作缺少 table 参数', route: route } };
+        return ctx.output;
+      }
+      var db = mysql.db();
+      db.table = table;
+      var result;
+      switch (action) {
+        case 'add':
+          result = await db.add(body);
+          break;
+        case 'del':
+          result = await db.del(query);
+          break;
+        case 'set':
+          result = await db.set(query, body);
+          break;
+        case 'list':
+          result = await db.list(query);
+          break;
+        case 'getObj':
+          result = await db.getObj(query);
+          break;
+        case 'count':
+          result = await db.count(query);
+          break;
+      }
+      if (db.error) {
+        ctx.output = { error: { code: 'ORM_ERROR', message: db.error.message, route: route } };
+        return ctx.output;
+      }
+      ctx.output = { result: result, route: route };
+      return ctx.output;
+    }
+
+    // SQL 方法: query / insert / update / delete / execute
+    switch (action) {
+      case 'runSql': {
+        var rs = await mysql.runSql(sql);
+        if (mysql.error) {
+          ctx.output = { error: { code: 'SQL_ERROR', message: mysql.error.message, route: route } };
+          return ctx.output;
+        }
+        ctx.output = {
+          success: rs.success,
+          statements: rs.statements,
+          affected_rows: rs.affected_rows,
+          route: route
+        };
+        break;
+      }
+      case 'query':
+      case 'run': {
+        var rows = await mysql.run(sql, values);
+        if (mysql.error) {
+          ctx.output = { error: { code: 'SQL_ERROR', message: mysql.error.message, route: route } };
+          return ctx.output;
+        }
+        ctx.output = {
+          list: Array.isArray(rows) ? rows : [],
+          count: Array.isArray(rows) ? rows.length : 0,
+          route: route
+        };
+        break;
+      }
+      case 'insert':
+      case 'update':
+      case 'delete':
+      case 'execute':
+      case 'exec': {
+        var affected = await mysql.exec(sql, values);
+        if (mysql.error) {
+          ctx.output = { error: { code: 'SQL_ERROR', message: mysql.error.message, route: route } };
+          return ctx.output;
+        }
+        ctx.output = {
+          affected: affected || 0,
+          route: route
+        };
+        break;
+      }
+      default:
+        ctx.output = {
+          error: {
+            code: 'SQL_UNKNOWN_ACTION',
+            message: '不支持的操作: ' + action + '，支持: query/insert/update/delete/execute/runSql + ORM(add/set/del/getObj/list/count)',
+            route: route
+          }
+        };
+    }
+  } catch (err) {
+    ctx.output = {
+      error: { code: 'SQL_ERROR', message: err.message, route: route }
+    };
+  }
+
+  return ctx.output;
+}
+
+module.exports = { main };

package/lib/tools/sql_dump/index.js

@@ -0,0 +1,181 @@
+/**
+ * SQL导出管理器
+ * 将数据库表导出为 SQL 文件（表结构 + 数据），基于 mm_mysql
+ * 导出内容: SHOW CREATE TABLE 建表语句 + INSERT 数据语句
+ */
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * 主函数
+ * @param {object} ctx 上下文对象
+ * @param {object} params 参数 { table, output_file }
+ * @returns {object} 导出结果 { file_path, table, statements, rows }
+ */
+async function main(params, ctx, options) {
+  const { mysqlAdmin } = require('mm_mysql');
+  var table = params.table || '';
+  var output_file = params.output_file || '';
+  // 未提供的可选参数在模板中会保留为占位符，此时使用默认输出路径
+  if (output_file.indexOf('{{') !== -1) {
+    output_file = '';
+  }
+
+  if (!table) {
+    ctx.output = _errorResult('MGR_TABLE_EMPTY', '表名不能为空');
+    return ctx.output;
+  }
+
+  var opts = this.getOptions();
+
+  try {
+    var mysql = mysqlAdmin('os', opts);
+    await mysql.open();
+
+    var create_sql = await _getCreateSql(mysql, table);
+    if (mysql.error) {
+      ctx.output = _errorResult('MGR_DUMP_ERROR', '查询表结构失败: ' + mysql.error.message);
+      return ctx.output;
+    }
+
+    var rows = await _getRows(mysql, table);
+    if (mysql.error) {
+      ctx.output = _errorResult('MGR_DUMP_ERROR', '查询表数据失败: ' + mysql.error.message);
+      return ctx.output;
+    }
+
+    var insert_sqls = _buildInserts(table, rows);
+    var sql_text = _buildSqlText(table, create_sql, insert_sqls);
+    var file_path = _writeFile(table, sql_text, output_file);
+
+    ctx.output = {
+      file_path: file_path,
+      table: table,
+      statements: 1 + insert_sqls.length,
+      rows: rows.length
+    };
+    return ctx.output;
+  } catch (err) {
+    ctx.output = _errorResult('MGR_DUMP_ERROR', err.message);
+    return ctx.output;
+  }
+}
+
+/**
+ * 查询表结构
+ * @param {object} mysql 数据库实例
+ * @param {string} table 表名
+ * @returns {string} 建表语句
+ */
+async function _getCreateSql(mysql, table) {
+  var list = await mysql.run('SHOW CREATE TABLE `' + table + '`', []);
+  if (!Array.isArray(list) || list.length === 0) {
+    return '';
+  }
+  var first = list[0];
+  var create_sql = first['Create Table'] || Object.values(first).pop() || '';
+  create_sql = String(create_sql).trim();
+  if (create_sql && !create_sql.endsWith(';')) {
+    create_sql += ';';
+  }
+  return create_sql;
+}
+
+/**
+ * 查询表数据
+ * @param {object} mysql 数据库实例
+ * @param {string} table 表名
+ * @returns {Array} 数据行数组
+ */
+async function _getRows(mysql, table) {
+  var list = await mysql.run('SELECT * FROM `' + table + '`', []);
+  return Array.isArray(list) ? list : [];
+}
+
+/**
+ * 生成 INSERT 语句数组
+ * @param {string} table 表名
+ * @param {Array} rows 数据行
+ * @returns {Array} INSERT 语句数组
+ */
+function _buildInserts(table, rows) {
+  var sqls = [];
+  for (var i = 0; i < rows.length; i++) {
+    var row = rows[i];
+    var cols = Object.keys(row);
+    var vals = [];
+    for (var j = 0; j < cols.length; j++) {
+      vals.push(_sqlValue(row[cols[j]]));
+    }
+    sqls.push(
+      'INSERT INTO `' + table + '` (`' + cols.join('`, `') + '`) VALUES (' + vals.join(', ') + ');'
+    );
+  }
+  return sqls;
+}
+
+/**
+ * 转换值为 SQL 字面量
+ * @param {*} value 字段值
+ * @returns {string} SQL 字面量
+ */
+function _sqlValue(value) {
+  if (value === null || value === undefined) return 'NULL';
+  if (typeof value === 'number') return String(value);
+  if (typeof value === 'boolean') return value ? '1' : '0';
+  if (value instanceof Date) {
+    var dt = value.toISOString().slice(0, 19).replace('T', ' ');
+    return "'" + dt + "'";
+  }
+  return "'" + String(value).replace(/'/g, "''") + "'";
+}
+
+/**
+ * 拼接完整导出 SQL 文本
+ * @param {string} table 表名
+ * @param {string} create_sql 建表语句
+ * @param {Array} insert_sqls INSERT 语句数组
+ * @returns {string} 完整 SQL 文本
+ */
+function _buildSqlText(table, create_sql, insert_sqls) {
+  var lines = [];
+  lines.push('-- 表结构导出: `' + table + '`');
+  lines.push(create_sql);
+  if (insert_sqls.length > 0) {
+    lines.push('');
+    lines.push('-- 表数据导出: `' + table + '` (' + insert_sqls.length + ' 行)');
+    for (var i = 0; i < insert_sqls.length; i++) {
+      lines.push(insert_sqls[i]);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * 写入导出文件
+ * @param {string} table 表名
+ * @param {string} sql_text SQL 内容
+ * @param {string} output_file 输出路径（可选）
+ * @returns {string} 文件绝对路径
+ */
+function _writeFile(table, sql_text, output_file) {
+  var base = process.cwd();
+  var file_path = output_file
+    ? path.resolve(base, output_file)
+    : path.resolve(base, 'backup', table + '.sql');
+  fs.mkdirSync(path.dirname(file_path), { recursive: true });
+  fs.writeFileSync(file_path, sql_text, 'utf8');
+  return file_path;
+}
+
+/**
+ * 构建错误结果对象
+ * @param {string} code 错误码
+ * @param {string} message 错误信息
+ * @returns {object} 错误对象
+ */
+function _errorResult(code, message) {
+  return { error: { code: code, message: message } };
+}
+
+module.exports = { main };

package/package.json

@@ -1,50 +1,51 @@
-{
-	"name": "mm_mysql",
-	"version": "2.5.7",
-	"description": "这是超级美眉mysql帮助函数模块，用于便捷操作mysql，使用await方式，可以避免嵌套函数",
-	"main": "index.js",
-	"dependencies": {
-		"mm_corejs": "^1.1.4",
-		"mm_mod": "^1.0.1",
-		"mm_helper": "^1.0.0",
-		"mysql2": "^3.24.2",
-		"sqlstring": "^2.3.3"
-	},
-	"scripts": {
-		"start": "node index.js",
-		"test": "node test.js",
-		"lint": "eslint . --config eslint.config.js",
-		"lint:fix": "eslint . --config eslint.config.js --fix"
-	},
-	"repository": {
-		"type": "git",
-		"url": "https://gitee.com/qiuwenwu91/mm_mysql.git"
-	},
-	"keywords": [
-		"mm_mod",
-		"mm_adapter",
-		"mm_persist",
-		"mysql",
-		"async",
-		"await",
-		"promise",
-		"mysql2",
-		"database",
-		"query",
-		"transaction",
-		"sql",
-		"db"
-	],
-	"layer": "adapter",
-	"group": "persist",
-	"author": "qww",
-	"license": "ISC",
-	"engines": {
-		"node": ">=12.0.0"
-	},
-	"devDependencies": {
-		"eslint": "^10.9.1",
-		"eslint-plugin-jsdoc": "^64.2.1",
-		"mm_eslint": "^1.7.7"
-	}
-}
+{
+  "name": "mm_mysql",
+  "version": "2.6.0",
+  "description": "这是超级美眉mysql帮助函数模块，用于便捷操作mysql，使用await方式，可以避免嵌套函数",
+  "main": "index.js",
+  "dependencies": {
+    "mm_admin": "^1.1.0",
+    "mm_eslint": "^1.0.0",
+    "mm_helper": "^1.0.0",
+    "mm_mod": "^1.0.1",
+    "mysql2": "^3.24.2",
+    "sqlstring": "^2.3.3"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "node test.js",
+    "lint": "eslint . --config eslint.config.js",
+    "lint:fix": "eslint . --config eslint.config.js --fix"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitee.com/qiuwenwu91/mm_mysql.git"
+  },
+  "keywords": [
+    "mm_mod",
+    "mm_adapter",
+    "mm_persist",
+    "mysql",
+    "async",
+    "await",
+    "promise",
+    "mysql2",
+    "database",
+    "query",
+    "transaction",
+    "sql",
+    "db"
+  ],
+  "layer": "infrastructure",
+  "group": "persistence",
+  "author": "qww",
+  "license": "ISC",
+  "engines": {
+    "node": ">=12.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^10.9.1",
+    "eslint-plugin-jsdoc": "^64.2.1",
+    "mm_eslint": "^1.7.7"
+  }
+}

package/tool/mysql/index.js

@@ -0,0 +1,7 @@
+'use strict';
+/**
+ * mysql —— 工具契约适配层
+ * 业务实现归位于模块 lib/tools/mysql/，本文件只把模块能力暴露给加载器。
+ * 其它模块可直接 require('mm_mysql').tools.mysql 复用。
+ */
+module.exports = require('../../lib/tools/mysql');

package/tool/mysql/tool.json

@@ -0,0 +1,118 @@
+{
+  "name": "mysql",
+  "handler": "manager",
+  "title": "MySQL管理器",
+  "description": "操作 MySQL 数据库，支持 SQL 与 ORM 两种方式。适用场景：需要持久化数据、增删改查、统计计数时。工作流提示：action 必填（query/execute/runSql 配 sql，add/del/set/list/getObj/count/upsert 配 table/query/body），读结果在 list/count、写结果在 affected/id。",
+  "type": "data",
+  "params": {
+    "type": "object",
+    "properties": {
+      "action": {
+        "type": "string",
+        "description": "操作类型: SQL方法(query/execute/runSql) + ORM方法(add/del/set/list/getObj/count) + upsert + batch",
+        "enum": [
+          "query",
+          "execute",
+          "runSql",
+          "add",
+          "del",
+          "set",
+          "list",
+          "getObj",
+          "count",
+          "upsert",
+          "batch"
+        ]
+      },
+      "sql": {
+        "type": "string",
+        "description": "SQL语句（SQL方法需要）"
+      },
+      "params": {
+        "type": "array",
+        "description": "SQL参数（可选）"
+      },
+      "table": {
+        "type": "string",
+        "description": "表名（ORM方法需要）"
+      },
+      "query": {
+        "type": "object",
+        "description": "查询条件（ORM方法需要）"
+      },
+      "body": {
+        "type": "object",
+        "description": "数据对象（add/set/upsert 操作需要）"
+      },
+      "unique": {
+        "type": "array",
+        "description": "唯一约束字段列表（upsert 操作，不更新的字段）"
+      }
+    },
+    "required": [
+      "action"
+    ]
+  },
+  "returns": {
+    "description": "管理操作结果，读操作返回 list+count，写操作返回 affected，异常时返回 error",
+    "type": "object",
+    "properties": {
+      "list": {
+        "type": "array",
+        "description": "查询结果列表（query/run 操作）"
+      },
+      "count": {
+        "type": "number",
+        "description": "列表条目数/统计数"
+      },
+      "affected": {
+        "type": "number",
+        "description": "受影响的行数（写操作）"
+      },
+      "id": {
+        "type": "number",
+        "description": "插入的自增ID（upsert 操作）"
+      }
+    }
+  },
+  "options": {
+    "host": {
+      "type": "string",
+      "description": "数据库主机地址",
+      "default": "localhost"
+    },
+    "port": {
+      "type": "number",
+      "description": "数据库端口",
+      "default": 3306
+    },
+    "user": {
+      "type": "string",
+      "description": "数据库用户名",
+      "default": "root"
+    },
+    "password": {
+      "type": "string",
+      "description": "数据库密码",
+      "default": "Asd159357"
+    },
+    "database": {
+      "type": "string",
+      "description": "数据库名",
+      "default": "mm"
+    },
+    "charset": {
+      "type": "string",
+      "description": "字符集",
+      "default": "utf8mb4"
+    },
+    "pool_size": {
+      "type": "number",
+      "description": "连接池大小",
+      "default": 10,
+      "min": 1,
+      "max": 100
+    }
+  },
+  "group": "storage"
+}

package/tool/mysql_rw/index.js

@@ -0,0 +1,7 @@
+'use strict';
+/**
+ * mysql_rw —— 工具契约适配层
+ * 业务实现归位于模块 lib/tools/mysql_rw/，本文件只把模块能力暴露给加载器。
+ * 其它模块可直接 require('mm_mysql').tools.mysql_rw 复用。
+ */
+module.exports = require('../../lib/tools/mysql_rw');

package/tool/mysql_rw/tool.json

@@ -0,0 +1,105 @@
+{
+  "name": "mysql_rw",
+  "handler": "manager",
+  "title": "MySQL读写分离",
+  "description": "MySQL 读写分离，SELECT 走读库、写操作走主库，多读库负载均衡。适用场景：高并发读、读写分离部署时。工作流提示：action 必填（SQL 配 sql/values，ORM 配 table/query/body），读在 list/count、写后 affected、路由在 route。",
+  "type": "data",
+  "params": {
+    "type": "object",
+    "properties": {
+      "action": {
+        "type": "string",
+        "description": "操作类型: SQL(query/insert/update/delete/execute/runSql) + ORM(add/del/set/getObj/list/count)，写操作走主库，读操作走读库",
+        "enum": [
+          "query",
+          "insert",
+          "update",
+          "delete",
+          "execute",
+          "runSql",
+          "add",
+          "del",
+          "set",
+          "getObj",
+          "list",
+          "count"
+        ]
+      },
+      "sql": {
+        "type": "string",
+        "description": "SQL 语句（runSql 可传多条以分号分隔的建表/插入语句，强制走主库）"
+      },
+      "values": {
+        "type": "array",
+        "description": "SQL 参数值(使用参数化查询防注入)"
+      },
+      "table": {
+        "type": "string",
+        "description": "表名(ORM 方法需要)"
+      },
+      "query": {
+        "type": "object",
+        "description": "查询条件(ORM 方法需要)，如 {username: 'demo'} 或 {id: 1}"
+      },
+      "body": {
+        "type": "object",
+        "description": "数据对象(add/set 操作需要)"
+      }
+    },
+    "required": [
+      "action"
+    ]
+  },
+  "returns": {
+    "description": "操作结果，返回 route 字段标识实际路由到的库",
+    "type": "object",
+    "properties": {
+      "list": {
+        "type": "array",
+        "description": "查询结果列表(query操作)"
+      },
+      "count": {
+        "type": "number",
+        "description": "查询结果数量(query操作)"
+      },
+      "affected": {
+        "type": "number",
+        "description": "影响行数或插入ID(insert/update/delete操作)"
+      },
+      "route": {
+        "type": "string",
+        "description": "实际路由: master/replica"
+      }
+    }
+  },
+  "options": {
+    "master": {
+      "type": "object",
+      "description": "写库(主库)配置",
+      "properties": {
+        "host": { "type": "string", "description": "主机", "default": "localhost" },
+        "port": { "type": "number", "description": "端口", "default": 3306 },
+        "user": { "type": "string", "description": "用户名", "default": "root" },
+        "password": { "type": "string", "description": "密码", "default": "Asd159357" },
+        "database": { "type": "string", "description": "数据库名", "default": "mm" },
+        "connectionLimit": { "type": "number", "description": "连接池大小", "default": 10 }
+      }
+    },
+    "replicas": {
+      "type": "array",
+      "description": "读库(从库)配置列表，多台随机负载均衡",
+      "items": {
+        "type": "object",
+        "properties": {
+          "host": { "type": "string", "description": "主机" },
+          "port": { "type": "number", "description": "端口", "default": 3306 },
+          "user": { "type": "string", "description": "用户名" },
+          "password": { "type": "string", "description": "密码" },
+          "database": { "type": "string", "description": "数据库名" },
+          "connectionLimit": { "type": "number", "description": "连接池大小", "default": 10 }
+        }
+      }
+    }
+  },
+  "group": "system"
+}

package/tool/sql_dump/index.js

@@ -0,0 +1,7 @@
+'use strict';
+/**
+ * sql_dump —— 工具契约适配层
+ * 业务实现归位于模块 lib/tools/sql_dump/，本文件只把模块能力暴露给加载器。
+ * 其它模块可直接 require('mm_mysql').tools.sql_dump 复用。
+ */
+module.exports = require('../../lib/tools/sql_dump');

package/tool/sql_dump/tool.json

@@ -0,0 +1,83 @@
+{
+  "name": "sql_dump",
+  "handler": "manager",
+  "title": "SQL导出管理器",
+  "description": "将 MySQL 表导出为 SQL 文件（建表语句+数据）。适用场景：备份表结构数据、迁移或重建环境时。工作流提示：table 必填导出表名，output_file 指定路径（默认 ./backup/{table}.sql），路径在 file_path、条数与行数在 statements/rows。",
+  "type": "data",
+  "params": {
+    "type": "object",
+    "properties": {
+      "table": {
+        "type": "string",
+        "description": "要导出的表名"
+      },
+      "output_file": {
+        "type": "string",
+        "description": "输出文件路径（可选，默认 ./backup/{table}.sql）"
+      }
+    },
+    "required": ["table"]
+  },
+  "returns": {
+    "description": "导出结果",
+    "type": "object",
+    "properties": {
+      "file_path": {
+        "type": "string",
+        "description": "导出文件绝对路径"
+      },
+      "table": {
+        "type": "string",
+        "description": "导出的表名"
+      },
+      "statements": {
+        "type": "number",
+        "description": "生成的 SQL 语句条数"
+      },
+      "rows": {
+        "type": "number",
+        "description": "导出的数据行数"
+      }
+    }
+  },
+  "options": {
+    "host": {
+      "type": "string",
+      "description": "数据库主机地址",
+      "default": "localhost"
+    },
+    "port": {
+      "type": "number",
+      "description": "数据库端口",
+      "default": 3306
+    },
+    "user": {
+      "type": "string",
+      "description": "数据库用户名",
+      "default": "root"
+    },
+    "password": {
+      "type": "string",
+      "description": "数据库密码",
+      "default": "Asd159357"
+    },
+    "database": {
+      "type": "string",
+      "description": "数据库名",
+      "default": "mm"
+    },
+    "charset": {
+      "type": "string",
+      "description": "字符集",
+      "default": "utf8mb4"
+    },
+    "pool_size": {
+      "type": "number",
+      "description": "连接池大小",
+      "default": 10,
+      "min": 1,
+      "max": 100
+    }
+  },
+  "group": "storage"
+}