wok-server 0.5.0 → 0.7.0

package/src/mysql/manager/tx.ts

@@ -0,0 +1,31 @@
+import { PoolConnection } from 'mysql2'
+import { BaseMysqlManager } from './base'
+import { MysqlConfig } from '../config'
+import { MysqlException } from '../exception'
+
+/**
+ * mysql 事务会话.
+ */
+export class MysqlTxSession extends BaseMysqlManager {
+  /**
+   * 中止标识
+   */
+  #aborted = false
+
+  constructor(config: MysqlConfig, conn: PoolConnection) {
+    super({ config, connection: conn })
+  }
+
+  protected queryWithConnection<T>(queryFn: (conn: PoolConnection) => Promise<T>): Promise<T> {
+    if (this.#aborted) {
+      throw new MysqlException('Session has been aborted!')
+    }
+    return super.queryWithConnection(queryFn)
+  }
+  /**
+   * 中止，被中止后的会话不能再进行任何操作
+   */
+  abort() {
+    this.#aborted = true
+  }
+}

package/src/mysql/manager/utils.ts

@@ -0,0 +1,75 @@
+// 工具集，将一些驱动的方法进行 promise 封装，方便操作
+// 程序中没有使用 mysql2/promise ，主要是在测试中发现 mysql2/promise 不是很可靠
+// mysql2/promise 在查询方便处理的不是很好
+// query 查询在没有记录的情况下仍然会返回列表，里面会包含列定义信息，不符合预期
+
+import {
+  Connection,
+  OkPacket,
+  Pool,
+  PoolConnection,
+  ProcedureCallPacket,
+  ResultSetHeader,
+  RowDataPacket,
+  format
+} from 'mysql2'
+import { MysqlConfig } from '../config'
+import { getLogger } from '../../log'
+
+/**
+ * 查询，适用于各种 sql 的执行
+ * @param config
+ * @param conn
+ * @param sql
+ * @param values
+ * @returns
+ */
+export function promiseQuery(
+  config: MysqlConfig,
+  conn: Connection,
+  sql: string,
+  values: any[] = []
+) {
+  return new Promise<
+    | OkPacket
+    | ResultSetHeader
+    | ResultSetHeader[]
+    | RowDataPacket[]
+    | RowDataPacket[][]
+    | OkPacket[]
+    | ProcedureCallPacket
+  >((res, rej) => {
+    const start = new Date().getTime()
+    conn.query(sql, values, (err, result) => {
+      if (config.slowSqlWarn) {
+        const cost = new Date().getTime() - start
+        // 慢 sql 警告
+        if (cost > config.slowSqlMs) {
+          getLogger().warn(`[mysql slow sql] ${cost}ms ${format(sql, values)}`)
+        }
+      }
+      if (err) {
+        rej(err)
+      } else {
+        res(result)
+      }
+    })
+  })
+}
+
+/**
+ * 获取连接
+ * @param pool
+ * @returns
+ */
+export function promiseGetConnection(pool: Pool) {
+  return new Promise<PoolConnection>((res, rej) => {
+    pool.getConnection((err, conn) => {
+      if (err) {
+        rej(err)
+      } else {
+        res(conn)
+      }
+    })
+  })
+}

package/src/mysql/migration.ts

@@ -0,0 +1,149 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
+import { Connection, RowDataPacket } from 'mysql2'
+import { isAbsolute, resolve } from 'path'
+import { getLogger } from '../log'
+import { MysqlConfig } from './config'
+import { MysqlException } from './exception'
+import { promiseQuery } from './manager/utils'
+
+/**
+ * 版本信息.
+ */
+interface MysqlVersion {
+  version: number
+  filePath: string
+}
+
+/**
+ * 迁移.
+ * @param config
+ * @param conn
+ */
+export async function migrate(config: MysqlConfig, conn: Connection) {
+  const versionDir = config.versionControlDir
+  // 查找文件
+  const dir = isAbsolute(versionDir) ? versionDir : resolve(process.cwd(), versionDir)
+  if (!existsSync(dir)) {
+    throw new Error(`Directory ${versionDir} does not exist`)
+  }
+  const versions: MysqlVersion[] = []
+  // 忽略隐藏文件
+  const files = readdirSync(dir).filter(file => !file.startsWith('.'))
+  for (const file of files) {
+    const filePath = resolve(dir, file)
+    const stat = statSync(filePath)
+    if (!stat.isFile()) {
+      continue
+    }
+    if (!file.endsWith('.sql')) {
+      throw new Error(`版本文件名没有以 .sql 为后缀：${file}`)
+    }
+    const version = parseInt(file.substring(0, file.length - 4))
+    if (isNaN(version)) {
+      throw new Error(`Version file is not named with a number：${file}`)
+    }
+    versions.push({ version, filePath })
+  }
+  // 排序，判定顺序
+  versions.sort((o1, o2) => o1.version - o2.version)
+  for (let i = 0; i < versions.length; i++) {
+    const version = versions[i]
+    if (version.version !== i + 1) {
+      throw new Error(
+        `The SQL version number must start from 1 and increment one by one，error version：${version.version}`
+      )
+    }
+  }
+  await createVersionTableIfNotExist(config, conn)
+
+  // 在事务中执行版本管理，主要目的是为了通过锁来协调多个进程同时启动的情况
+  // 事务不能保存一个版本处理成功就完整回退，如有错误，仍然需要手动调整后再操作
+  await promiseQuery(config, conn, `SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED`)
+  await new Promise<void>((resolve, reject) => {
+    conn.beginTransaction(err => {
+      if (err) {
+        reject(err)
+      } else {
+        resolve()
+      }
+    })
+  })
+  try {
+    // 执行 sql, 判定当前版本
+    let currentVersion = await getCurrentVersion(config, conn)
+    if (typeof currentVersion !== 'number') {
+      // 插入初始版本号
+      await promiseQuery(config, conn, 'insert `db_version`(`version`) values (0)')
+    }
+    const filnalCurrentVersion = currentVersion || 0
+    const pendingVersions = versions.filter(ver => ver.version > filnalCurrentVersion)
+    if (!pendingVersions.length) {
+      getLogger().info('The SQL version is already the latest.')
+      return
+    }
+    const nextVersion = filnalCurrentVersion + 1
+    if (pendingVersions[0].version !== nextVersion) {
+      throw new MysqlException(
+        `MySQL migration error, the next version should be ${nextVersion}，but current is ${pendingVersions[0].version}`
+      )
+    }
+
+    for (const verion of pendingVersions) {
+      getLogger().info(`Mysql migrating, version: ${verion.version}`)
+      let sql = readFileSync(verion.filePath, { encoding: 'utf-8' })
+      await promiseQuery(config, conn, sql)
+      // 版本号
+      await promiseQuery(config, conn, `UPDATE db_version SET version=${verion.version};`)
+    }
+    // 提交
+    await new Promise<void>((resolve, reject) => {
+      conn.commit(err => {
+        if (err) {
+          reject(err)
+        } else {
+          resolve()
+        }
+      })
+    })
+    getLogger().info('Mysql migration finished.')
+  } catch (e) {
+    // 异常回退，仅能回退 dml 操作，对 ddl 无效
+    await new Promise<void>((resolve, reject) => {
+      conn.rollback(err => {
+        if (err) {
+          reject(err)
+        } else {
+          resolve()
+        }
+      })
+    })
+    throw e
+  }
+}
+
+async function createVersionTableIfNotExist(config: MysqlConfig, conn: Connection): Promise<void> {
+  await promiseQuery(
+    config,
+    conn,
+    'CREATE TABLE IF NOT EXISTS `db_version` (' +
+      '  `version` int NOT NULL,' +
+      '  PRIMARY KEY (`version`)' +
+      ') ENGINE = innodb DEFAULT CHARACTER SET = "utf8mb4" ' +
+      'COLLATE = "utf8mb4_unicode_ci";'
+  )
+}
+/**
+ * 获取当前版本，使用 for update 加锁，用于协调多进程并发场景
+ * @param config
+ * @param conn
+ * @returns
+ */
+async function getCurrentVersion(config: MysqlConfig, conn: Connection): Promise<number | null> {
+  const res = await promiseQuery(config, conn, 'select version from `db_version` for update')
+  const rows = res as RowDataPacket[]
+  if (rows.length >= 1) {
+    return rows[0].version
+  } else {
+    return null
+  }
+}

package/src/mysql/table-info.ts

@@ -0,0 +1,41 @@
+import { notBlank, ValidationOpts } from '../validation'
+
+/**
+ * 表信息. 表的字段分为三个部分：主键、普通列、时间列，分别对应的属性是：id、columns
+ * 和 createDate 还有 updatedDate，这三部分配置的字段名称不允许有重叠，否则会产生错误.
+ */
+export interface Table<T> {
+  /**
+   * 表名.
+   */
+  tableName: string
+  /**
+   * id 字段名称.
+   */
+  id: keyof T
+  /**
+   * 列字段名称.只有配置了名称的字段才会参与数据库的查询与更新，没有配置的其它字段可作其它用途。
+   * 注意：columns 配置的字段不能和 id 或更新时间和创建时间重叠，否则在更新时产生错误，将数据改错。
+   * 程序本身是不会做检查的，编写的时候必须要注意。
+   */
+  columns: Array<keyof T>
+  /**
+   * 创建时间字段信息.
+   */
+  createdDate?: {
+    column: keyof T
+    type: 'number' | 'date'
+  }
+  /**
+   * 更新时间字段信息.
+   */
+  updatedDate?: {
+    column: keyof T
+    type: 'number' | 'date'
+  }
+}
+
+export const tableValidation: ValidationOpts<Table<any>> = {
+  tableName: [notBlank('表名不能为空')],
+  id: [notBlank('id 不能为空')]
+}

package/src/task/daily.ts

@@ -0,0 +1,70 @@
+import { max, min, notNull, validate } from '../validation'
+import { Task, TaskController, execTask } from './task'
+
+/**
+ * 每日任务.
+ * @param hours 时
+ * @param minutes 分
+ * @param task 要执行的任务
+ * @param timeout 任务超时时间，单位毫秒
+ * @returns
+ */
+export function scheduleDailyTask(
+  hours: number,
+  minutes: number,
+  task: Task,
+  timeout?: number
+): TaskController {
+  // 校验
+  validate(
+    { hours, minutes },
+    {
+      hours: [notNull(), min(0), max(23)],
+      minutes: [notNull(), min(0), max(59)]
+    }
+  )
+  const taskController = new TaskController()
+  const delay = dailyTaskDelay(hours, minutes)
+  setTimeout(() => exec(hours, minutes, task, taskController, timeout), delay)
+  return taskController
+}
+/**
+ * 计算到下次指定时间点的延迟
+ * @param hours
+ * @param minutes
+ */
+export function dailyTaskDelay(hours: number, minutes: number): number {
+  const now = new Date()
+  let todayTime = new Date()
+  todayTime.setHours(hours)
+  todayTime.setMinutes(minutes)
+  todayTime.setSeconds(0)
+  todayTime.setMilliseconds(0)
+  // 如果今天还没有到指定的点，今天就执行，否则明天执行
+  if (todayTime > now) {
+    return todayTime.getTime() - now.getTime()
+  }
+  // 明天时间
+  const oneDayMilliseconds = 1000 * 3600 * 24
+  const tomorrowTime = todayTime.getTime() + oneDayMilliseconds
+  return tomorrowTime - now.getTime()
+}
+
+function exec(
+  hours: number,
+  minutes: number,
+  task: Task,
+  controller: TaskController,
+  timeout?: number
+) {
+  Promise.resolve()
+    .then(async () => {
+      if (controller.isStopped()) {
+        return
+      }
+      await execTask(task, timeout)
+      const delay = dailyTaskDelay(hours, minutes)
+      setTimeout(() => exec(hours, minutes, task, controller), delay)
+    })
+    .catch(console.error)
+}

package/src/task/fixed-delay.ts

@@ -0,0 +1,45 @@
+import { getLockManager } from '../lock'
+import { getLogger } from '../log'
+import { max, min, notNull, validate } from '../validation'
+import { Task, TaskController, execTask } from './task'
+
+/**
+ * 固定延迟执行任务
+ * @param initialDelay  第一次执行延迟的时间，单位秒
+ * @param delay 每次的延迟时间，单位秒
+ * @param task 任务
+ * @param timeout 任务超时时间，单位毫秒
+ */
+export function scheduleWithFixedDelay(
+  initialDelay: number,
+  delay: number,
+  task: Task,
+  timeout?: number
+): TaskController {
+  validate(
+    { initialDelay, delay },
+    {
+      initialDelay: [notNull(), min(0), max(3600 * 24)],
+      delay: [notNull(), min(1), max(3600 * 24)]
+    }
+  )
+  const controller = new TaskController()
+  setTimeout(() => exec(delay, task, controller, timeout), initialDelay * 1000)
+  return controller
+}
+
+function exec(delay: number, task: Task, controller: TaskController, timeout?: number) {
+  Promise.resolve()
+    .then(async () => {
+      if (controller.isStopped()) {
+        return
+      }
+      await execTask(task, timeout)
+      // 下次执行
+      setTimeout(() => exec(delay, task, controller), delay * 1000)
+    })
+    .catch(e => {
+      getLogger().error(`EXEC TASK ERROR: ${task.name}`, e)
+    })
+    .catch(console.error)
+}

package/src/task/fixed-rate.ts

@@ -0,0 +1,49 @@
+import { getLogger } from '../log'
+import { max, min, notNull, validate } from '../validation'
+import { Task, TaskController, execTask } from './task'
+
+/**
+ * 固定延迟执行任务
+ * @param initialDelay  第一次执行延迟的时间，单位秒
+ * @param period 每次的延迟时间，单位秒
+ * @param task 任务
+ * @param timeout 任务超时时间，单位毫秒
+ */
+export function scheduleWithFixedRate(
+  initialDelay: number,
+  period: number,
+  task: Task,
+  timeout?: number
+): TaskController {
+  validate(
+    { initialDelay, period },
+    {
+      initialDelay: [notNull(), min(0), max(3600 * 24)],
+      period: [notNull(), min(1), max(3600 * 24)]
+    }
+  )
+
+  const taskController = new TaskController()
+  setTimeout(() => exec(period, task, taskController, timeout), initialDelay * 1000)
+  return taskController
+}
+
+function exec(fixedDelay: number, task: Task, controller: TaskController, timeout?: number) {
+  Promise.resolve()
+    .then(async () => {
+      if (controller.isStopped()) {
+        return
+      }
+      const res = await execTask(task, timeout)
+      // 下次执行
+      let delay = res.start + fixedDelay * 1000 - new Date().getTime()
+      if (delay < 0) {
+        delay = 0
+      }
+      setTimeout(() => exec(fixedDelay, task, controller), delay)
+    })
+    .catch(e => {
+      getLogger().error(`EXEC TASK ERROR: ${task.name}`, e)
+    })
+    .catch(console.error)
+}

package/src/task/index.ts

@@ -0,0 +1,4 @@
+export { Task, TaskController } from './task'
+export * from './fixed-delay'
+export * from './fixed-rate'
+export * from './daily'

package/src/task/task.ts

@@ -0,0 +1,70 @@
+import { getLogger } from '../log'
+
+/**
+ * 任务.
+ */
+export interface Task {
+  /**
+   * 任务的名称，用于跟踪任务的执行情况，定位错误.
+   * 当任务执行时间过长或任务失败时，相关的错误提示信息会显示名称，以便于排查.
+   */
+  name: string
+  /**
+   * 任务运行.
+   * @returns
+   */
+  run: () => Promise<void>
+}
+
+/**
+ * 任务控制器
+ */
+export class TaskController {
+  #stopped = false
+  isStopped() {
+    return this.#stopped
+  }
+
+  stop() {
+    this.#stopped = true
+  }
+}
+
+/**
+ * 任务执行，封装任务执行过程中的一些通用信息输出和异常控制.
+ * @param task
+ * @param timeout 任务超时时间，单位毫秒
+ * @returns
+ */
+export async function execTask(
+  task: Task,
+  timeout?: number
+): Promise<{ start: number; cost: number; end: number }> {
+  const start = new Date().getTime()
+  try {
+    getLogger().debug(`START TASK：${task.name}`)
+    // 支持任务超时设置
+    if (timeout && timeout > 0) {
+      await Promise.race([
+        task.run(),
+        new Promise<void>((_, reject) => {
+          setTimeout(() => {
+            reject('The task has timed out.')
+          }, timeout)
+        })
+      ])
+    } else {
+      await task.run()
+    }
+  } catch (e) {
+    getLogger().error(`TASK ERROR: ${task.name}`, e)
+  }
+  const end = Date.now()
+  const cost = end - start
+  if (cost > 1000 * 60 * 5) {
+    getLogger().warn(`Task "${task.name}" takes too long ，cost ${cost}ms`)
+  } else {
+    getLogger().debug(`Task "${task.name}" has finished, taking a total of ${cost} milliseconds.`)
+  }
+  return { start, cost, end }
+}

package/src/validation/exception.ts

@@ -0,0 +1,27 @@
+/**
+ * 校验异常.
+ */
+export class ValidationException extends Error {
+  constructor(
+    /**
+     * 异常信息，如 “不能为空” 之类的.
+     */
+    readonly errMsg: string,
+    /**
+     * 校验器名称，如 length 、notNull 之类的.
+     */
+    readonly validator: string,
+    /**
+     * 校验出错的路径.
+     */
+    readonly propertyPath: string,
+    /**
+     * 值
+     */
+    readonly val: any
+  ) {
+    super(
+      `Field "${propertyPath}" failed to validate by validator ${validator} ，value：${val}，info：${errMsg}`
+    )
+  }
+}

package/src/validation/index.ts

@@ -0,0 +1,61 @@
+import { ValidationException } from './exception'
+/**
+ * 校验结果。message：错误信息，反馈给调用处；validator 校验器名称，用于记录错误信息来自哪个校验器，
+ * 以便于程序在出错时知道信息来自哪里。
+ */
+export type ValidationResult =
+  | { ok: true }
+  | {
+      ok: false
+      message: string
+      validator: string
+      /**
+       * 如果校验的是层级深的对象，内部的属性发生了错误，可用于标记属性的路径
+       */
+      propPath?: string[]
+    }
+/**
+ * 校验器.
+ */
+export type PropValidator<T> = (val: T) => ValidationResult
+
+/**
+ * 对象的校验选项
+ */
+export type ValidationOpts<T> = Partial<{ [key in keyof T]: PropValidator<T[key]>[] }>
+
+/**
+ * 校验对象.
+ * @param obj
+ */
+export function validate<T>(obj: T, opts: ValidationOpts<T>) {
+  for (const entry of Object.entries(opts)) {
+    const [prop, validators] = entry
+    const val = obj[prop as keyof T]
+    for (const validator of validators as PropValidator<any>[]) {
+      const result = validator(val)
+      if (!result.ok) {
+        const propPath = [prop]
+        if (result.propPath) {
+          propPath.push(...result.propPath)
+        }
+        const fullPath = propPath
+          .map((prop, idx) => {
+            if (idx === 0) {
+              return prop
+            }
+            if (prop.startsWith('[') && prop.endsWith(']')) {
+              return prop
+            }
+            return '.' + prop
+          })
+          .join('')
+        throw new ValidationException(result.message, result.validator, fullPath, val)
+      }
+    }
+  }
+}
+
+// 导出
+export * from './exception'
+export * from './validator'

package/src/validation/validator/array.ts

@@ -0,0 +1,32 @@
+import { PropValidator } from '..'
+import { getI18n } from '../../i18n'
+
+/**
+ * 校验数组的条目.
+ */
+export function array<T>(opts: PropValidator<T>[]): PropValidator<T[] | undefined> {
+  const validator = 'array'
+  return val => {
+    if (!val) {
+      return { ok: true }
+    }
+    if (!Array.isArray(val)) {
+      return { ok: false, validator, message: getI18n().buildMsg('validate-err-array') }
+    }
+    // 条目处理
+    for (let i = 0; i < val.length; i++) {
+      const item = val[i] as T
+      for (const validation of opts) {
+        const result = validation(item)
+        if (!result.ok) {
+          const propPath = [`[${i}]`]
+          if (result.propPath) {
+            propPath.push(...result.propPath)
+          }
+          return { ok: false, validator, message: result.message, propPath }
+        }
+      }
+    }
+    return { ok: true }
+  }
+}

package/src/validation/validator/enum.ts

@@ -0,0 +1,25 @@
+import { PropValidator } from '..'
+import { getI18n } from '../../i18n'
+/**
+ * 枚举，校验值必须是指定列表中的一个.
+ * @param list 支持的值列表，仅支持数字和字符串类型
+ * @param msg
+ * @returns
+ */
+export function enumerate<T>(list: (number | string)[], msg?: string): PropValidator<T> {
+  const validator = 'enumerate'
+  return val => {
+    if (!val) {
+      return { ok: true }
+    }
+    if (!list.some(item => item === val)) {
+      return {
+        ok: false,
+        validator,
+        // must be one of [1,2,3]
+        message: msg || getI18n().buildMsg('validate-err-enum', `[${list.join(',')}]`)
+      }
+    }
+    return { ok: true }
+  }
+}

package/src/validation/validator/index.ts

@@ -0,0 +1,11 @@
+export * from './not-null'
+export * from './not-blank'
+export * from './max'
+export * from './min'
+export * from './regexp'
+export * from './length'
+export * from './enum'
+export * from './array'
+export * from './plain-obj'
+export * from './max-length'
+export * from './min-length'