wok-server 0.5.0 → 0.6.0

package/skills/wok-server-validate/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: wok-server-validate
+description: wok-server 校验组件使用指南，提供对象属性校验、内置规则和自定义规则的完整支持。
+license: MIT
+metadata:
+  author: Peak Tai
+  email: peaktai@qq.com
+---
+
+# wok-server 校验组件
+
+## 概述
+
+校验组件提供 `validate` 函数校验对象属性，内置 11 种通用校验规则，支持嵌套对象/数组校验和自定义规则。校验器通过国际化组件自动生成多语言错误提示。
+
+## 源码与类型定义
+
+安装 `wok-server` 后，可通过以下路径查看源码与类型定义：
+
+- 源码目录：`node_modules/wok-server/src/validation/`
+- 类型定义：`node_modules/wok-server/types/` （引用 validation 组件的 `.d.ts` 文件）
+
+核心源码文件：
+
+| 文件                | 说明                               |
+| :------------------ | :--------------------------------- |
+| `index.ts`          | 模块入口，`validate` 函数          |
+| `exception.ts`      | `ValidationException` 异常类       |
+| `validator/`        | 内置校验规则函数目录               |
+| `validator/index.ts`| 导出所有内置校验器                 |
+
+---
+
+## 基本使用
+
+```ts
+import { validate, notNull, length } from 'wok-server'
+
+validate(
+  { name: 'tom' },
+  { name: [notNull(), length({ min: 2, max: 16 })] }
+)
+```
+
+- 校验通过无返回值
+- 校验失败抛出 `ValidationException`（含 `errMsg`、`validator`、`propertyPath`、`val`）
+
+```ts
+try {
+  validate(obj, rules)
+} catch (e) {
+  if (e instanceof ValidationException) {
+    console.log(e.propertyPath)  // 如 "profile.theme"
+    console.log(e.errMsg)        // 如 "不能为空"
+  }
+}
+```
+
+### 内置校验规则
+
+| 函数          | 作用                                    | 空值行为         |
+| :------------ | :-------------------------------------- | :--------------- |
+| `notNull`     | 不能是 `null` 或 `undefined`            | —                |
+| `notBlank`    | 不能是 `null`/`undefined`/空白字符串     | —                |
+| `min(n)`      | 数字必须 ≥ n                            | 空值跳过         |
+| `max(n)`      | 数字必须 ≤ n                            | 空值跳过         |
+| `length`      | 字符串/数组长度必须在 [min, max] 之间   | 空值跳过         |
+| `maxLength(n)`| 长度必须 ≤ n                            | 空值跳过         |
+| `minLength(n)`| 长度必须 ≥ n                            | 空值跳过         |
+| `regexp`      | 正则校验                                | 空值跳过         |
+| `enumerate`   | 值必须在指定列表中                      | 空值跳过         |
+| `array`       | 校验数组元素                            | —                |
+| `plainObject` | 校验嵌套对象                            | —                |
+
+**空值行为**：大部分较验器对空值（`null`/`undefined`）返回 `{ ok: true }` 跳过，需配合 `notNull` 使用。`notNull` 和 `notBlank` 本身才校验空。
+
+### 国际化支持
+
+所有内置校验器的默认错误消息通过 `getI18n().buildMsg(...)` 自动生成，支持多语言。也可以覆盖 `message` 参数。
+
+```ts
+notNull('名称不能为空')
+length({ min: 2, max: 16, message: '名称必须是2到16个字' })
+```
+
+---
+
+## 嵌套校验
+
+```ts
+import { array, plainObject } from 'wok-server'
+
+interface Tag { id: string; name: string }
+interface User { profile: { theme: string }; tags: Tag[] }
+
+validate<User>(data, {
+  profile: [notNull(), plainObject({
+    theme: [notBlank()]
+  })],
+  tags: [notNull(), maxLength(5), array([
+    notNull(),
+    plainObject({
+      id: [notBlank()],
+      name: [notBlank()]
+    })
+  ])]
+})
+```
+
+- `plainObject` 为嵌套对象定义子校验规则
+- `array` 为数组元素定义校验规则（每个元素都校验）
+- `ValidationException.propertyPath` 会记录完整路径（如 `tags[0].name`）
+
+**⚠️ 建议嵌套不超过一层**，否则难以维护。
+
+---
+
+## 自定义校验规则
+
+```ts
+import { PropValidator } from 'wok-server'
+
+function customValidate(): PropValidator<string> {
+  const validator = 'custom'
+  return val => {
+    if (!val) return { ok: true }                    // 不校验空
+    if (typeof val !== 'string') {
+      return { ok: false, validator, message: '值不是字符串' }
+    }
+    if (val.startsWith('t')) {
+      return { ok: false, validator, message: '不能以 t 开头' }
+    }
+    return { ok: true }
+  }
+}
+
+validate({ name: 'tim' }, { name: [customValidate()] })
+```
+
+`PropValidator<T>` 定义为 `(val: T) => ValidationResult`。
+- `ok: true` 校验通过
+- `ok: false` 校验失败，需提供 `validator` 名称和 `message` 错误信息
+- 可附带 `propPath` 字段（在被 `array`/`plainObject` 内部逐层拼接使用）
+
+自定义校验器需要国际化时，自行调用 `getI18n().buildMsg()`。
+
+---
+
+## validate 函数实现
+
+```ts
+function validate<T>(obj: T, opts: ValidationOpts<T>): void
+```
+
+内部遍历 `opts` 的每个 key，取出对应的值，依次运行该 key 的所有校验器函数。第一个失败即抛出 `ValidationException`。属性路径通过 `propPath` 逐级拼接（嵌套时 `array`/`plainObject` 校验器内部会设置）。
+
+---
+
+## ValidationOpts 类型
+
+```ts
+type ValidationOpts<T> = Partial<{
+  [key in keyof T]: PropValidator<T[key]>[]
+}>
+```
+
+即对象的每个属性对应一个校验器函数数组。

package/src/cache/cache.ts

@@ -0,0 +1,118 @@
+import { config } from './config'
+import { CacheStat } from './stat'
+
+/**
+ * 缓存内容
+ */
+export interface CacheContent {
+  /**
+   * 保存的值
+   */
+  val: any
+  /**
+   * 过期时间
+   */
+  expireAt: number
+}
+
+export class Cache {
+  /**
+   * promise 表，作用是处理异步并发问题，如果有相同的 key 同时请求，保证异步的 provider 只执行一次
+   */
+  private promiseMap = new Map<string, Promise<any>>()
+
+  constructor(
+    private readonly valueMap: Map<string, CacheContent>,
+    private readonly stat?: CacheStat
+  ) {}
+
+  /**
+   * 放入缓存
+   * @param key
+   * @param val
+   * @param expiresInSeconds
+   */
+  put(key: string, val: any, expiresInSeconds?: number) {
+    const finalExpiresInSeconds =
+      typeof expiresInSeconds === 'number' ? expiresInSeconds : config.defaultExpireInSeconds
+    this.valueMap.set(key, {
+      val,
+      expireAt: new Date().getTime() + finalExpiresInSeconds * 1000
+    })
+  }
+
+  /**
+   * 获取缓存值
+   * @param key
+   * @returns
+   */
+  get<T>(key: string): T | undefined {
+    const content = this.valueMap.get(key)
+    if (!content) {
+      this.stat?.addGet(false)
+      return undefined
+    }
+    if (content.expireAt < new Date().getTime()) {
+      this.stat?.addGet(false)
+      this.valueMap.delete(key)
+      return undefined
+    }
+    this.stat?.addGet(true)
+    return content.val
+  }
+  /**
+   * 清除所有缓存
+   */
+  clear() {
+    this.valueMap.clear()
+    this.stat?.clear()
+  }
+
+  /**
+   * 删除.
+   * @param key
+   */
+  remove(key: string) {
+    this.valueMap.delete(key)
+  }
+
+  /**
+   * 在缓存值不存在时计算缓存的值，然后放入并返回.
+   * @param key
+   * @param provider
+   * @param expiresInSeconds
+   */
+  async computeIfAbsent<T>(
+    key: string,
+    provider: () => Promise<T> | T,
+    expiresInSeconds?: number
+  ): Promise<T> {
+    const content = this.valueMap.get(key)
+    if (content && content.expireAt >= new Date().getTime()) {
+      this.stat?.addGet(true)
+      return content.val
+    }
+    this.stat?.addGet(false)
+    // 如果已经在处理中，则直接返回 promise
+    const ep = this.promiseMap.get(key)
+    if (ep) {
+      return ep
+    }
+    // 创建新的异步流程
+    const promise = Promise.resolve().then(async () => {
+      try {
+        const finalExpireInSeconds =
+          typeof expiresInSeconds === 'number' ? expiresInSeconds : config.defaultExpireInSeconds
+        // 计算值
+        const res = provider()
+        const val = res instanceof Promise ? await res : res
+        this.put(key, val, finalExpireInSeconds)
+        return val
+      } finally {
+        this.promiseMap.delete(key)
+      }
+    })
+    this.promiseMap.set(key, promise)
+    return promise
+  }
+}

package/src/cache/config.ts

@@ -0,0 +1,53 @@
+import { registerConfig } from '../config'
+import { max, min, notNull } from '../validation'
+
+/**
+ * 缓存的配置
+ */
+interface CacheConfig {
+  /**
+   * 默认的存活时长，取值：1-3600，默认 60。存活时间应该尽可能的短，尤其是当缓存的内容比较大时，
+   * 否则缓存的内容长时间占用内存，会对 gc 造成影响。
+   */
+  defaultExpireInSeconds: number
+  /**
+   * 是否启用统计任务，启用后每隔指定的时间打印一次缓存统计信息，用于了解缓存的情况.
+   */
+  statTaskEnabled: boolean
+  /**
+   * 统计任务执行的周期,单位秒，取值 60-3600。统计周期也即是时间窗口，
+   * 每个周期都是独立的，只统计这个周期内的缓存使用情况。
+   */
+  statInterval: number
+  /**
+   * 最大元素数量，为了控制缓存占用的内存空间，可以将 maxElements 设置的低一些。
+   */
+  maxElements: number
+  /**
+   * 数据清理任务执行周期，单位秒.取值 1-3600，清理任务完成两件事：删除过期数据和驱逐多余记录。
+   * 如果项目规模小，缓存的内容非常少，可以将间隔设置长一些，降低频率.
+   * 如果缓存的内容很多，频率需要高一些，及时将无效数据清理掉。
+   * 否则缓存会长时间占用很高的内存无法被回收，回收器完成检查却需要很长时间，影响gc效率.
+   */
+  cleaningInterval: number
+}
+
+const ENV_PREFIX = 'CACHE'
+
+export const config = registerConfig<CacheConfig>(
+  {
+    defaultExpireInSeconds: 60,
+    statTaskEnabled: false,
+    statInterval: 300,
+    maxElements: 1024,
+    cleaningInterval: 60
+  },
+  ENV_PREFIX,
+  {
+    defaultExpireInSeconds: [notNull(), min(1), max(3600)],
+    statTaskEnabled: [notNull()],
+    statInterval: [notNull(), min(1), max(3600 * 24)],
+    maxElements: [notNull(), min(1), max(Number.MAX_VALUE)],
+    cleaningInterval: [notNull(), min(1), max(3600)]
+  }
+)

package/src/cache/index.ts

@@ -0,0 +1,27 @@
+import { scheduleWithFixedDelay } from '../task'
+import { Cache } from './cache'
+import { config } from './config'
+import { PurgeTask } from './purge-task'
+import { CacheStat } from './stat'
+
+const valueMap = new Map<string, any>()
+const stat = config.statTaskEnabled ? new CacheStat(valueMap) : undefined
+const cache = new Cache(valueMap, stat)
+
+// 清理任务
+scheduleWithFixedDelay(config.cleaningInterval, config.cleaningInterval, new PurgeTask(valueMap))
+
+// 统计任务
+if (config.statTaskEnabled) {
+  scheduleWithFixedDelay(config.statInterval, config.statInterval, {
+    name: 'Cache statistics',
+    async run() {
+      stat?.log()
+      stat?.clear()
+    }
+  })
+}
+
+export function getCache() {
+  return cache
+}

package/src/cache/purge-task.ts

@@ -0,0 +1,53 @@
+import { getLogger } from '../log'
+import { Task } from '../task'
+import { CacheContent } from './cache'
+import { config } from './config'
+
+/**
+ * 缓存清理任务
+ */
+export class PurgeTask implements Task {
+  readonly name = 'Cache purge'
+
+  constructor(private readonly valueMap: Map<string, CacheContent>) {}
+
+  async run(): Promise<void> {
+    let removeCount = 0
+    for (const entry of this.valueMap.entries()) {
+      const [key, value] = entry
+      if (value.expireAt < new Date().getTime()) {
+        this.valueMap.delete(key)
+        removeCount++
+      }
+    }
+    if (removeCount > 0) {
+      getLogger().info(
+        `A total of ${removeCount} expired cache ${
+          removeCount > 1 ? 'records' : 'record'
+        } have been cleared.`
+      )
+    }
+
+    // 如果过期的都清理掉，但是元素总数仍然超出，则删除多余元素，删除是从头开始删除的
+    // 看上去是按put顺序清理最早的，实际上随机的，重复 set 相同的 key，key 的位置是不会变的，不保证 key 的顺序
+    // 所以，缓存是随机驱逐的
+    // 目前没有考虑支持其它的策略，因为需要额外记录信息，清理的逻辑也可能更复杂
+    // nodejs 是单线程模式的，规模上去后，可能需要执行较长的时间带来阻塞
+    if (this.valueMap.size > config.maxElements) {
+      let diff = this.valueMap.size - config.maxElements
+      let evictedCount = 0
+      for (const key of this.valueMap.keys()) {
+        this.valueMap.delete(key)
+        evictedCount++
+        if (evictedCount >= diff) {
+          break
+        }
+      }
+      getLogger().info(
+        `A total of ${evictedCount} cache ${
+          evictedCount > 1 ? 'records' : 'record'
+        } have been evicted.`
+      )
+    }
+  }
+}

package/src/cache/stat.ts

@@ -0,0 +1,47 @@
+import { getLogger } from '../log'
+import { formatDateTime } from '../log/date'
+import { config } from './config'
+
+/**
+ * 缓存统计.
+ */
+export class CacheStat {
+  /**
+   * 开始统计时间
+   */
+  private start: Date
+  private totalGet = 0
+  private totalHit = 0
+
+  constructor(private readonly valueMap: Map<string, any>) {
+    this.start = new Date()
+  }
+  /**
+   * 添加 get 次数
+   * @param hit 是否命中
+   */
+  addGet(hit: boolean) {
+    this.totalGet++
+    if (hit) {
+      this.totalHit++
+    }
+  }
+  /**
+   * 清空统计信息，重新开始统计.
+   */
+  clear() {
+    this.start = new Date()
+    this.totalGet = 0
+    this.totalHit = 0
+  }
+  /**
+   * 输出日志
+   */
+  log() {
+    getLogger().info(
+      `Cache statistics，time window ：${formatDateTime(this.start)} - now， hit ：${
+        this.totalHit
+      }/${this.totalGet}，capacity：${this.valueMap.size}/${config.maxElements}`
+    )
+  }
+}

package/src/config/convert.ts

@@ -0,0 +1,27 @@
+import { ConfigException } from './exception'
+/**
+ * 转换值.
+ * @param val
+ * @param defaultVal
+ */
+export function convert(val: string, defaultVal: any): string | number | boolean {
+  if (typeof defaultVal === 'string') {
+    return val
+  } else if (typeof defaultVal === 'number') {
+    const num = parseFloat(val)
+    if (isNaN(num)) {
+      throw new ConfigException(`Unable to convert value to number ：${val}`)
+    }
+    return num
+  } else if (typeof defaultVal === 'boolean') {
+    if (val === 'true') {
+      return true
+    } else if (val === 'false') {
+      return false
+    } else {
+      throw new ConfigException(`Cannot convert value to a boolean type：${val}`)
+    }
+  } else {
+    throw new ConfigException(`Unsupported conversion type ：${typeof defaultVal}`)
+  }
+}

package/src/config/exception.ts

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

package/src/config/index.ts

@@ -0,0 +1,92 @@
+import { config } from 'dotenv'
+import { validate, ValidationOpts } from '../validation'
+import { convert } from './convert'
+import { ConfigException } from './exception'
+
+// 初始化 .env 文件
+config()
+
+/**
+ * 环境变量配置表.
+ */
+const configEnvMap = new Map<string, any>()
+
+/**
+ * 获取配置
+ * @param envPrefix
+ */
+export function getConfig<T>(envPrefix: string): T | undefined {
+  return configEnvMap.get(envPrefix)
+}
+
+/**
+ * 注册配置信息.
+ * @param defaultConfig 默认值, 模块会根据默认值来映射环境变量，默认值所有的属性都不能是 undefined，否则无法映射.
+ * @param envPrefix 环境变量前缀.
+ * @param validation 校验规则，如果有值，初始化的时候会对配置进行校验
+ * @returns 映射了环境变量后的配置
+ */
+export function registerConfig<T extends {}>(
+  defaultConfig: T,
+  envPrefix: string,
+  validation?: ValidationOpts<T>
+): T {
+  if (configEnvMap.has(envPrefix)) {
+    throw new ConfigException(`The prefix "${envPrefix}" has already been registered`)
+  }
+  const config = generateConfig(defaultConfig, envPrefix, validation)
+  configEnvMap.set(envPrefix, config)
+  return config
+}
+
+/**
+ * 根据环境变量来生成配置对象，与 registerConfig 的参数是一致的，和 registerConfig 不同的是
+ * generateConfig 可以多次重复使用，方便在运行时更改环境变量后再生成配置，而调用 registerConfig
+ * 一旦注册后不能再被更改。之所以这样设计是为了方便程序的测试，模拟不同的环境来运行程序，和其它的
+ * 一些特殊需求。
+ * @param defaultConfig
+ * @param envPrefix
+ * @param validation
+ */
+export function generateConfig<T extends {}>(
+  defaultConfig: T,
+  envPrefix: string,
+  validation?: ValidationOpts<T>
+) {
+  // 环境变量匹配
+  for (const propName in defaultConfig) {
+    const defaultVal = defaultConfig[propName]
+    const envName = buildEnvName(envPrefix, propName)
+    const envVal = process.env[envName]
+    console.log(
+      `[CONFIG]prefix：${envPrefix}，env variable：${envName} ,value：${envVal}，mapping property：${propName}`
+    )
+    if (!envVal) {
+      continue
+    }
+    const finalVal = convert(envVal, defaultVal)
+    ;(defaultConfig as any)[propName] = finalVal
+  }
+  // 校验
+  if (validation) {
+    try {
+      validate(defaultConfig, validation)
+    } catch (e) {
+      console.error(e)
+      throw new ConfigException(
+        `Error in verifying configuration information, configuration prefix：${envPrefix}`
+      )
+    }
+  }
+  return defaultConfig
+}
+
+function buildEnvName(envPrefix: string, propName: string) {
+  let part2 = propName.replace(/[A-Z]+/g, subStr => `_${subStr}`)
+  if (part2.startsWith('_')) {
+    part2 = part2.substring(1)
+  }
+  return `${envPrefix.toUpperCase()}_${part2.toUpperCase()}`
+}
+
+export * from './exception'