wok-server 0.4.13 → 0.6.0

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

@@ -0,0 +1,214 @@
+---
+name: wok-server-i18n
+description: wok-server 国际化组件使用指南，支持多语言消息构建、语言绑定、扩展业务国际化内容。
+license: MIT
+metadata:
+  author: Peak Tai
+  email: peaktai@qq.com
+---
+
+# wok-server 国际化组件
+
+## 概述
+
+国际化组件提供多语言消息构建能力，内置 12 种语言，支持扩展新语言和业务国际化内容。`getI18n()` 返回全局单例。
+
+注意：全局 i18n 对象是共享的，异步请求中可能出现语言被其他请求串改的问题——请使用绑定功能（`bindByRequest` / `bindLang`）解决。
+
+## 源码与类型定义
+
+安装 `wok-server` 后，可通过以下路径查看源码与类型定义：
+
+- 源码目录：`node_modules/wok-server/src/i18n/`
+- 类型定义：`node_modules/wok-server/types/` （引用 i18n 组件的 `.d.ts` 文件）
+
+核心源码文件：
+
+| 文件            | 说明                               |
+| :-------------- | :--------------------------------- |
+| `i18n.ts`       | `I18n`、`BoundI18n`、`ExtensibleI18n` 三个类 |
+| `index.ts`      | 模块入口，`getI18n()` 初始化 12 种语言 |
+| `tag.ts`        | 语言标签解析（`zh-CN` → `{lang, region}`） |
+| `msg.ts`        | 内置消息模板类型定义 `I18nMsgs`     |
+| `zh-cn.ts` 等   | 各语言的消息模板文件               |
+
+---
+
+## 获取实例
+
+```ts
+import { getI18n } from 'wok-server'
+const i18n = getI18n()
+```
+
+首次调用完成初始化后始终返回同一实例。初始化时会根据环境变量 `LANG` 或 `LC_CTYPE` 自动切换语言。
+
+---
+
+## 基本操作
+
+### 获取 / 切换语言
+
+```ts
+const lang = i18n.getLang()        // 'zh-CN'
+const ok = i18n.setLang('en')      // true 成功，false 不支持
+```
+
+### 构建消息
+
+```ts
+const msg = i18n.buildMsg('validate-err-max', '7')
+// zh-CN: "7 以下である必要があります" → 实际看当前语言
+```
+
+`buildMsg(key, ...args)` 中 `key` 有类型约束（`I18nMsgs`），模板中用 `{}` 占位，按顺序替换。
+
+### 支持的语言标签检测
+
+```ts
+const supported = i18n.getSupportedLanguageTags('zh-CN', 'xx', 'ja')
+// ['zh-CN', 'ja']  — 过滤掉不支持的
+```
+
+---
+
+## 内置语言
+
+| 语言标签 | 语言         |
+| :------- | :----------- |
+| en       | 英语（默认） |
+| zh-CN    | 简体中文     |
+| zh-TW    | 繁体中文     |
+| zh-HK    | 香港繁体     |
+| ja       | 日语         |
+| ko       | 韩语         |
+| ru       | 俄语         |
+| es       | 西班牙语     |
+| de       | 德语         |
+| fr       | 法语         |
+| ar       | 阿拉伯语     |
+| pt       | 葡萄牙语     |
+
+---
+
+## 语言匹配规则
+
+`setLang` 的匹配逻辑（实现在 `findMsgsByLang`）：
+
+1. 解析语言标签为 `{lang, region}`
+2. 查 `lang` 下的 region → 精确匹配 region
+3. 未命中查默认区域 `-`
+4. 仍未命中取该语言下第一个 region
+5. 全部未命中返回 `undefined`，`setLang` 返回 `false`，语言不变
+
+**注意**：匹配失败不会回退到英文默认语言，而是保持原有语言不变。
+
+---
+
+## 配置新语言
+
+如果需要的语言未内置，通过 `setMsgs` 添加消息模板后即可切换：
+
+```ts
+i18n.setMsgs('ja', {
+  'validate-err-array': '値が配列ではありません',
+  'validate-err-max': '{} 以下である必要があります',
+  'validate-err-min': '{} 以上である必要があります',
+  'validate-err-empty': '空であってはいけません',
+  'validate-err-string': '値が文字列のタイプではありません',
+  // ... 其他 key 来自 I18nMsgs
+})
+i18n.setLang('ja')
+```
+
+---
+
+## 扩展业务国际化内容
+
+通过 `extend` 创建独立的 i18n 对象，与全局 i18n 自动保持语言同步：
+
+```ts
+interface ExtMsgs { hello: string; world: string }
+
+const extI18n = i18n.extend<ExtMsgs>({ hello: 'hello', world: 'world' })
+extI18n.setMsgs('zh-CN', { hello: '你好', world: '世界' })
+
+i18n.setLang('zh-CN')
+extI18n.buildMsg('hello')  // "你好"
+```
+
+**约束**：所有消息模板 value 必须是 `string`，模板支持 `{}` 占位。扩展对象的 `setLang` 会自动被全局 i18n 的 `setLang` 同步调用（`ExtensibleI18n` 覆写了 `setLang`，遍历 `extendedI18ns` 逐个同步）。
+
+---
+
+## 绑定语言 — 解决异步串扰
+
+由于全局 i18n 共享，请求 A 切换语言后执行异步操作，请求 B 可能在此期间切换语言，导致 A 的消息构建语言错误。解决方案：
+
+### bindByRequest — 根据请求头绑定
+
+```ts
+async function handleReq(exchange: RouterExchange): Promise<void> {
+  const boundI18n = extI18n.bindByRequest(exchange.headers)
+  await query1()
+  await query2()
+  const hello = boundI18n.buildMsg('hello')  // 语言固定，不受其他请求影响
+}
+```
+
+解析 `accept-language` 头，取第一个支持的语言，生成 `BoundI18n`。`BoundI18n` 没有 `setLang` 方法，语言不可变。
+
+### bindLang — 手动绑定
+
+```ts
+const bound = i18n.bindLang('zh-CN')   // 绑定指定语言
+const bound2 = i18n.bindLang()          // 绑定当前语言
+bound.buildMsg('validate-err-empty')
+```
+
+`bindLang` 不传参时绑定当前语言，传参且语言不支持时抛出 `Error`。
+
+### switchByRequest — 直接切换
+
+```ts
+i18n.switchByRequest(exchange.headers)
+```
+
+根据 `accept-language` 直接切换全局语言（不创建绑定对象）。适合没有异步串扰风险的场景。
+
+---
+
+## 无国际化需求时固定中文
+
+在 import 框架之前设置：
+
+```ts
+process.env.LANG = 'zh-CN'
+import { startWebServer } from 'wok-server'
+```
+
+或者在容器中设置 `LANG=zh-CN` 环境变量。
+
+---
+
+## 内部实现要点
+
+### 类层次
+
+```
+I18n<T>                    — 核心类：setLang/getLang/buildMsg/bindLang/bindByRequest/switchByRequest
+  └── ExtensibleI18n<T>    — 增加 extend 方法，覆写 setLang 同步扩展子对象
+BoundI18n<T>               — 轻量只读绑定对象，仅 getLang/buildMsg
+```
+
+### 消息存储结构
+
+`msgsMap: Map<lang, Map<region, T>>`。两层 Map：第一层 key 为语言（`en`），第二层 key 为地区（`us` 或 `-` 表示默认）。全小写存储。
+
+### 语言标签解析 (`tag.ts`)
+
+仅支持 `语言-地区` 格式（如 `zh-CN`），不支持完整 BCP 47。统一转小写后匹配。
+
+### 初始化 (`index.ts`)
+
+`getI18n()` 首次调用：创建 `ExtensibleI18n(enUS)` → 注册 11 种语言（不含默认 en）→ 根据 `LANG`/`LC_CTYPE` 环境变量自动切换语言。

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

@@ -0,0 +1,144 @@
+---
+name: wok-server-lock
+description: wok-server 锁组件使用指南，协调并发请求中的异步操作，防止数据竞争。
+license: MIT
+metadata:
+  author: Peak Tai
+  email: peaktai@qq.com
+---
+
+# wok-server 锁组件
+
+## 概述
+
+锁组件基于内存实现简单的异步并发控制，用于将不确定顺序、有冲突的异步操作按顺序执行。典型场景：减库存、抽奖等并发修改操作。
+
+**注意**：这是进程内锁，只能协调单进程内的异步流程。如果需要分布式锁，应使用外部方案（如 Redis）。
+
+## 源码与类型定义
+
+安装 `wok-server` 后，可通过以下路径查看源码与类型定义：
+
+- 源码目录：`node_modules/wok-server/src/lock/`
+- 类型定义：`node_modules/wok-server/types/` （引用 lock 组件的 `.d.ts` 文件）
+
+核心源码文件：
+
+| 文件            | 说明                               |
+| :-------------- | :--------------------------------- |
+| `index.ts`      | `ServerLockManager`、`getLockManager` |
+
+---
+
+## 使用
+
+```ts
+import { getLockManager } from 'wok-server'
+
+const lockManager = getLockManager()
+```
+
+`getLockManager()` 返回全局单例 `ServerLockManager`。
+
+---
+
+## tryLock — 竞争锁
+
+```ts
+function tryLock(opts: {
+  key: string
+  run: () => Promise<void>
+  waitSeconds?: number
+  expiresInSeconds?: number
+}): Promise<boolean>
+```
+
+| 参数               | 说明                                                                 |
+| :----------------- | :------------------------------------------------------------------- |
+| `key`              | 锁标识，相同 key 产生竞争关系，排队执行                               |
+| `run`              | 获取锁成功后执行的异步函数                                            |
+| `waitSeconds`      | 等待秒数（可选），不设置或 ≤0 则获取不到立即返回 `false`              |
+| `expiresInSeconds` | 锁过期时间（秒），默认 60。防止持有者异常退出导致死锁                  |
+
+返回值 `boolean`：`true` 表示成功获取锁并执行完毕，`false` 表示等待超时未获取到锁。
+
+---
+
+## 完整示例
+
+```ts
+import { createJsonHandler, getLockManager, notBlank, notNull, min, max } from 'wok-server'
+
+interface Form {
+  id: string
+  quantity: number
+}
+
+createJsonHandler<Form>({
+  validation: {
+    id: [notBlank()],
+    quantity: [notNull(), min(1), max(10)]
+  },
+  async handle(body) {
+    const lock = getLockManager()
+    const acquired = await lock.tryLock({
+      key: `reduce-quantity-${body.id}`,
+      waitSeconds: 2,
+      expiresInSeconds: 600,
+      async run() {
+        const product = await findProductById(body.id)
+        if (product.quantity < body.quantity) {
+          throw new BusinessException('库存不足')
+        }
+        await reduceQuantity(body.id, body.quantity)
+      }
+    })
+    if (!acquired) {
+      throw new BusinessException('系统繁忙，请稍后重试')
+    }
+  }
+})
+```
+
+---
+
+## 内部实现要点
+
+### 锁结构
+
+```ts
+interface LockInfo {
+  value: string    // 随机 UUID，验证锁归属
+  expiresAt: number // 过期时间戳（ms）
+}
+```
+
+底层为 `Map<string, LockInfo>`，`key` 是锁标识，`value` 是随机值 + 过期时间。
+
+### 竞争流程
+
+`tryLock` → `waitLock`（循环尝试获取锁）：
+
+1. 检查 `lockMap` 中是否存在对应 key
+2. 不存在或已过期 → `lockMap.set(key, { value, expiresAt })` → 获取成功
+3. 存在且未过期 → 等待一次 `setTimeout(0)`（让出事件循环）→ 继续循环
+4. 超时 `waitSeconds` → 返回 `false`
+
+### 锁释放
+
+`run()` 执行完（成功或抛异常）后，在 `finally` 中验证 `value` 一致后 `delete(key)` 释放锁。
+
+### 死锁防护
+
+- **过期机制**：每个锁有 `expiresAt`，到期后其他竞争者可以覆盖获取
+- **定期清理**：`ServerLockManager` 构造时启动 10 秒间隔的过期锁清理，防止 `lockMap` 内存泄漏
+
+### sleep 实现
+
+```ts
+private sleep() {
+  return new Promise<void>(resolve => setTimeout(resolve, 0))
+}
+```
+
+通过 `setTimeout(0)` 让出事件循环，给其他异步操作（包括锁持有者的 `run()` 执行和释放）创造执行机会。

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

@@ -0,0 +1,218 @@
+---
+name: wok-server-log
+description: wok-server 日志组件使用指南，支持级别控制、文件输出、自定义存储和结构化日志。
+license: MIT
+metadata:
+  author: Peak Tai
+  email: peaktai@qq.com
+---
+
+# wok-server 日志组件
+
+## 概述
+
+日志组件提供日志记录能力，支持级别过滤、控制台输出、文件写入、自定义存储、日志前缀、JSON/文本双格式。
+
+## 源码与类型定义
+
+安装 `wok-server` 后，可通过以下路径查看源码与类型定义：
+
+- 源码目录：`node_modules/wok-server/src/log/`
+- 类型定义：`node_modules/wok-server/types/` （引用 log 组件的 `.d.ts` 文件）
+
+核心源码文件：
+
+| 文件            | 说明                               |
+| :-------------- | :--------------------------------- |
+| `index.ts`      | 模块入口，`Logger` 类与 `getLogger` |
+| `log.ts`        | `Log` 结构定义、`formatLogText`/`formatLogJson` |
+| `config.ts`     | 日志配置（环境变量映射）            |
+| `level.ts`      | `LogLevel` 枚举与解析              |
+| `file.ts`       | 文件存储实现，缓冲写入 + 定时清理    |
+| `store.ts`      | 自定义存储接口，`setLogStore`       |
+| `date.ts`       | 日期时间格式化                      |
+
+---
+
+## 环境变量
+
+| 环境变量          | 默认值 | 说明                                           |
+| :---------------- | :----- | :--------------------------------------------- |
+| `LOG_LEVEL`       | INFO   | 日志级别：DEBUG / INFO / WARN / ERROR           |
+| `LOG_FILE`        | false  | 是否输出到文件                                  |
+| `LOG_FILE_DIR`    | logs   | 日志文件目录（支持相对路径和绝对路径）           |
+| `LOG_FILE_MAX_DAYS` | 30   | 日志文件最大保留天数                             |
+| `LOG_CONSOLE`     | true   | 是否输出到控制台                                |
+| `LOG_FORMAT`      | text   | 输出格式：text 或 json（控制台强制 text）       |
+
+---
+
+## 获取日志对象
+
+```ts
+import { getLogger } from 'wok-server'
+
+const logger = getLogger()
+const moduleLogger = getLogger('my-module')  // 带前缀
+```
+
+`getLogger()` 无参时返回模块级默认单例 `Logger`（共享），传 prefix 时每次返回新实例。prefix 会在每条日志中显示为 `[INFO][my-module]日志内容`。
+
+---
+
+## 日志输出
+
+### 基本方法
+
+```ts
+logger.debug('调试信息')
+logger.info('普通信息')
+logger.warn('警告信息')
+logger.warning('警告信息')      // 同 warn
+logger.error('错误信息', new Error('details'))
+```
+
+### 级别判定（避免不必要的开销）
+
+```ts
+logger.isDebugEnabled()         // 是否 DEBUG 级别可用
+logger.isInfoEnabled()
+logger.isWarnEnabled()
+logger.isErrorEnabled()
+
+if (logger.isDebugEnabled()) {
+  logger.debug(`复杂构建: ${JSON.stringify(largeObj)}`)
+}
+```
+
+---
+
+## 日志格式
+
+### text 格式
+
+```
+[2025/05/13 14:30:22.456][INFO][my-module]日志内容
+```
+
+错误信息附带 stack trace（如果有），以换行拼接。
+
+### json 格式
+
+```json
+{"level":2,"content":"日志内容","time":"2025-05-13T06:30:22.456Z","prefix":"my-module"}
+```
+
+`LOG_FORMAT=json` 启用。注意控制台强制输出 text 格式，json 仅对文件有效。
+
+---
+
+## 文件日志
+
+### 启用
+
+```bash
+LOG_FILE=true
+LOG_FILE_DIR=logs
+LOG_FILE_MAX_DAYS=30
+```
+
+模块加载时，若 `LOG_FILE=true` 则自动将 `fileStore` 注册为日志存储。
+
+### 写入机制
+
+- **缓冲写入**：日志先进入内存队列 `LOG_QUEUE`，延迟 100ms 批量写出，避免频繁 IO
+- **超限立即写入**：队列超过 1024 条时立即写入，防止内存溢出
+- **按日期分文件**：每天一个文件，文件名格式 `YYYYMMDD.log`
+- **自动清理**：启动后每 24 小时检查并删除超过 `LOG_FILE_MAX_DAYS` 天的文件（基于文件 mtime）
+
+### 手动 flush
+
+```ts
+import { flushLogsToFile } from 'wok-server'
+
+// 进程退出前确保缓冲日志落盘
+process.on('beforeExit', async () => {
+  await flushLogsToFile()
+})
+```
+
+---
+
+## 自定义存储
+
+通过 `setLogStore` 替换默认的文件存储，可将日志发送到消息队列、外部系统等：
+
+```ts
+import { setLogStore } from 'wok-server'
+
+setLogStore((log: Log, config: LogConfig) => {
+  // log.time   — Date，日志时间
+  // log.level  — LogLevel，级别枚举
+  // log.content — string，日志正文
+  // log.error  — any，可选的异常对象
+  // log.prefix — string | undefined，可选的模块前缀
+  messageQueue.push(log)
+})
+```
+
+一旦设置 `setLogStore`，文件存储会被覆盖（即使 `LOG_FILE=true`），两者不可共存。
+
+---
+
+## Log 结构
+
+```ts
+interface Log {
+  time: Date        // 日志时间
+  level: LogLevel   // 级别枚举（DEBUG=1, INFO=2, WARN=3, ERROR=4）
+  content: string   // 日志正文
+  error?: any       // 可选，关联的异常对象
+  prefix?: string   // 可选，模块前缀
+}
+```
+
+## LogLevel 枚举
+
+```ts
+enum LogLevel {
+  DEBUG = 1,
+  INFO = 2,
+  WARN = 3,
+  ERROR = 4
+}
+```
+
+`parseLogLevel('INFO')` 将字符串转为枚举值，不支持的字符串抛 `Error`。
+
+---
+
+## 内部实现要点
+
+### Logger 类 (`index.ts`)
+
+```ts
+class Logger {
+  constructor(private prefix?: string) {}
+  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) { /* 控制台输出，强制 text 格式 */ }
+    const store = getLogStore()
+    if (store) store(log, config)                       // 自定义存储
+  }
+}
+```
+
+无 prefix 时使用模块级 defaultLogger 单例，有 prefix 时创建新实例。
+
+### 配置 (`config.ts`)
+
+通过 `registerConfig` 映射环境变量，`level` 在配置阶段通过 `parseLogLevel` 转换为 `LogLevel` 枚举值，`fileDir` 转换为绝对路径。最终配置通过 `Object.freeze` 冻结。
+
+### 文件存储 (`file.ts`)
+
+- 延迟批量写入（100ms 定时器）
+- 队列上限 1024 触发立即写入
+- 按日期分组写入不同文件
+- 24 小时清理周期，基于文件 mtime 判断过期