wok-server 0.5.0 → 0.7.0

package/src/mysql/config.ts

@@ -0,0 +1,130 @@
+import { max, min, notBlank, notNull, ValidationOpts } from '../validation'
+
+/**
+ * mysql 配置.
+ */
+export interface MysqlConfig {
+  /**
+   * 主机名.
+   */
+  host: string
+  /**
+   * 端口号
+   */
+  port: number
+  /**
+   * 用户名
+   */
+  user: string
+  /**
+   * 密码
+   */
+  password: string
+  /**
+   * 字符集，默认 utf8mb4
+   */
+  charset: string
+  /**
+   * 库
+   */
+  database: string
+  /**
+   * 版本控制开启.
+   */
+  versionControlEnabled: boolean
+  /**
+   * 版本控制的文件目录，默认 db_migration.
+   */
+  versionControlDir: string
+  /**
+   * 时区，默认 +08:00
+   */
+  timezone: string
+  /**
+   * 超时时间，单位毫秒，默认 10秒
+   */
+  connectTimeout: number
+  /**
+   * 调试模式
+   */
+  debug: boolean
+  /**
+   * 最大连接数
+   */
+  connectionLimit: number
+  /**
+   * 最大闲置数
+   */
+  maxIdle: number
+  /**
+   * 闲置的超时时间，当一个数据库连接不再被业务使用、处于闲置状态的时间超过这个阈值，连接池就会自动回收并关闭这个连接，释放资源。
+   */
+  idleTimeout: number
+  /**
+   * 慢 sql 警告，启用后如果一个查询过慢，就会输出警告日志。
+   */
+  slowSqlWarn: boolean
+  /**
+   * 慢 sql 毫秒数，执行时间超过设定值的 sql 会被认为是慢 sql ，默认 200
+   */
+  slowSqlMs: number
+  /**
+   * 事务超时时间，单位毫秒，默认 5000，设置为小于等于 0 的值表示不限制
+   */
+  transactionTimeout: number
+  /**
+   * 事务严格模式
+   */
+  transactionStrict: boolean
+  /**
+   * 在严格事务中可进行的最大操作次数
+   */
+  maxOpsInStrictTx: number
+}
+/**
+ * 默认配置.
+ */
+export const defaultConfig: MysqlConfig = {
+  host: 'localhost',
+  port: 3306,
+  user: 'root',
+  password: '123456',
+  charset: 'utf8mb4',
+  database: 'example',
+  versionControlEnabled: false,
+  versionControlDir: 'db_migration',
+  timezone: '+08:00',
+  connectTimeout: 10000,
+  debug: false,
+  connectionLimit: 10,
+  maxIdle: 10,
+  idleTimeout: 60000,
+  slowSqlWarn: true,
+  slowSqlMs: 200,
+  transactionTimeout: 5000,
+  transactionStrict: true,
+  maxOpsInStrictTx: 10
+}
+/**
+ * 配置校验规则.
+ */
+export const configValidation: ValidationOpts<MysqlConfig> = {
+  host: [notBlank()],
+  port: [notNull(), min(80), max(65535)],
+  user: [notBlank()],
+  password: [notBlank()],
+  charset: [notBlank()],
+  database: [notBlank()],
+  versionControlEnabled: [notNull()],
+  versionControlDir: [notNull()],
+  timezone: [notBlank()],
+  connectTimeout: [notNull(), min(1000), max(60000)],
+  connectionLimit: [notNull(), min(1), max(999)],
+  maxIdle: [notNull(), min(1), max(999)],
+  idleTimeout: [notNull(), min(1000), max(60000)],
+  slowSqlWarn: [notNull()],
+  slowSqlMs: [notNull(), min(0), max(3600000)],
+  transactionTimeout: [notNull(), min(0), max(60000)],
+  transactionStrict: [notNull()],
+  maxOpsInStrictTx: [notNull(), min(1)]
+}

package/src/mysql/exception.ts

@@ -0,0 +1,8 @@
+/**
+ * mysql 异常.
+ */
+export class MysqlException extends Error {
+  constructor(readonly message: string) {
+    super(message)
+  }
+}

package/src/mysql/index.ts

@@ -0,0 +1,88 @@
+import { Connection, createConnection, createPool } from 'mysql2'
+import { registerConfig } from '../config'
+import { MysqlConfig, configValidation, defaultConfig } from './config'
+import { MysqlException } from './exception'
+import { MysqlManager } from './manager'
+import { MysqlCriteria } from './manager/ops/criteria'
+import { migrate } from './migration'
+import { Table } from './table-info'
+
+const managerMap = new Map<string, MysqlManager>()
+
+const defaultName = 'mysql'
+
+/**
+ * 启用mysql
+ * @param name 配置名称，同时也是环境变量配置的前缀，英文开头，由英文数字和下划线成.
+ */
+export async function enableMysql(name?: string) {
+  // 校验名称
+  if (name) {
+    if (!/^[a-zA-Z][a-zA-Z0-9_]{0,31}$/.test(name)) {
+      throw new Error(
+        `mysql 配置名称必须是英文开头，由英文数字和下划线成，并且不得超过 32 位：${name}`
+      )
+    }
+  }
+  const finalName = name || defaultName
+  // 连接池配置
+  const mysqlConfig = registerConfig<MysqlConfig>(defaultConfig, finalName, configValidation)
+
+  // 数据库版本管理
+  if (mysqlConfig.versionControlEnabled) {
+    // 创建一个支持多语句的连接，专门处理迁移
+    const conn = await new Promise<Connection>((resolve, reject) => {
+      const conn = createConnection({
+        host: mysqlConfig.host,
+        port: mysqlConfig.port,
+        user: mysqlConfig.user,
+        password: mysqlConfig.password,
+        charset: mysqlConfig.charset,
+        database: mysqlConfig.database,
+        connectTimeout: mysqlConfig.connectTimeout,
+        multipleStatements: true,
+        timezone: mysqlConfig.timezone
+      })
+      conn.connect(err => (err ? reject(err) : resolve(conn)))
+    })
+    try {
+      await migrate(mysqlConfig, conn)
+    } finally {
+      await new Promise<void>((resolve, reject) => {
+        conn.end(err => (err ? reject(err) : resolve()))
+      })
+    }
+  }
+  const pool = createPool({
+    host: mysqlConfig.host,
+    port: mysqlConfig.port,
+    user: mysqlConfig.user,
+    password: mysqlConfig.password,
+    charset: mysqlConfig.charset,
+    database: mysqlConfig.database,
+    connectTimeout: mysqlConfig.connectTimeout,
+    debug: mysqlConfig.debug,
+    connectionLimit: mysqlConfig.connectionLimit,
+    maxIdle: mysqlConfig.maxIdle,
+    idleTimeout: mysqlConfig.idleTimeout,
+    timezone: mysqlConfig.timezone
+  })
+  process.addListener('beforeExit', () => pool.end())
+  managerMap.set(finalName, new MysqlManager(mysqlConfig, pool))
+}
+
+/**
+ * 获取管理器.
+ * @param name  配置名称，如果调用 enableMysql 时填写了，那么这里也要填写并保持一致
+ */
+export function getMysqlManager(name?: string) {
+  const manager = managerMap.get(name || defaultName)
+  if (!manager) {
+    throw new Error(`找不到想要的 mysql 配置 ${name ? ': ' + name : ''}，请先调用 enableMysql 启用`)
+  }
+  return manager
+}
+
+// 部分需要导出的对象
+export * from './manager'
+export { MysqlCriteria, MysqlException, Table }

package/src/mysql/manager/base.ts

@@ -0,0 +1,332 @@
+import { Pool, PoolConnection } from 'mysql2'
+import { MysqlConfig } from '../config'
+import { MysqlException } from '../exception'
+import { Table } from '../table-info'
+import {
+  DeleteManyOpts,
+  FindOpts,
+  MixCriteria,
+  MysqlPage,
+  MysqlPaginateOpts,
+  MysqlPaginateSelectOpts,
+  OrderBy,
+  UpdateOpts,
+  Updater,
+  InsertValue,
+  count,
+  deleteMany,
+  deleteById,
+  existsBy,
+  existsById,
+  find,
+  findAll,
+  findById,
+  findByIdIn,
+  findFirst,
+  insert,
+  insertMany,
+  modify,
+  paginate,
+  paginateSelect,
+  partialUpdate,
+  query,
+  update,
+  updateMany,
+  updateOne,
+  FindSelectOpts,
+  findSelect,
+  upsert,
+  upsertMany,
+  upsertWithUpdater
+} from './ops'
+import { promiseGetConnection } from './utils'
+
+/**
+ * mysql 管理器基类，提供基础的操作方法.
+ */
+export abstract class BaseMysqlManager {
+  /**
+   * @param mapping 映射
+   */
+  constructor(
+    /**
+     * 选项，连接池和连接必须有一个，连接池优先.
+     */
+    private readonly opts: { config: MysqlConfig; pool?: Pool; connection?: PoolConnection }
+  ) {
+    if (!opts.pool && !opts.connection) {
+      throw new MysqlException('Pool and Connection cannot be both null.')
+    }
+  }
+
+  protected async queryWithConnection<T>(
+    queryFn: (conn: PoolConnection) => Promise<T>
+  ): Promise<T> {
+    let conn: PoolConnection | undefined
+    if (this.opts.pool) {
+      conn = await promiseGetConnection(this.opts.pool)
+    } else if (this.opts.connection) {
+      conn = this.opts.connection
+    }
+    if (!conn) {
+      throw new MysqlException('Unable to obtain connection')
+    }
+    try {
+      return queryFn(conn)
+    } finally {
+      // 如果是连接池来的，每次连接都是新建，必须释放掉
+      if (this.opts.pool) {
+        this.opts.pool.releaseConnection(conn)
+      }
+    }
+  }
+  /**
+   * 依据id查找.
+   * @param table 表信息
+   * @param id id
+   * @returns
+   */
+  findById<T>(table: Table<T>, id: string | number): Promise<T | null> {
+    return this.queryWithConnection(conn => findById(this.opts.config, conn, table, id))
+  }
+  /**
+   * 根据id列表查询
+   * @param table
+   * @param ids
+   * @returns
+   */
+  findByIdIn<T>(table: Table<T>, ids: Array<string | number>): Promise<T[]> {
+    return this.queryWithConnection(conn => findByIdIn(this.opts.config, conn, table, ids))
+  }
+  /**
+   * 根据条件判定是否存在记录.
+   * @param table
+   * @param criteria  条件信息，可以为空，为空的情况下判定整个表是否有记录
+   * @returns
+   */
+  existsBy<T>(table: Table<T>, criteria?: MixCriteria<T>): Promise<boolean> {
+    return this.queryWithConnection(conn => existsBy(this.opts.config, conn, table, criteria))
+  }
+  /**
+   * 根据id判定记录是否存在
+   * @param table
+   * @param id
+   * @returns
+   */
+  existsById<T>(table: Table<T>, id: string | number): Promise<boolean> {
+    return this.queryWithConnection(conn => existsById(this.opts.config, conn, table, id))
+  }
+  /**
+   * 按 id 查询
+   * @param table 表信息
+   * @param id
+   */
+  deleteById<T>(table: Table<T>, id: string | number): Promise<boolean> {
+    return this.queryWithConnection(conn => deleteById(this.opts.config, conn, table, id))
+  }
+  /**
+   * 按条件删除数据。批量删除是危险操作，建议在使用时尽可能设置 limit 参数来限制数量。
+   * @param opts
+   * @returns
+   */
+  deleteMany<T>(opts: DeleteManyOpts<T>): Promise<number> {
+    return this.queryWithConnection(conn => deleteMany(this.opts.config, conn, opts))
+  }
+  /**
+   * 仅删除符合条件的一条记录，必须是相等条件
+   * @param table
+   * @param criteria
+   * @returns
+   */
+  async deleteOne<T>(table: Table<T>, criteria: Partial<T>) {
+    if (!Object.keys(criteria).length) {
+      throw new MysqlException('criteria cannot be empty !')
+    }
+    const res = await this.queryWithConnection(conn =>
+      deleteMany(this.opts.config, conn, {
+        table,
+        criteria,
+        limit: 1
+      })
+    )
+    return res === 1
+  }
+  /**
+   * 查询表中所有数据.
+   * @param table  表信息
+   * @returns
+   */
+  findAll<T>(table: Table<T>): Promise<T[]> {
+    return this.queryWithConnection(conn => findAll(this.opts.config, conn, table))
+  }
+  /**
+   * 按条件查询第一条记录.
+   * @param table 表信息
+   * @param criteria 查询条件
+   * @param orderBy 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
+   * @returns
+   */
+  findFirst<T>(
+    table: Table<T>,
+    criteria?: MixCriteria<T>,
+    orderBy?: OrderBy<T>
+  ): Promise<T | null> {
+    return this.queryWithConnection(conn =>
+      findFirst(this.opts.config, conn, table, criteria, orderBy)
+    )
+  }
+
+  /**
+   * 插入数据. 不支持自增加长id,id必须提前生成，请使用 uuid.
+   * @param table 表信息
+   * @param data 数据，数据必须是 T 的实例, T 必须是已配置的实体类类型，否则无法完成操作
+   * @returns 插入后的数据
+   */
+  insert<T>(table: Table<T>, data: InsertValue<T>): Promise<T> {
+    return this.queryWithConnection(conn => insert(this.opts.config, conn, table, data))
+  }
+  /**
+   * 批量插入
+   * @param table 表
+   * @param list 要插入的数据列表
+   */
+  insertMany<T>(table: Table<T>, list: InsertValue<T>[]): Promise<void> {
+    return this.queryWithConnection(conn => insertMany(this.opts.config, conn, table, list))
+  }
+  /**
+   * Upsert 单条数据
+   * 如果主键冲突则更新，否则插入
+   * @param table 表信息
+   * @param data 数据
+   * @returns
+   */
+  upsert<T>(table: Table<T>, data: InsertValue<T>): Promise<T> {
+    return this.queryWithConnection(conn => upsert(this.opts.config, conn, table, data))
+  }
+  /**
+   * Upsert 多条数据
+   * 如果主键冲突则更新，否则插入
+   * @param table 表
+   * @param list 要插入的数据列表
+   * @returns 影响的行数
+   */
+  upsertMany<T>(table: Table<T>, list: InsertValue<T>[]): Promise<number> {
+    return this.queryWithConnection(conn => upsertMany(this.opts.config, conn, table, list))
+  }
+  /**
+   * Upsert 单条数据（支持自定义更新器）
+   * 如果主键冲突则按自定义逻辑更新，否则插入
+   * @param table 表信息
+   * @param data 插入的数据
+   * @param updater 冲突时的更新器
+   * @returns
+   */
+  upsertWithUpdater<T>(table: Table<T>, data: InsertValue<T>, updater: Updater<T>): Promise<T> {
+    return this.queryWithConnection(conn => upsertWithUpdater(this.opts.config, conn, table, data, updater))
+  }
+  /**
+   * 更新
+   * @param table 表信息
+   * @param data
+   */
+  update<T>(table: Table<T>, data: T): Promise<T> {
+    return this.queryWithConnection(conn => update(this.opts.config, conn, table, data))
+  }
+  /**
+   * 更新所以匹配条件的记录
+   * @param opts
+   * @returns
+   */
+  updateMany<T>(opts: UpdateOpts<T>): Promise<number> {
+    return this.queryWithConnection(conn => updateMany(this.opts.config, conn, opts))
+  }
+
+  /**
+   * 只更新一条记录。仅支持相等条件，不支持范围条件，可以严格事务中使用。
+   * @param table
+   * @param criteria
+   * @param updater
+   * @returns 更新是否成功
+   */
+  updateOne<T>(table: Table<T>, criteria: MixCriteria<T>, updater: Updater<T>) {
+    if (!Object.keys(updater).length) {
+      throw new MysqlException('updater cannot be empty !')
+    }
+    return this.queryWithConnection(conn =>
+      updateOne(this.opts.config, conn, table, criteria, updater)
+    )
+  }
+
+  /**
+   * 部分更新
+   * @param table 表信息
+   * @param data 字段信息，必须要包含id字段，如果包含了更新和创建时间的字段，则忽略掉
+   */
+  partialUpdate<T>(table: Table<T>, data: Updater<T>): Promise<boolean> {
+    return this.queryWithConnection(conn => partialUpdate(this.opts.config, conn, table, data))
+  }
+
+  /**
+   * 查找实体类 自定义条件
+   * @param opts
+   * @returns
+   */
+  find<T>(opts: FindOpts<T>): Promise<T[]> {
+    return this.queryWithConnection(conn => find(this.opts.config, conn, opts))
+  }
+
+  /**
+   * 指定字段条件查询
+   * @param opts
+   * @returns
+   */
+  findSelect<T, K extends keyof T>(opts: FindSelectOpts<T, K>): Promise<Pick<T, K>[]> {
+    return this.queryWithConnection(conn => findSelect(this.opts.config, conn, opts))
+  }
+
+  /**
+   * 指定条件查询数量
+   * @param table 表信息
+   * @param criteria 查询条件
+   * @returns
+   */
+  count<T>(table: Table<T>, criteria?: MixCriteria<T>): Promise<number> {
+    return this.queryWithConnection(conn => count(this.opts.config, conn, table, criteria))
+  }
+  /**
+   * 分页查询
+   * @param opts
+   * @returns
+   */
+  paginate<T>(opts: MysqlPaginateOpts<T>): Promise<MysqlPage<T>> {
+    return this.queryWithConnection(conn => paginate(this.opts.config, conn, opts))
+  }
+
+  /**
+   * 指定字段分页查询
+   * @param opts
+   * @returns
+   */
+  paginateSelect<T, K extends keyof T>(opts: MysqlPaginateSelectOpts<T, K>): Promise<MysqlPage<Pick<T, K>>> {
+    return this.queryWithConnection(conn => paginateSelect(this.opts.config, conn, opts))
+  }
+
+  /**
+   * 自定义查询，指定 sql 、参数和返回值类型
+   * @param sql 预编译 sql ，参数使用 ”?“（英文问号） 占位，注意查询的字段名称会与返回值类型的字段映射，如果 sql 中的字段名称很特殊（比如纯数字等），需要设置别名，避免产生映射错误
+   * @param values 要传递的值，对应 sql 中的占位符 ”?“（英文问号）
+   * @param T 返回值类型，注意类型映射问题，详细可以参考文档中关于类型映射的说明
+   */
+  async query<T>(sql: string, values?: any[]): Promise<T[]> {
+    return this.queryWithConnection(conn => query(this.opts.config, conn, sql, values))
+  }
+  /**
+   * 自定义 sql 执行，必须是修改类的 sql ，否则会发生错误
+   * @param sql
+   * @param values
+   * @returns 返回影响的行数
+   */
+  async modify(sql: string, values?: any[]): Promise<number> {
+    return this.queryWithConnection(conn => modify(this.opts.config, conn, sql, values))
+  }
+}

package/src/mysql/manager/index.ts

@@ -0,0 +1,112 @@
+import { Pool } from 'mysql2'
+import { MysqlConfig } from '../config'
+import { MysqlException } from '../exception'
+import { BaseMysqlManager } from './base'
+import { MysqlTxSession } from './tx'
+import { MysqlStrictTxSession } from './tx-strict'
+import { promiseGetConnection, promiseQuery } from './utils'
+
+/**
+ * mysql 管理器，封装数据库操作，提供方便使用的实体类操作方法.
+ */
+export class MysqlManager extends BaseMysqlManager {
+  /**
+   * @param mapping 映射
+   */
+  constructor(
+    private readonly config: MysqlConfig,
+    /**
+     * 连接池.
+     */
+    private readonly pool: Pool
+  ) {
+    super({ config, pool })
+  }
+
+  /**
+   * 事务. 所有事务中的操作都必须使用 exec 函数中提供的 session 对象，直接使用 MysqlManager 上的方法
+   * 进行的操作不会在事务中生效.
+   * @param ops 逻辑执行函数，内部的所有逻辑都必须在函数内执行完，
+   * 不得有操作在函数外异步执行（异步操作不 await，或使用定时器单独执行等），否则不会在事务中生效
+   * @param opts 选项，可设置超时时间等
+   */
+  async tx<T>(
+    ops: (session: MysqlTxSession) => Promise<T>,
+    opts?: {
+      timeout?: number
+      isolationLevel?: 'REPEATABLE READ' | 'READ COMMITTED' | 'READ UNCOMMITTED' | 'SERIALIZABLE'
+      accessMode?: 'READ WRITE' | 'READ ONLY'
+    }
+  ): Promise<T> {
+    const conn = await promiseGetConnection(this.pool)
+    if (opts && opts.isolationLevel) {
+      await promiseQuery(
+        this.config,
+        conn,
+        `SET TRANSACTION ISOLATION LEVEL ${opts.isolationLevel}`
+      )
+    }
+    if (opts && opts.accessMode) {
+      await promiseQuery(this.config, conn, `SET TRANSACTION ${opts.accessMode}`)
+    }
+    await new Promise<void>((resolve, reject) => {
+      conn.beginTransaction(err => {
+        if (err) {
+          reject(err)
+        } else {
+          resolve()
+        }
+      })
+    })
+    // 构建 session ，然后执行查询
+    const session = this.config.transactionStrict
+      ? new MysqlStrictTxSession(this.config, conn)
+      : new MysqlTxSession(this.config, conn)
+    try {
+      // 超时抛出异常
+      const timeout =
+        opts && typeof opts.timeout === 'number' ? opts.timeout : this.config.transactionTimeout
+      const result =
+        timeout > 0
+          ? await Promise.race([
+              ops(session),
+              new Promise<T>((resolve, reject) => {
+                setTimeout(() => {
+                  // 立即中止会话，防止再有后续操作
+                  session.abort()
+                  reject(new MysqlException('Transaction timeout !'))
+                }, timeout)
+              })
+            ])
+          : await ops(session)
+      await new Promise<void>((resolve, reject) => {
+        conn.commit(err => {
+          if (err) {
+            reject(err)
+          } else {
+            resolve()
+          }
+        })
+      })
+      return result
+    } catch (e) {
+      await new Promise<void>((resolve, reject) => {
+        conn.rollback(err => {
+          if (err) {
+            reject(err)
+          } else {
+            resolve()
+          }
+        })
+      })
+      throw e
+    } finally {
+      // 无论如何中止会话，离开事务，会话就不能再被使用
+      session.abort()
+      this.pool.releaseConnection(conn)
+    }
+  }
+}
+
+export { FindOpts, MixCriteria, MysqlCriteria } from './ops'
+export { BaseMysqlManager, MysqlTxSession }

package/src/mysql/manager/ops/count.ts

@@ -0,0 +1,30 @@
+import { PoolConnection, RowDataPacket } from 'mysql2'
+import { Table } from '../../table-info'
+import { MixCriteria, buildQuery } from './criteria'
+import { promiseQuery } from '../utils'
+import { MysqlConfig } from '../../config'
+
+/**
+ * 按条件统计数量.
+ * @param config
+ * @param conn
+ * @param table
+ * @param criteria
+ * @returns
+ */
+export async function count<T>(
+  config: MysqlConfig,
+  conn: PoolConnection,
+  table: Table<T>,
+  criteria?: MixCriteria<T>
+): Promise<number> {
+  let query = criteria ? buildQuery(criteria) : undefined
+  const res = await promiseQuery(
+    config,
+    conn,
+    `select count(*) as ct from ?? ${query ? `where ${query.sql}` : ''} `,
+    [table.tableName].concat(query ? query.values : [])
+  )
+  const row = res as RowDataPacket[]
+  return row[0].ct
+}