wok-server 0.5.0 → 0.6.0

package/skills/wok-server-http-client/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: wok-server-http-client
+description: wok-server HTTP 客户端组件使用指南，基于 Node.js 内置 http/https 模块封装的请求工具。
+license: MIT
+metadata:
+  author: Peak Tai
+  email: peaktai@qq.com
+---
+
+# wok-server HTTP 客户端
+
+## 概述
+
+HTTP 客户端基于 Node.js 内置 `http` 和 `https` 模块封装，提供三个函数：`doRequest`（通用请求）、`postJson`（JSON 响应 POST）、`getJson`（JSON 响应 GET）。支持自动 HTTPS、重定向跟随、超时控制。
+
+## 源码与类型定义
+
+安装 `wok-server` 后，可通过以下路径查看源码与类型定义：
+
+- 源码目录：`node_modules/wok-server/src/http-client/`
+- 类型定义：`node_modules/wok-server/types/` （引用 http-client 组件的 `.d.ts` 文件）
+
+核心源码文件：
+
+| 文件            | 说明                               |
+| :-------------- | :--------------------------------- |
+| `index.ts`      | `doRequest`、`postJson`、`getJson`  |
+
+---
+
+## 三个函数
+
+| 函数        | 作用                                   |
+| :---------- | :------------------------------------- |
+| `doRequest` | 通用 HTTP 请求，自定义所有选项          |
+| `postJson`  | POST 请求 + JSON 响应，自动序列化 body  |
+| `getJson`   | GET 请求 + JSON 响应，默认跟随重定向    |
+
+---
+
+## getJson — GET JSON 请求
+
+```ts
+function getJson<T>(
+  opts: { url: string; query?: Record<string, string[] | string>; headers?: IncomingHttpHeaders; timeout?: number }
+): Promise<T>
+```
+
+- 自动跟随重定向（`followRedirect: true`）
+- 状态码非 200 抛异常（含响应体前 1024 字节）
+- 空响应体返回 `{}`
+
+```ts
+import { getJson } from 'wok-server'
+
+const list = await getJson<User[]>({
+  url: 'https://api.example.com/users',
+  query: { status: 'active' },
+  headers: { 'Authorization': 'Bearer xxx' },
+  timeout: 3000
+})
+```
+
+---
+
+## postJson — POST JSON 请求
+
+```ts
+function postJson<T>(
+  opts: { url: string; body: any; query?: Record<string, string[] | string>; headers?: IncomingHttpHeaders; timeout?: number }
+): Promise<T>
+```
+
+- 自动设置 `Content-Type: application/json; charset=utf-8`
+- 自动将 `body` 序列化为 JSON 字符串
+- 不跟随重定向（`followRedirect: false`）
+- 状态码非 200 抛异常
+
+```ts
+import { postJson } from 'wok-server'
+
+const res = await postJson<{ id: string }>({
+  url: 'https://api.example.com/users',
+  body: { name: 'jack', age: 33 },
+  timeout: 5000
+})
+```
+
+---
+
+## doRequest — 通用请求
+
+```ts
+function doRequest(opts: HttpRequestOpts): Promise<HttpResponseInfo>
+```
+
+完整选项：
+
+| 选项             | 类型                                              | 说明                                   |
+| :--------------- | :------------------------------------------------ | :------------------------------------- |
+| `url`            | `string`                                          | 请求地址（支持 `http://` 和 `https://`） |
+| `method`         | `GET \| POST \| PUT \| DELETE \| ...`             | 请求方法                               |
+| `body`           | `string \| Buffer`                                | 请求正文（可选）                       |
+| `query`          | `Record<string, string \| string[]>`              | 查询参数，自动拼接 URL（可选）         |
+| `headers`        | `IncomingHttpHeaders`                             | 自定义消息头（可选）                   |
+| `timeout`        | `number`                                          | 超时时间（ms），默认 5000              |
+| `followRedirect` | `boolean`                                         | 是否跟随重定向（301/302/303/307/308）  |
+
+返回值 `HttpResponseInfo`：
+
+```ts
+interface HttpResponseInfo {
+  status: number
+  headers: IncomingHttpHeaders
+  body: Buffer
+}
+```
+
+示例：
+
+```ts
+import { doRequest } from 'wok-server'
+
+// DELETE 请求
+const res = await doRequest({
+  url: 'https://api.example.com/users/001',
+  method: 'DELETE',
+  timeout: 5000
+})
+
+// 带查询参数
+const res2 = await doRequest({
+  url: 'https://api.example.com/search',
+  method: 'GET',
+  query: { keyword: 'test', tags: ['a', 'b'] }
+})
+
+// 跟随重定向
+const res3 = await doRequest({
+  url: 'https://short.link/abc',
+  method: 'GET',
+  followRedirect: true
+})
+```
+
+---
+
+## 内部实现要点
+
+### URL 解析
+
+使用 Node.js 内置 `URL` 类解析，根据 `protocol` 自动选择 `http.request` 或 `https.request`。`query` 通过 `url.searchParams.append` 拼接（支持 `string` 和 `string[]`）。
+
+### 重定向
+
+`doRequest` 中检测 301/302/303/307/308 状态码时，取 `location` 头作为新 URL 递归调用。递归只进行一次（二次请求强制 `followRedirect: false`），防止死循环。
+
+### 超时
+
+通过 `req.on('timeout', ...)` 处理超时，timeout 默认为 5000ms。也可以传入自定义值，`<=0` 视为无效使用默认值。
+
+### HTTPS
+
+`rejectUnauthorized: false`，不验证服务端证书，适用于自签名证书场景。

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()` 执行和释放）创造执行机会。