wok-server 0.4.13 → 0.6.0

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

@@ -0,0 +1,200 @@
+---
+name: wok-server-config
+description: wok-server 配置组件使用指南，将配置对象与环境变量映射，支持类型转换和校验。
+license: MIT
+metadata:
+  author: Peak Tai
+  email: peaktai@qq.com
+---
+
+# wok-server 配置组件
+
+## 概述
+
+配置组件将配置对象与环境变量映射，并提供给其他模块使用。结合校验组件可实现配置的合法性校验。
+
+配置对象的属性仅支持三种类型：`string`、`number`、`boolean`。
+
+提供三个函数：`registerConfig`、`getConfig`、`generateConfig`。
+
+## 源码与类型定义
+
+安装 `wok-server` 后，可通过以下路径查看源码与类型定义：
+
+- 源码目录：`node_modules/wok-server/src/config/`
+- 类型定义：`node_modules/wok-server/types/` （引用 config 组件的 `.d.ts` 文件）
+
+核心源码文件：
+
+| 文件            | 说明                               |
+| :-------------- | :--------------------------------- |
+| `index.ts`      | 模块入口，导出三个配置函数          |
+| `convert.ts`    | 环境变量值类型转换逻辑              |
+| `exception.ts`  | `ConfigException` 异常类            |
+
+---
+
+## 配置类型与映射规则
+
+### 类型要求
+
+> **⚠️ 重要：配置类型的所有属性绝对不可为空（不能是 `undefined`）。**
+
+配置组件在**运行时**通过 `for...in` 遍历 `defaultConfig` 的属性来匹配环境变量，如果某个属性的值为 `undefined`，该属性的类型将无法判断（`typeof undefined` 为 `"undefined"`），导致 `convert` 抛出 `ConfigException`。
+
+以下写法在真实开发中是不允许的，非常容易出现 bug：
+
+```ts
+// ❌ 错误：属性可空
+interface XxxConfig {
+  name?: string
+}
+// 如果 defaultConfig 初始化时 name 的值为 undefined，运行时匹配会失败
+```
+
+正确做法是所有属性保持必填并给出有意义的默认值：
+
+```ts
+// ✅ 正确：属性必填，必须有默认值
+interface XxxConfig {
+  name: string
+}
+```
+
+配置对象的属性仅支持三种类型：
+
+| TypeScript 类型 | 环境变量值转换方式                       |
+| :-------------- | :--------------------------------------- |
+| `string`        | 直接使用字符串值                         |
+| `number`        | 通过 `parseFloat` 转换，NaN 则抛异常      |
+| `boolean`       | `'true'` → true, `'false'` → false，其他抛异常 |
+
+### 环境变量名映射
+
+环境变量名 = `前缀(大写)_属性名转换(大写)`。属性名中的大写字母前会插入下划线。
+
+例如：前缀 `custom`，属性 `appId` → 环境变量 `CUSTOM_APP_ID`。
+
+每次调用 `registerConfig` 或 `generateConfig` 都会输出日志，包含前缀、环境变量名、当前值、映射属性名，便于调试。
+
+---
+
+## registerConfig — 注册配置（推荐）
+
+```ts
+function registerConfig<T extends {}>(
+  defaultConfig: T,
+  envPrefix: string,
+  validation?: ValidationOpts<T>
+): T
+```
+
+- `defaultConfig`：默认配置对象，**所有属性必须有值（不能为 `undefined`）**。运行时通过遍历该对象的属性来匹配环境变量，属性值为 `undefined` 会导致类型无法识别而抛出异常
+- `envPrefix`：环境变量前缀
+- `validation`：可选的校验规则
+- 返回映射后的配置对象
+
+**特点**：同一前缀只能注册一次，重复注册会抛出 `ConfigException`。推荐将返回的配置对象导出供其他模块使用。
+
+```ts
+import { registerConfig, notBlank, notNull, min, max } from 'wok-server'
+
+interface CustomConfig {
+  appId: string
+  appSecret: string
+  ssl: boolean
+  timeout: number
+}
+
+const config = registerConfig<CustomConfig>(
+  { appId: '', appSecret: '', ssl: true, timeout: 5000 },
+  'custom',
+  {
+    appId: [notBlank()],
+    appSecret: [notBlank()],
+    timeout: [notNull(), min(1000), max(3600)]
+  }
+)
+```
+
+也可以不显式定义类型，让 TypeScript 自动推断：
+
+```ts
+const config = registerConfig(
+  { url: 'http://localhost/api', account: 'Jack' },
+  'c2',
+  { url: [notBlank()] }
+)
+```
+
+---
+
+## generateConfig — 生成配置（可重复）
+
+```ts
+function generateConfig<T extends {}>(
+  defaultConfig: T,
+  envPrefix: string,
+  validation?: ValidationOpts<T>
+): T
+```
+
+参数与 `registerConfig` 完全一致。区别在于 `generateConfig` **不注册**，可多次调用，适合以下场景：
+- 运行时更改环境变量后重新生成配置
+- 测试中模拟不同环境
+- 其他需要动态生成配置的特殊需求
+
+```ts
+const config1 = generateConfig(defaults, 'myapp')
+// 修改环境变量后
+process.env.MYAPP_TIMEOUT = '8000'
+const config2 = generateConfig(defaults, 'myapp')
+```
+
+---
+
+## getConfig — 获取已注册配置
+
+```ts
+function getConfig<T>(envPrefix: string): T | undefined
+```
+
+通过前缀获取已注册的配置对象。一般不需要使用，推荐在 `registerConfig` 调用后直接导出返回的配置对象。
+
+```ts
+const config = getConfig<CustomConfig>('custom')
+```
+
+---
+
+## 内部实现要点
+
+### 类型转换 (`convert.ts`)
+
+```ts
+function convert(val: string, defaultVal: any): string | number | boolean
+```
+
+- 根据 `defaultVal` 的类型决定转换策略
+- `string`：直接返回原值
+- `number`：`parseFloat` 转换，失败抛出 `ConfigException`
+- `boolean`：仅接受 `'true'` / `'false'`，大小写敏感
+- 其他类型不支持，抛出 `ConfigException`
+
+### 环境变量名构建
+
+```ts
+function buildEnvName(envPrefix: string, propName: string): string
+```
+
+将驼峰属性名转换为下划线大写格式：
+- `appId` → `APP_ID`
+- 前缀 `custom` + `appId` → `CUSTOM_APP_ID`
+
+### 全局注册表
+
+`registerConfig` 内部维护一个 `configEnvMap`（`Map<string, any>`），以前缀为 key 存储配置。重复注册相同前缀直接抛异常，保证配置唯一性。
+
+### 模块初始化
+
+模块顶层调用 `dotenv` 的 `config()` 加载 `.env` 文件，确保环境变量在配置映射前已就绪。

package/skills/wok-server-getting-started/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: wok-server-getting-started
+description: 介绍 wok-server 的入门指南，包括项目创建、手动安装、最简使用、使用路由等。
+license: MIT
+metadata:
+  author: Peak Tai
+  email: peaktai@qq.com
+---
+
+# wok-server 入门指南
+
+wok-server 是一个简洁易用的 Node.js 后端开发框架，使用 TypeScript 开发，有完整的类型约束和定义，注释详细，文档齐全，支持国际化。
+
+主要功能：配置，日志，国际化，校验，缓存，MVC，MySQL，MongoDB，周期任务。
+
+## 创建项目
+
+推荐通过脚手架创建一个结构完整的项目：
+
+```bash
+npm create wok-server
+```
+
+创建的项目结构与[工程化文档](./references/engineering.md)推荐的目录结构一致（按功能划分，而非传统的按层划分），细节可参考该文档。
+
+## 手动安装
+
+```bash
+npm i wok-server --save
+```
+
+## 最简示例
+
+入口文件 `main.ts`：
+
+```ts
+import { startWebServer } from 'wok-server'
+
+startWebServer({
+  routers: {
+    '/': async exchange => exchange.respondText('Hello world !')
+  }
+}).catch(e => {
+  console.error('Start server failed', e)
+})
+```
+
+运行后访问 `http://localhost:8080` 将输出 "Hello world !"。
+
+相关设置可通过环境变量来修改，比如 `SERVER_PORT` 设置端口号。
+
+## 路由与拦截器
+
+```ts
+import { startWebServer } from 'wok-server'
+
+await startWebServer({
+  routers: {
+    '/': async exchange => exchange.respondJson({ ok: true }),
+    '/users': async exchange => {
+      const list = await listUser()
+      exchange.respondJson(list)
+    }
+  },
+  interceptors: [
+    async (exchange, next) => {
+      try {
+        await next()
+      } catch (e) {
+        exchange.respondErrMsg('服务器错误', 500)
+      }
+    }
+  ]
+})
+```
+
+## JSON 请求处理
+
+使用 `createJsonHandler` 快速创建 JSON 格式接口，自动完成请求解析、校验、响应序列化：
+
+```ts
+import { createJsonHandler, notBlank, length } from 'wok-server'
+
+interface Form {
+  code: string
+  nickname: string
+}
+
+export const createUser = createJsonHandler<Form, { id: string }>({
+  validation: {
+    code: [notBlank(), length({ max: 64 })],
+    nickname: [notBlank(), length({ max: 64 })]
+  },
+  async handle(body) {
+    const newUser = await createUserInDb(body)
+    return { id: newUser.id }
+  }
+})
+```
+
+## 数据库操作（MySQL 为例）
+
+```ts
+import { enableMysql, getMysqlManager, Table } from 'wok-server'
+
+await enableMysql()
+
+export interface User {
+  id: string
+  nickname: string
+}
+
+export const tableUser: Table<User> = {
+  tableName: 'user',
+  id: 'id',
+  columns: ['nickname']
+}
+
+const manager = getMysqlManager()
+const user = await manager.findById(tableUser, '001')
+```
+
+数据库组件也支持 MongoDB，用法类似。

package/skills/wok-server-getting-started/references/engineering.md

@@ -0,0 +1,169 @@
+# 工程化实践
+
+当程序规模变大后，需要对代码文件进行合理组织。
+
+## 目录结构
+
+推荐按功能划分目录，而非传统的按层（service 层、controller 层）划分，这样相关性高的文件放在一起，查找更方便，也更利于封装。
+
+假设有用户（user）和标签（tag）两个业务功能，项目大致结构如下：
+
+```
+根目录
+  ├── db_migration/          # MySQL 数据库迁移文件
+  ├── src/
+  │   ├── auth/              # 授权业务
+  │   │   ├── auth.ts               # 实体配置
+  │   │   ├── auth-interceptor.ts   # 授权拦截器
+  │   │   ├── create-auth.ts        # 创建授权接口
+  │   │   ├── ccu-task.ts           # 在线人数统计任务
+  │   │   └── index.ts              # 包入口，导出模块
+  │   ├── user/              # 用户业务
+  │   │   ├── user.ts               # 实体配置
+  │   │   ├── create-user.ts        # 创建用户接口
+  │   │   ├── delete-user.ts        # 删除用户接口
+  │   │   ├── update-user.ts        # 更新用户接口
+  │   │   └── index.ts
+  │   ├── tag/               # 标签业务
+  │   │   ├── tag.ts                # 实体配置
+  │   │   ├── create-tag.ts         # 创建标签接口
+  │   │   ├── delete-tag.ts         # 删除标签接口
+  │   │   └── index.ts
+  │   ├── exception.ts       # 全局异常与异常拦截器
+  │   ├── router.ts          # 全局路由配置，规模较大的项目，需要将路由配置单独放到一个文件中，或者创建一个单独的目录
+  │   └── main.ts            # 入口文件，启动服务，配置路由
+  ├── .env                    # 开发环境变量配置
+  ├── package.json
+  └── tsconfig.json
+```
+
+## 核心原则
+
+1. **按功能划分目录**，相关性高的文件放在一起
+2. **每个接口单独一个文件**，仅导出处理函数
+3. **路由配置集中管理**，不可分散到各业务目录
+4. **通过异常中断处理流程**，由拦截器统一响应
+
+## 异常处理
+
+定义业务异常，在流程无法继续时抛出，由拦截器统一处理：
+
+```ts
+export class BusinessException {
+  constructor(
+    readonly message: string,
+    readonly status?: number
+  ) {}
+}
+
+export async function globalErrorInterceptor(
+  exchange: ServerExchange,
+  next: () => Promise<void>
+): Promise<void> {
+  try {
+    await next()
+  } catch (e) {
+    if (e instanceof BusinessException) {
+      exchange.respondErrMsg(e.message, e.status ?? 400)
+      return
+    }
+    if (e instanceof ValidationException) {
+      exchange.respondErrMsg(`${e.propertyPath}：${e.errMsg}`, 400)
+      return
+    }
+    throw e  // 框架默认响应 500
+  }
+}
+```
+
+## 入口文件示例
+
+```ts
+import { enableMysql, startWebServer, scheduleWithFixedDelay } from 'wok-server'
+import { createAuth, authInterceptor, ccuTask } from './auth'
+import { createUser, updateUser, deleteUser } from './user'
+import { createTag, deleteTag } from './tag'
+import { globalErrorInterceptor } from './exception'
+
+async function main() {
+  Date.prototype.toJSON = function () {
+    return this.getTime() as any
+  }
+
+  await enableMysql()
+
+  await startWebServer({
+    routers: {
+      '/auth/create': createAuth,
+      '/user/create': createUser,
+      '/user/update': updateUser,
+      '/user/delete': deleteUser,
+      '/tag/create': createTag,
+      '/tag/delete': deleteTag
+    },
+    interceptors: [globalErrorInterceptor, authInterceptor]
+  })
+
+  scheduleWithFixedDelay(60, 60, ccuTask)
+}
+
+main().catch(console.error)
+```
+
+## 实体与接口示例
+
+`user/user.ts` — 实体类型与表配置：
+
+```ts
+import { Table } from 'wok-server'
+
+export interface User {
+  id: string
+  code: string
+  nickname: string
+  pwd: string
+  status: 'ACTIVATED' | 'DISABLED'
+  create_at?: Date
+  update_at?: Date
+}
+
+export const tableUser: Table<User> = {
+  tableName: 'user',
+  id: 'id',
+  columns: ['code', 'nickname', 'pwd', 'status'],
+  createdDate: { type: 'date', column: 'create_at' },
+  updatedDate: { type: 'date', column: 'update_at' }
+}
+```
+
+`user/create-user.ts` — 接口处理：
+
+```ts
+import { createJsonHandler, getMysqlManager, notBlank, length } from 'wok-server'
+import { tableUser } from './user'
+
+interface Form {
+  code: string
+  nickname: string
+  pwd: string
+}
+interface Resp {
+  id: string
+}
+
+export const createUser = createJsonHandler<Form, Resp>({
+  validation: {
+    code: [notBlank(), length({ max: 64 })],
+    nickname: [notBlank(), length({ max: 64 })],
+    pwd: [notBlank(), length({ max: 20 })]
+  },
+  async handle(body) {
+    const manager = getMysqlManager()
+    if (await manager.existsBy(tableUser, { code: body.code })) {
+      throw new BusinessException('编号已存在')
+    }
+    const newUser = await manager.insert(tableUser, body)
+    return { id: newUser.id }
+  }
+})
+```

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`，不验证服务端证书，适用于自签名证书场景。