mm_sql 1.3.8 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # mm_sql
 
-一个通用的SQL帮助类，支持通过切换db_type实现对不同数据库的操作，包括MySQL和SQLite等。
+一个通用的SQL帮助类，支持通过切换db_type实现对不同数据库的操作，包括MySQL和SQLite等，提供统一的API接口，支持异步操作和基础SQL执行。
 
 ## 安装
 
@@ -10,8 +10,8 @@ npm install mm_sql
 
 ## 依赖
 
-- mm_mysql: ^2.0.3
-- mm_sqlite: ^1.0.0
+- mm_mysql: ^2.1.1
+- mm_sqlite: ^1.1.3
 
 ## 使用方法
 
@@ -19,132 +19,126 @@ npm install mm_sql
 
 ```javascript
 // 引入模块
-const Sql = require('mm_sql');
+const { Sql } = require('mm_sql');
 
 // 创建实例（默认使用MySQL）
 const sql = new Sql({
+  db_type: 'mysql',
   host: 'localhost',
   port: 3306,
   user: 'root',
   password: 'password',
-  database: 'test_db',
-  table: 'users'
+  database: 'test_db'
 });
 
-// 初始化连接
-await sql.init();
+// 执行查询SQL
+const users = await sql.run('SELECT * FROM users WHERE status = 1');
 
-// 查询数据
-const users = await sql.get({ status: 1 }, 'created_at DESC');
+// 执行更新SQL
+const result = await sql.exec('UPDATE users SET status = 0 WHERE id = 1');
 
-// 销毁连接
-await sql.destroy();
+// 关闭连接
+await sql.close();
 ```
 
 ### 2. 切换数据库类型
 
 ```javascript
 // 创建MySQL实例
-const mysqlSql = new Sql({
+const sql = new Sql({
   db_type: 'mysql',
   host: 'localhost',
   user: 'root',
   password: 'password',
-  database: 'mysql_db',
-  table: 'users'
+  database: 'mysql_db'
 });
 
 // 切换到SQLite
-const sqliteSql = mysqlSql.use('sqlite', {
-  database: 'sqlite.db',
-  table: 'users'
+sql.setConfig({
+  db_type: 'sqlite',
+  dir: '/db/',
+  database: 'sqlite.db'
 });
 
 // 使用SQLite进行操作
-await sqliteSql.init();
-const data = await sqliteSql.get({});
+const data = await sql.run('SELECT * FROM users');
 ```
 
 ### 3. 主要方法
 
-#### 查询方法
+#### SQL执行方法
 
 ```javascript
-// 查询多条数据
-const list = await sql.get({ status: 1 }, 'id DESC');
-
-// 查询单条数据
-const user = await sql.getObj({ id: 1 });
-
-// 分页查询
-const result = await sql.getCount(
-  { status: 1 },
-  'created_at DESC',
-  'id, name, email'
-);
-// result结构: { list: [...], total: 100, page: 1, size: 20, pages: 5 }
-
-// 统计
-const count = await sql.count({ status: 1 });
-```
+// 执行查询操作（返回结果集）
+const users = await sql.run('SELECT * FROM users WHERE status = 1');
 
-#### 增删改方法
+// 执行带参数的查询
+const user = await sql.run('SELECT * FROM users WHERE id = ?', [1]);
 
-```javascript
-// 添加数据
-const addResult = await sql.add({
-  name: '张三',
-  age: 25,
-  status: 1
-});
+// 执行带超时的查询
+const timeoutResult = await sql.run('SELECT * FROM users WHERE status = 1', [], 5000);
 
-// 修改数据
-const updateResult = await sql.set(
-  { id: 1 }, // 查询条件
-  { name: '李四', age: 26 } // 更新字段
-);
+// 执行修改操作（返回影响行数）
+const updateResult = await sql.exec('UPDATE users SET status = 0 WHERE id = 1');
+
+// 执行带参数的修改
+const updateWithParams = await sql.exec('UPDATE users SET name = ? WHERE id = ?', ['张三', 1]);
 
-// 删除数据
-const deleteResult = await sql.del({ id: 1 });
+// 执行带超时的修改
+const timeoutExec = await sql.exec('DELETE FROM users WHERE status = 0', [], 3000);
 
-// 添加或修改（如果存在则修改，不存在则添加）
-const addOrSetResult = await sql.addOrSet(
-  { id: 1 }, // 查询条件
-  { name: '王五', age: 27 } // 要设置的字段
-);
+// 使用对象参数方式调用
+const result = await sql.run({
+  sql: 'SELECT * FROM users WHERE name LIKE ?',
+  params: ['张%'],
+  timeout: 5000
+});
 ```
 
-#### 批量操作
+#### 连接管理方法
 
 ```javascript
-// 批量添加
-const addListResult = await sql.addList([
-  { name: '用户1', status: 1 },
-  { name: '用户2', status: 1 }
-]);
-
-// 批量修改
-const setListResult = await sql.setList([
-  { query: { id: 1 }, item: { status: 0 } },
-  { query: { id: 2 }, item: { status: 0 } }
-]);
-
-// 批量删除
-const delListResult = await sql.delList([
-  { query: { id: 1 } },
-  { query: { id: 2 } }
-]);
+// 手动打开数据库连接
+await sql.open();
+
+// 手动关闭数据库连接
+await sql.close();
+
+// 动态修改配置
+sql.setConfig({
+  host: 'new_host',
+  database: 'new_database'
+});
 ```
 
-#### 模型操作
+#### 模板方法
 
 ```javascript
-// 获取模型对象
-const model = await sql.getObj({ id: 1 });
+// SQL模板查询生成
+const query = sql.tplQuery({ name: '张', age: 20 }, {
+  name: '`name` LIKE "{0}%"',
+  age: '`age` > {0}'
+});
+// 生成: "`name` LIKE \"张%\" AND `age` > 20"
+
+// SQL模板数据生成
+const body = sql.tplBody({ name: '李四', age: 25 }, {
+  name: '`name` = {0}',
+  age: '`age` = {0}'
+});
+// 生成: "`name` = '李四', `age` = 25"
+
+// 参数过滤
+const filteredParams = sql.filter({ id: 1, name: '张三', password: '123' }, ['password']);
+// 结果: { id: 1, name: '张三' }
+```
+
+#### 数据库适配器方法
 
-// 直接修改模型属性会自动更新到数据库
-model.name = '新名称'; // 自动执行UPDATE操作
-model.age += 1; // 自动执行UPDATE操作，增加年龄
+```javascript
+// 获取底层数据库适配器
+const dbAdapter = sql.db();
+// 可用于直接操作底层数据库接口
 ```
 
 ### 4. 配置选项
@@ -154,14 +148,8 @@ const sql = new Sql({
   // 数据库类型
   db_type: 'mysql', // 可选值: 'mysql', 'sqlite'
   
-  // 表相关配置
-  table: 'users', // 表名
-  key: 'id', // 主键
-  
-  // 分页配置
-  page: 1, // 默认页码
-  size: 20, // 默认每页数量
-  limit: 1000, // 最大查询数量
+  // 作用域配置
+  scope: 'sys', // 默认作用域
   
   // MySQL配置
   host: 'localhost',
@@ -169,38 +157,13 @@ const sql = new Sql({
   user: 'root',
   password: '',
   database: '',
-  charset: 'utf8mb4',
   
   // SQLite配置
-  database: 'db.sqlite', // SQLite数据库文件路径
-  
-  // 其他配置
-  filter: {}, // 过滤参数
-  separator: '|' // 分隔符，用于多条件查询
+  dir: '/db/', // SQLite数据库文件存储目录
+  database: 'db.sqlite' // SQLite数据库文件名
 });
 ```
 
-## 事务操作
-
-```javascript
-// MySQL事务示例
-const mysqlTransactionResult = await sql.exec(`
-  START TRANSACTION;
-  INSERT INTO users (name, age) VALUES ('测试用户', 30);
-  UPDATE users SET status = 1 WHERE id = LAST_INSERT_ID();
-  COMMIT;
-`);
-
-// SQLite事务示例
-const sqliteTransactionResult = await sql.exec(`
-  BEGIN TRANSACTION;
-  INSERT INTO users (name, age) VALUES ('测试用户', 30);
-  UPDATE users SET status = 1 WHERE id = last_insert_rowid();
-  COMMIT;
-`);
-
-// 注意：不同数据库的事务语法和函数可能有所不同，请根据实际使用的数据库类型调整SQL语句
-
 ## 高级用法
 
 ### 1. SQL模板
@@ -213,8 +176,31 @@ const sqlTemplate = {
 };
 
 // 使用模板构建查询条件
-const query = sql.tpl_query({ name: '张', age: 20 }, sqlTemplate);
-// 生成的查询条件: "`name` LIKE \"张%\" && `age` > 20"
+const query = sql.tplQuery({ name: '张', age: 20 }, sqlTemplate);
+// 生成的查询条件: "`name` LIKE \"张%\" AND `age` > 20"
+
+// 使用模板构建更新语句
+const body = sql.tplBody({ name: '李四', age: 25 }, {
+  name: '`name` = {0}',
+  age: '`age` = {0}'
+});
+// 生成的更新语句: "`name` = '李四', `age` = 25"
+
+// 使用配置文件定义SQL模板
+const config = {
+  "query": {
+    "name": "`name` like '%{0}%'"
+  },
+  "where": {
+    "uid": "`uid` = {0}"
+  },
+  "update": {
+    "name": "`name` = {0}"
+  }
+};
+
+// 使用配置文件中的模板
+const queryFromConfig = sql.tplQuery({ name: '张' }, config.query);
 ```
 
 ### 2. 自定义SQL执行
@@ -225,20 +211,103 @@ const result = await sql.run('SELECT * FROM users WHERE status = 1');
 
 // 执行自定义更新SQL
 const updateResult = await sql.exec('UPDATE users SET status = 0 WHERE id = 1');
+
+// 执行带参数的SQL
+const user = await sql.run('SELECT * FROM users WHERE id = ?', [1]);
+
+// 执行带超时的SQL
+const timeoutResult = await sql.run('SELECT * FROM users WHERE status = 1', [], 5000);
+
+// 执行事务操作（MySQL）
+const mysqlTransactionResult = await sql.exec(`
+  START TRANSACTION;
+  INSERT INTO users (name, age) VALUES ('测试用户', 30);
+  UPDATE users SET status = 1 WHERE id = LAST_INSERT_ID();
+  COMMIT;
+`);
+
+// 执行事务操作（SQLite）
+const sqliteTransactionResult = await sql.exec(`
+  BEGIN TRANSACTION;
+  INSERT INTO users (name, age) VALUES ('测试用户', 30);
+  UPDATE users SET status = 1 WHERE id = last_insert_rowid();
+  COMMIT;
+`);
 ```
 
 ## 注意事项
 
-1. 使用前必须先调用`init()`方法初始化连接
-2. 使用完成后应调用`destroy()`方法销毁连接，避免资源泄漏
+1. 系统会自动初始化连接，无需手动调用初始化方法
+2. 使用完成后建议调用`close()`方法关闭连接，避免资源泄漏
 3. 切换数据库类型时会重新创建适配器，原来的连接会被关闭
-4. 为提高性能，系统会缓存数据库适配器，相同配置的实例会复用适配器
+4. 不同数据库的SQL语法可能有所差异，请根据实际使用的数据库类型调整SQL语句
+5. 事务操作需要根据具体数据库类型使用相应的SQL语法
+6. 错误处理：所有方法都包含错误处理，会记录错误日志并抛出异常
+
+## 错误处理
+
+```javascript
+try {
+  const result = await sql.run('SELECT * FROM non_existent_table');
+} catch (error) {
+  console.error('SQL执行失败:', error);
+  // 错误信息会被自动记录到日志
+}
+```
 
 ## 支持的数据库类型
 
 - MySQL
 - SQLite
 
+## API参考
+
+### Sql类
+
+#### constructor(config)
+创建Sql实例
+- `config`: 配置对象
+
+#### run(sql, params, timeout)
+执行查询SQL
+- `sql`: SQL语句或选项对象
+- `params`: 参数数组（可选）
+- `timeout`: 超时时间（毫秒，可选）
+
+#### exec(sql, params, timeout)
+执行修改SQL
+- `sql`: SQL语句或选项对象
+- `params`: 参数数组（可选）
+- `timeout`: 超时时间（毫秒，可选）
+
+#### open()
+手动打开数据库连接
+
+#### close()
+手动关闭数据库连接
+
+#### setConfig(config)
+动态修改配置
+- `config`: 新的配置对象
+
+#### tplQuery(paramDt, sqlDt)
+生成SQL查询条件
+- `paramDt`: 参数对象
+- `sqlDt`: SQL模板对象
+
+#### tplBody(paramDt, sqlDt)
+生成SQL数据部分
+- `paramDt`: 参数对象
+- `sqlDt`: SQL模板对象
+
+#### filter(paramDt, arr)
+过滤参数对象
+- `paramDt`: 参数对象
+- `arr`: 需要过滤的键数组
+
+#### db()
+获取底层数据库适配器
+
 ## 许可证
 
-MIT
+MIT