wok-server 0.5.0 → 0.6.0

package/src/i18n/tag.ts

@@ -0,0 +1,18 @@
+export interface LangTag {
+  lang: string
+  region?: string
+}
+/**
+ * 解析语言标签，语言标签格式非常多，这里仅支持语言加地区的形式，如 zh-CN。
+ * 更多信息可以查看 https://www.rfc-editor.org/rfc/bcp/bcp47.txt 。
+ * @param tag
+ * @returns 语言和地区信息，为了方便匹配，全转小写
+ */
+export function parseLangTag(tag: string): LangTag {
+  const [lang, region] = tag.split('-')
+  // 解析失败，抛出错误
+  if (!lang) {
+    throw new Error(`Unable to parse lang tag：${tag}`)
+  }
+  return { lang: lang.toLowerCase(), region: region ? region.toLowerCase() : undefined }
+}

package/src/i18n/zh-HK.ts

@@ -0,0 +1,16 @@
+import { I18nMsgs } from "./msg";
+
+export const zhHK: I18nMsgs = {
+  'validate-err-array': '值不是陣列',
+  'validate-err-enum': '值必須是 {} 其中一個',
+  'validate-err-numer': '值不是數字',
+  'validate-err-max': '不得大於 {}',
+  'validate-err-min': '不得小於 {}',
+  'validate-err-empty': '不能為空',
+  'validate-err-string': '值不是字串型別',
+  'validate-err-incorrect-format': '格式不正確',
+  'validate-err-no-length': '找不到 length 屬性',
+  'validate-err-length-not-number': 'length 屬性不是數字',
+  'validate-err-min-length': '長度不得小於 {}',
+  'validate-err-max-length': '長度不得大於 {}'
+}

package/src/i18n/zh-TW.ts

@@ -0,0 +1,16 @@
+import { I18nMsgs } from './msg'
+
+export const zhTW: I18nMsgs = {
+  'validate-err-array': '值不是陣列',
+  'validate-err-enum': '值必須是 {} 其中一個',
+  'validate-err-numer': '值不是數字',
+  'validate-err-max': '不得大於 {}',
+  'validate-err-min': '不得小於 {}',
+  'validate-err-empty': '不能為空',
+  'validate-err-string': '值不是字串型別',
+  'validate-err-incorrect-format': '格式不正確',
+  'validate-err-no-length': '找不到 length 屬性',
+  'validate-err-length-not-number': 'length 屬性不是數字',
+  'validate-err-min-length': '長度不得小於 {}',
+  'validate-err-max-length': '長度不得大於 {}'
+}

package/src/i18n/zh-cn.ts

@@ -0,0 +1,16 @@
+import { I18nMsgs } from './msg'
+
+export const zhCN: I18nMsgs = {
+  'validate-err-array': '值不是数组',
+  'validate-err-enum': '值必须是 {} 其中一个',
+  'validate-err-numer': '值不是数字',
+  'validate-err-max': '不得大于 {}',
+  'validate-err-min': '不得小于 {}',
+  'validate-err-empty': '不能为空',
+  'validate-err-string': '值不是字符串类型',
+  'validate-err-incorrect-format': '格式不正确',
+  'validate-err-no-length': '找不到 length 属性',
+  'validate-err-length-not-number': 'length 属性不是数字',
+  'validate-err-min-length': '长度不得小于 {}',
+  'validate-err-max-length': '长度不得大于 {}'
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from './log'
+export * from './i18n'
+export * from './validation'
+export * from './config'
+export * from './cache'
+export * from './task'
+export * from './mvc'
+export * from './mysql'
+export * from './http-client'
+export * from './mongodb'
+export * from './lock'

package/src/lock/index.ts

@@ -0,0 +1,164 @@
+import { randomUUID } from 'crypto'
+
+export interface LockInfo {
+  /**
+   * 一个随机值，用于验证锁是否为当前程序所拥有
+   */
+  value: string
+  /**
+   * 锁过期的时间
+   */
+  expiresAt: number
+}
+
+/**
+ * 锁管理器，主要用于将不确定的顺序且有冲突的异步操作顺序执行，
+ * 防止异步流程庞大穿插执行造成的数据混乱和错误，常见于请求的处理。
+ */
+class ServerLockManager {
+  /**
+   * 存储锁信息的表，值是一个随机值，用于验证锁是否为当前程序所拥有
+   */
+  private lockMap = new Map<string, LockInfo>()
+
+  constructor() {
+    // 定期清理，将过期的信息移除，防止内存泄漏
+    setTimeout(() => {
+      const keysToBeDeleted: string[] = []
+      const now = Date.now()
+      for (const entry of this.lockMap.entries()) {
+        const [key, info] = entry
+        if (info.expiresAt < now) {
+          keysToBeDeleted.push(key)
+        }
+      }
+      if (keysToBeDeleted.length) {
+        for (const key of keysToBeDeleted) {
+          this.lockMap.delete(key)
+        }
+      }
+    }, 10000)
+  }
+
+  /**
+   * 尝试竞争锁，如果成功获取到锁，则执行 run 函数
+   * @param opts
+   * @returns 是否获取到锁
+   */
+  async tryLock(opts: {
+    /**
+     * 竞争锁的标识，相同的 key 会处于竞争关系，从而按顺序执行
+     */
+    key: string
+    /**
+     * 等待秒数，如果没有获取锁，要等待的时间，单位秒。
+     * 不设置的情况下则不会等待，获取不到锁就立即返回。
+     */
+    waitSeconds?: number
+    /**
+     * 运行函数，成功获取锁就会执行
+     * @returns
+     */
+    run: () => Promise<void>
+    /**
+     * 过期时间，单位秒。目的是防止一个程序长期占用锁，导致其它程序获取不到锁一直不能被执行
+     * 导致的死锁问题。锁一旦过期，当前程序就不再拥有锁，其它程序就可以获取到锁。默认 60 秒。
+     */
+    expiresInSeconds?: number
+  }): Promise<boolean> {
+    const value = randomUUID().toString()
+    const expiresInSeconds =
+      typeof opts.expiresInSeconds === 'number' && opts.expiresInSeconds > 0
+        ? opts.expiresInSeconds
+        : 60
+    const expiresAt = Date.now() + expiresInSeconds * 1000
+    const waitSeconds =
+      typeof opts.waitSeconds === 'number' && opts.waitSeconds > 0 ? opts.waitSeconds : 0
+    const res = await this.waitLock({
+      key: opts.key,
+      value,
+      expiresAt,
+      waitSeconds
+    })
+    if (!res) {
+      return false
+    }
+    try {
+      await opts.run()
+    } finally {
+      // 解锁
+      const info = this.lockMap.get(opts.key)
+      if (info && info.value === value) {
+        this.lockMap.delete(opts.key)
+      }
+    }
+    return true
+  }
+  /**
+   * 等待锁
+   * @param opts
+   */
+  private async waitLock(opts: {
+    /**
+     * 竞争锁的标识，相同的 key 会处于竞争关系，从而按顺序执行
+     */
+    key: string
+    /**
+     * 值
+     */
+    value: string
+    /**
+     * 等待秒数，如果没有获取锁，要等待的时间，单位秒。
+     */
+    waitSeconds: number
+    /**
+     * 过期时间
+     */
+    expiresAt: number
+  }): Promise<boolean> {
+    let start = Date.now()
+    while (true) {
+      const info = this.lockMap.get(opts.key)
+      // 锁不存在或已经过期
+      if (!info || info.expiresAt < Date.now()) {
+        // 成功获取到锁
+        this.lockMap.set(opts.key, {
+          value: opts.value,
+          expiresAt: opts.expiresAt
+        })
+        return true
+      }
+      if (info.value === opts.value) {
+        return true
+      }
+      if (Date.now() - start > opts.waitSeconds * 1000) {
+        break
+      }
+      await this.sleep()
+    }
+    return false
+  }
+  /**
+   * 沉睡
+   * @returns
+   */
+  private sleep() {
+    return new Promise<void>((resolve, reject) => {
+      setTimeout(resolve, 0)
+    })
+  }
+}
+
+let lockManager: ServerLockManager | undefined
+
+/**
+ * 获取锁管理器。锁管理器提供一个简单的异步并发控制，用于将不确定的顺序的有冲突的异步操作顺序执行，
+ * 防止异步流程庞大穿插执行造成的数据混乱和错误，常见于请求的处理。
+ * @returns
+ */
+export function getLockManager(): ServerLockManager {
+  if (!lockManager) {
+    lockManager = new ServerLockManager()
+  }
+  return lockManager
+}

package/src/log/config.ts

@@ -0,0 +1,71 @@
+import { isAbsolute, resolve } from 'path'
+import { registerConfig } from '../config'
+import { min, notBlank, notNull } from '../validation'
+import { LogLevel, parseLogLevel } from './level'
+
+/**
+ * 日志配置的定义
+ */
+interface EnvConfig {
+  /**
+   * 是否输出日志到控制台
+   */
+  console: boolean
+  /**
+   * 输出日志的格式
+   */
+  format: 'text' | 'json'
+  /**
+   * 是否输出到文件，如果为 true ，则会在根目录下生成 logs 目录存放日志文件.
+   */
+  file: boolean
+  /**
+   * 文件目录
+   */
+  fileDir: string
+  /**
+   * 文件最大保存天数.需要开启文件才有效.
+   */
+  fileMaxDays: number
+  /**
+   * 要输出的日志级别.
+   */
+  level: string
+}
+
+const envConfig = registerConfig<EnvConfig>(
+  {
+    console: true,
+    format: 'text',
+    file: false,
+    fileDir: 'logs',
+    fileMaxDays: 30,
+    level: 'INFO'
+  },
+  'LOG',
+  {
+    console: [notNull()],
+    format: [notNull()],
+    file: [notNull()],
+    fileDir: [notBlank()],
+    fileMaxDays: [min(1)],
+    level: [notBlank()]
+  }
+)
+
+export type LogConfig = Omit<EnvConfig, 'level'> & { level: LogLevel }
+
+let { fileDir, level } = envConfig
+// 目录处理
+if (!isAbsolute(fileDir)) {
+  fileDir = resolve(process.cwd(), fileDir)
+}
+
+export const config: LogConfig = Object.freeze({
+  file: envConfig.file,
+  fileDir,
+  fileMaxDays: envConfig.fileMaxDays,
+  level: parseLogLevel(level),
+  console: envConfig.console,
+  format: envConfig.format
+})

package/src/log/date.ts

@@ -0,0 +1,19 @@
+export function currentDateTimeStr() {
+  return formatDateTime(new Date())
+}
+
+export function formatDateTime(date: Date) {
+  return (
+    date.toLocaleString('zh-CN', {
+      timeZone: 'Asia/Shanghai',
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      hour12: false,
+      hourCycle: 'h23'
+    }) + `.${date.getMilliseconds()}`
+  )
+}

package/src/log/file.ts

@@ -0,0 +1,215 @@
+import { existsSync, statSync } from 'fs'
+import { readdir, rm, appendFile, mkdir } from 'fs/promises'
+import { EOL } from 'os'
+import { dirname, resolve, isAbsolute } from 'path'
+import { config, LogConfig } from './config'
+import { formatLogJson, formatLogText, Log } from './log'
+
+// 日志队列
+let LOG_QUEUE: Log[] = []
+// 最大缓冲数量
+const MAX_QUEUE_SIZE = 1024
+// 写入定时器
+let WRITE_TIMER: NodeJS.Timeout | null = null
+// 延迟写入时间（毫秒）
+const WRITE_DELAY = 100
+// 是否已经安排了清理任务
+let CLEANUP_SCHEDULED = false
+// 清理任务定时器
+let CLEANUP_TIMER: NodeJS.Timeout | null = null
+
+/**
+ * 文件存储.
+ * @param log 日志对象
+ * @param logConfig 日志配置
+ */
+export function fileStore(log: Log, logConfig: LogConfig): void {
+  // 将日志添加到队列
+  LOG_QUEUE.push(log)
+
+  // 如果队列超过最大缓冲数量，立即写入
+  if (LOG_QUEUE.length >= MAX_QUEUE_SIZE) {
+    writeLogs(logConfig).catch(e => console.error('Writing log file failed', e))
+
+    // 在写入前检查是否需要安排清理任务
+    if (!CLEANUP_SCHEDULED) {
+      scheduleCleanupTask(logConfig)
+    }
+    return
+  }
+
+  // 安排延迟写入
+  if (!WRITE_TIMER) {
+    WRITE_TIMER = setTimeout(() => {
+      WRITE_TIMER = null
+      writeLogs(logConfig).catch(e => console.error('Writing log file failed', e))
+    }, WRITE_DELAY)
+  }
+
+  // 如果启用了文件存储并且还没有安排清理任务，则安排清理任务
+  if (!CLEANUP_SCHEDULED) {
+    scheduleCleanupTask(logConfig)
+  }
+}
+
+/**
+ * 根据日期构建日志文件路径
+ * @param logConfig 日志配置
+ * @param dateKey 数字键 (格式：年*10000 + 月*100 + 日)
+ * @returns 日志文件路径
+ */
+function buildFilePathByDate(logConfig: LogConfig, dateKey: number): string {
+  const fileName = `${dateKey}.log`
+  // 确保目录是绝对路径
+  let fileDir = logConfig.fileDir
+  if (!isAbsolute(fileDir)) {
+    fileDir = resolve(process.cwd(), fileDir)
+  }
+  return resolve(fileDir, fileName)
+}
+
+/**
+ * 根据日期对象计算数字键
+ * @param date 日期对象
+ * @returns 数字键 (格式：年*10000 + 月*100 + 日)
+ */
+function calculateDateKey(date: Date): number {
+  const year = date.getFullYear()
+  const month = date.getMonth() + 1 // 转换为1-12
+  const day = date.getDate()
+  return year * 10000 + month * 100 + day
+}
+
+/**
+ * 写入日志到文件
+ * @param logConfig 日志配置
+ */
+async function writeLogs(logConfig: LogConfig): Promise<void> {
+  if (!LOG_QUEUE.length || !logConfig.file) {
+    return
+  }
+
+  // 复制队列并清空原始队列
+  const logsToWrite = [...LOG_QUEUE]
+  LOG_QUEUE = []
+
+  // 按日期对日志进行分组 - 使用数字键提升性能
+  const logsByDate = new Map<number, Log[]>()
+
+  logsToWrite.forEach(log => {
+    const logDate = new Date(log.time)
+    // 直接使用日期对象计算数字键
+    const dateKey = calculateDateKey(logDate)
+    const dateLogs = logsByDate.get(dateKey)
+    if (dateLogs) {
+      dateLogs.push(log)
+    } else {
+      logsByDate.set(dateKey, [log])
+    }
+  })
+
+  // 为每个日期组写入对应的日志文件
+  for (const [dateKey, dateLogs] of logsByDate.entries()) {
+    // 直接使用数字键构建文件路径
+    const filePath = buildFilePathByDate(logConfig, dateKey)
+    const dir = dirname(filePath)
+
+    // 确保目录存在
+    if (!existsSync(dir)) {
+      await mkdir(dir, { recursive: true })
+    }
+
+    // 格式化并写入该日期的所有日志
+    const lines = dateLogs
+      .map(log => (logConfig.format === 'json' ? formatLogJson(log) : formatLogText(log)))
+      .join(EOL)
+
+    try {
+      await appendFile(filePath, lines)
+    } catch (error) {
+      console.error(`Failed to write logs for date ${dateKey}:`, error)
+      // 继续处理下一个日期的日志，不中断整个写入过程
+    }
+  }
+}
+
+/**
+ * 执行日志清理任务
+ * @param logConfig 日志配置
+ */
+async function performCleanupTask(logConfig: LogConfig): Promise<void> {
+  try {
+    let dir = logConfig.fileDir
+    if (!isAbsolute(dir)) {
+      dir = resolve(process.cwd(), dir)
+    }
+
+    // 确保目录存在
+    if (!existsSync(dir)) {
+      return
+    }
+
+    const files = await readdir(dir)
+    const now = new Date().getTime()
+    const maxAge = logConfig.fileMaxDays * 24 * 3600 * 1000
+
+    for (const file of files) {
+      try {
+        // 获取文件的完整路径
+        const filePath = resolve(dir, file)
+
+        // 获取文件的最后修改时间
+        const fileStats = statSync(filePath)
+        const lastModifiedTime = fileStats.mtime.getTime()
+
+        // 检查文件是否过期（最后修改时间早于最大保留天数）
+        if (lastModifiedTime + maxAge < now) {
+          console.warn(`Remove log file： ${file}`)
+          await rm(filePath)
+        }
+      } catch (error) {
+        console.error(`Failed to process log file ${file}:`, error)
+        // 继续处理下一个文件，不中断清理过程
+        continue
+      }
+    }
+  } catch (error) {
+    console.error('Error during log cleanup:', error)
+  } finally {
+    // 清理完成后，重置清理任务安排状态
+    CLEANUP_SCHEDULED = false
+  }
+}
+
+/**
+ * 安排日志清理任务
+ * @param logConfig 日志配置
+ */
+function scheduleCleanupTask(logConfig: LogConfig): void {
+  CLEANUP_SCHEDULED = true
+
+  // 清除现有的清理定时器
+  if (CLEANUP_TIMER) {
+    clearTimeout(CLEANUP_TIMER)
+  }
+
+  // 设置清理任务在一天后执行
+  const delay = 24 * 60 * 60 * 1000
+  CLEANUP_TIMER = setTimeout(() => {
+    CLEANUP_TIMER = null
+    performCleanupTask(logConfig).catch(e => console.error('Cleanup task failed', e))
+  }, delay)
+}
+
+/**
+ * 确保所有日志都被写入文件
+ * 可以在应用程序关闭时调用
+ */
+export async function flushLogsToFile(): Promise<void> {
+  if (WRITE_TIMER) {
+    clearTimeout(WRITE_TIMER)
+    WRITE_TIMER = null
+  }
+
+  await writeLogs(config)
+}

package/src/log/index.ts

@@ -0,0 +1,136 @@
+import { config } from './config'
+import { fileStore } from './file'
+import { LogLevel } from './level'
+import { formatLogJson, formatLogText, Log } from './log'
+import { getLogStore, setLogStore } from './store'
+
+/**
+ * 文件存储
+ */
+if (config.file) {
+  setLogStore(fileStore)
+}
+
+class Logger {
+  constructor(private prefix?: string) {}
+
+  /**
+   * 输出日志
+   * @param level
+   * @param message
+   * @param error
+   */
+  private log(level: LogLevel, message: string, error?: any) {
+    if (level < config.level) {
+      return
+    }
+    const log: Log = {
+      level,
+      content: message,
+      time: new Date(),
+      prefix: this.prefix,
+      error
+    }
+    // 控制台输出日志
+    if (config.console) {
+      // const msg = config.format === 'text' ? formatLogText(log, true) : formatLogJson(log, true)
+      // 控制台强制使用 text 格式，json 格式只在文件中输出
+      const msg = formatLogText(log, true)
+      switch (level) {
+        case LogLevel.DEBUG:
+          console.debug(msg)
+          break
+        case LogLevel.INFO:
+          console.info(msg)
+          break
+        case LogLevel.WARN:
+          console.warn(msg)
+          break
+        case LogLevel.ERROR:
+          console.error(msg)
+          break
+      }
+      if (error) {
+        console.error(error)
+      }
+    }
+    // 自定义存储中输出日志
+    const store = getLogStore()
+    if (store) {
+      store(log, config)
+    }
+  }
+  /**
+   * debug 日志
+   */
+  debug(message: string) {
+    this.log(LogLevel.DEBUG, message)
+  }
+
+  isDebugEnabled() {
+    return LogLevel.DEBUG >= config.level
+  }
+  /**
+   * info 日志
+   * @param message
+   */
+  info(message: string) {
+    this.log(LogLevel.INFO, message)
+  }
+
+  isInfoEnabled() {
+    return LogLevel.INFO >= config.level
+  }
+  /**
+   * 警告日志
+   * @param message
+   * @param error
+   */
+  warn(message: string, error?: any) {
+    this.log(LogLevel.WARN, message, error)
+  }
+  /**
+   * 等同于 warn
+   * @param message
+   * @param error
+   */
+  warning(message: string, error?: any) {
+    this.log(LogLevel.WARN, message, error)
+  }
+
+  isWarnEnabled() {
+    return LogLevel.WARN >= config.level
+  }
+  /**
+   * 错误日志
+   * @param message
+   * @param error
+   */
+  error(message: string, error?: any) {
+    this.log(LogLevel.ERROR, message, error)
+  }
+
+  isErrorEnabled() {
+    return LogLevel.ERROR >= config.level
+  }
+}
+
+const defaultLogger = new Logger()
+
+/**
+ * 获取日志对象.
+ *
+ * @param prefix 日志前缀，如果有值，每条日志前都会加上前缀信息
+ * @returns
+ */
+export function getLogger(prefix?: string) {
+  if (prefix) {
+    return new Logger(prefix)
+  }
+  return defaultLogger
+}
+
+export * from './config'
+export * from './level'
+export * from './log'
+export { setLogStore } from './store'