@zenweb/mysql

ZenWeb 框架的 MySQL 模块，提供数据库连接池集成。

特性

• 基于 mysql-easy-query 封装，支持完整的 MySQL 操作
• 支持主从集群、读写分离
• 连接池自动管理
• 事务支持
• 可选的指标收集（配合 @zenweb/metric）
• 全局快捷访问方式

安装

npm i @zenweb/mysql

快速开始

import { create } from 'zenweb';
import modMySQL from '@zenweb/mysql';

const app = create();

app.setup(modMySQL({
  pools: {
    MASTER: {
      host: '127.0.0.1',
      port: 3306,
      user: 'root',
      password: '',
      database: 'test',
      charset: 'utf8mb4',
      timezone: '+08:00',
      connectionLimit: 100,
    },
  },
}));

app.start();

启动后可通过以下方式访问连接池：

• app.mysql — 应用级别访问
• ctx.mysql — 请求上下文访问
• $mysql — 全局快捷访问

配置选项

interface MySQLOption {
  // 数据库连接配置（必填）
  pools: {
    [name: string]: {
      host: string;
      port: number;
      user: string;
      password: string;
      database: string;
      charset?: string;
      timezone?: string;
      connectionLimit?: number;
      // ...其他 mysql 连接参数
    }
  };

  // 获取连接前的回调（可选）
  getPoolConnectionBefore?: (opt) => { pattern: string; selector?: string };

  // 获取连接后的回调（可选）
  getPoolConnectionAfter?: (conn) => conn;

  // 用于 zenorm 集成（可选）
  bindQuery?: (query) => void;

  // 禁用指标收集（可选）
  metricDisable?: boolean;
}

主从集群

配置多个数据库服务器实现读写分离：

app.setup(modMySQL({
  pools: {
    MASTER: {
      host: 'master.db.local',
      // ...主库配置
    },
    SLAVE1: {
      host: 'slave1.db.local',
      // ...从库配置
    },
    SLAVE2: {
      host: 'slave2.db.local',
      // ...从库配置
    },
  },
}));

使用时指定服务器：

// 使用从库查询
await $mysql.of('SLAVE*').query('SELECT * FROM users');

// 使用主库写入
await $mysql.query('INSERT INTO users SET ?', { name: 'test' });

使用示例

基本查询

import { Get } from 'zenweb';
import { $mysql } from '@zenweb/mysql';

export class UserController {
  @Get()
  async list() {
    return await $mysql.query('SELECT * FROM users LIMIT 10');
  }
}

事务操作

import { Get, Context } from 'zenweb';

export class OrderController {
  @Get()
  async create(ctx: Context) {
    return await ctx.mysql.transaction(async tx => {
      await tx.query('INSERT INTO orders SET ?', { user_id: 1 });
      await tx.query('UPDATE users SET order_count = order_count + 1 WHERE id = ?', [1]);
      return { success: true };
    });
  }
}

连接钩子

app.setup(modMySQL({
  pools: { /* ... */ },

  // 获取连接前，可切换目标服务器
  getPoolConnectionBefore(opt) {
    return {
      pattern: opt?.pattern || '*',
      selector: opt?.selector,
    };
  },

  // 获取连接后，可进行初始化操作
  getPoolConnectionAfter(conn) {
    // 例如设置会话变量
    return conn;
  },
}));

指标收集

配合 @zenweb/metric 模块使用时，自动收集以下指标：

| 指标名 | 说明 | |--------|------| | mysql_actives | 活跃连接数 | | mysql_idles | 空闲连接数 | | mysql_queues | 等待队列数 |

如需禁用：

app.setup(modMySQL({
  pools: { /* ... */ },
  metricDisable: true,
}));

API 导出

// 默认导出：模块安装函数
import modMySQL from '@zenweb/mysql';

// 命名导出
import { $mysql, $getPool } from '@zenweb/mysql';

// 重新导出 mysql-easy-query 的所有类型和方法
import { PoolCompatible, PoolClusterQuery } from '@zenweb/mysql';

| 导出项 | 说明 | |--------|------| | default | 模块安装函数 | | $mysql | 连接池快捷代理，可在任意位置使用 | | $getPool() | 获取当前上下文的连接池实例 |

License

MIT