wok-server 0.5.0 → 0.7.0

package/skills/wok-server-code-navigation/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: wok-server-code-navigation
+description: 教你如何读懂一个 wok-server 项目的代码结构，快速定位目标文件。
+license: MIT
+metadata:
+  author: Peak Tai
+  email: peaktai@qq.com
+---
+
+# wok-server 项目代码导航
+
+## 概述
+
+面对一个 wok-server 项目时，按以下路径快速理解项目结构、定位目标代码。核心原则：**项目按功能划分目录，路由集中配置，每个接口/拦截器独立一个文件**。
+
+## 项目入口 — main.ts
+
+入口文件在 `src/main.ts`，包含：
+
+1. 全局初始化（如 `Date.prototype.toJSON`、`enableMysql()`）
+2. `startWebServer()` 调用，配置 routers 和 interceptors
+3. 任务调度（`scheduleWithFixedDelay` 等）
+
+**所以 `main.ts` 是读懂项目的第一个文件**。从这里可以看到所有路由映射和拦截器链。
+
+## 路由定位决策树
+
+```
+要找一个接口的处理逻辑？
+  → 打开 src/main.ts（或 src/router.ts）
+  → 找到路由对象中对应路径的 key
+  → 看它的 value（通常是 import 的 handler 函数）
+  → Ctrl/Cmd + 点击跳转到 handler 文件
+```
+
+路由集中在一个地方，所以**搜路由路径就能找到对应 handler 的 import**。
+
+## 文件定位速查表
+
+| 想找什么                 | 去哪里找                                                       |
+| ------------------------ | -------------------------------------------------------------- |
+| 入口、路由注册、启动逻辑 | `src/main.ts`                                                  |
+| 路由配置（大项目）       | `src/router.ts` 或 `src/router/` 目录                          |
+| 某个接口的处理逻辑       | `src/{功能名}/{接口名}.ts`（如 `src/user/create-user.ts`）     |
+| 拦截器                   | `src/{功能名}/{拦截器名}-interceptor.ts` 或 `src/exception.ts` |
+| 数据库实体与表定义       | `src/{功能名}/{功能名}.ts`（如 `user/user.ts`）                |
+| MySQL 迁移脚本           | `db_migration/` 目录                                           |
+| 环境变量                 | 项目根目录 `.env`                                              |
+
+## 目录结构速览
+
+```
+根目录
+  ├── db_migration/          # MySQL 迁移文件
+  ├── src/
+  │   ├── auth/              # 授权功能
+  │   │   ├── auth.ts               # 实体配置（表结构）
+  │   │   ├── auth-interceptor.ts   # 授权拦截器
+  │   │   ├── create-auth.ts        # 创建授权接口
+  │   │   └── index.ts              # 包入口，聚合导出
+  │   ├── user/              # 用户功能
+  │   │   ├── user.ts
+  │   │   ├── create-user.ts
+  │   │   └── index.ts
+  │   ├── exception.ts       # 全局异常定义 + 异常拦截器
+  │   ├── router.ts          # 路由集中配置（大项目）
+  │   └── main.ts            # 入口文件（小项目路由也在这里）
+  ├── .env
+  ├── package.json
+  └── tsconfig.json
+```
+
+## 阅读项目的步骤
+
+### 第一步：看 main.ts
+
+打开 `src/main.ts`，关注三个区域：
+
+1. **顶部 import** — 了解项目用了哪些 wok-server 功能模块（MySQL？MongoDB？Task？）
+2. **startWebServer() 调用** — 了解有哪些路由和拦截器
+3. **任务调度调用** — 了解有哪些定时任务
+
+### 第二步：看路由表
+
+从 `main.ts` 的 routers 对象中找到你关心的路径，跳转到对应 handler。
+
+### 第三步：看拦截器链
+
+从 `main.ts` 的 interceptors 数组了解请求处理流程。典型链路：
+
+```
+请求 → globalErrorInterceptor → authInterceptor → handler
+```
+
+### 第四步：按需看业务目录
+
+根据 handler 文件所在的目录，查看同目录下的：
+
+- `{功能}.ts` — 了解数据实体结构
+- `{功能}-interceptor.ts` — 了解功能级拦截逻辑
+- 其他 handler 文件 — 了解该功能的完整接口
+
+## 常见查找场景
+
+### 场景 1：我要改一个接口的逻辑
+
+1. 从路由路径反查 handler 文件（搜路径字符串）
+2. 打开 handler 文件，找到 `handle()` 函数体
+3. 修改逻辑
+
+### 场景 2：我要新增一个接口
+
+1. 在对应功能目录下新建 `xxx.ts`
+2. 用 `createJsonHandler` 或其他工厂函数创建 handler
+3. 在 `src/main.ts` 或 `src/router.ts` 中注册路由
+
+### 场景 3：我要查某个表的结构
+
+1. 找 `src/{功能名}/{功能名}.ts`（如 `user/user.ts`）
+2. 查看 `Table` 对象定义（表名、列、ID 字段等）
+
+### 场景 4：项目可能封装了自定义 Handler
+
+wok-server 内置的 handler 工厂函数（`createJsonHandler`、`createUploadHandler`、`createSseHandler`、`restful`）在真实项目中经常被二次封装。例如：
+
+```ts
+// 项目可能定义了 createAuthJsonHandler，在 createJsonHandler 基础上注入用户信息
+export function createAuthJsonHandler<Req, Resp>(opts) {
+  return createJsonHandler<Req, Resp>({
+    ...opts,
+    async handle(body, exchange) {
+      const auth = new Auth(exchange) // 增加 auth 信息
+      return opts.handle(body, exchange, auth)
+    }
+  })
+}
+```
+
+**面对一个项目时，先搜索以下关键词，判断项目是否有自定义封装：**
+
+- 搜 `createJsonHandler` —— 如果没有匹配，说明项目可能用了自定义封装
+- 搜 `create.*Handler` 或 `create.*Json` —— 发现自定义的 handler 工厂函数
+- 搜 `from 'wok-server'` 中的 `createJsonHandler` —— 确认哪些文件直接用了内置版本
+- 后续搜索接口文件时，用自定义函数名而非内置名
+
+### 场景 5：找不到目标文件？
+
+1. **首先检查路由注册** — 搜路由路径字符串，定位 handler 的 import 来源
+2. 全文搜索 `createJsonHandler` —— 列出直接使用内置工厂的 JSON 接口
+3. 全文搜索 `create.*Handler` —— 发现自定义封装的 handler 工厂及使用位置
+4. 全文搜索 `Table<` —— 列出所有数据表定义
+5. 全文搜索 `Interceptor` —— 列出所有拦截器
+6. 全文搜索 `schedule` —— 列出所有定时任务

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 }
+  }
+})
+```