wok-server 0.4.13 → 0.6.0

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

@@ -0,0 +1,235 @@
+---
+name: wok-server-mongodb
+description: wok-server MongoDB 组件使用指南，基于官方驱动封装，提供实体映射、CRUD、事务和版本管理。
+license: MIT
+metadata:
+  author: Peak Tai
+  email: peaktai@qq.com
+---
+
+# wok-server MongoDB 组件
+
+## 概述
+
+MongoDB 组件基于 [mongodb 官方驱动](https://www.npmjs.com/package/mongodb) 封装，提供实体映射和增删改查功能。支持多实例、事务、慢查询告警、版本管理。
+
+## 源码与类型定义
+
+安装 `wok-server` 后，可通过以下路径查看源码与类型定义：
+
+- 源码目录：`node_modules/wok-server/src/mongodb/`
+- 类型定义：`node_modules/wok-server/types/` （引用 mongodb 组件的 `.d.ts` 文件）
+
+核心源码文件：
+
+| 文件               | 说明                               |
+| :----------------- | :--------------------------------- |
+| `index.ts`         | 模块入口，`enableMongoDB`/`getMongoDBManager` |
+| `config.ts`        | 配置定义与默认值                    |
+| `collection.ts`    | `MongoCollection<T>` 集合映射接口   |
+| `doc.ts`           | `MongoDocId`、`MongoDocWithId<T>`  |
+| `manager/base.ts`  | `BaseMongoManager` 基类            |
+| `manager/index.ts` | `MongoDBManager`，含 `tx` 方法     |
+| `manager/tx.ts`    | `MongoTxSession` 事务会话          |
+| `manager/tx-strict.ts` | `MongoStrictTxSession` 严格事务 |
+| `migration.ts`     | 版本迁移                           |
+| `exception.ts`     | `MongoDBException` 异常类          |
+
+---
+
+## 环境变量
+
+| 环境变量                    | 说明                 | 默认值 |
+| :-------------------------- | :------------------- | :----- |
+| `MONGO_URI`                 | 连接地址             | -      |
+| `MONGO_MAX_POOL_SIZE`       | 连接池最大连接数     | 10     |
+| `MONGO_MIN_POOL_SIZE`       | 连接池最小连接数     | 1      |
+| `MONGO_MAX_CONNECTING`      | 最大并发连接数       | 10     |
+| `MONGO_MAX_IDLE_TIME_MS`    | 最大闲置时间（ms）   | 60000  |
+| `MONGO_WAIT_QUEUE_TIMEOUT_MS` | 等待连接超时（ms） | 60000  |
+| `MONGO_SLOW_QUERY_WARN`     | 慢查询警告           | true   |
+| `MONGO_SLOW_QUERY_MS`       | 慢查询阈值（ms）     | 200    |
+| `MONGO_TRANSACTION_TIMEOUT` | 事务超时（ms）       | 5000   |
+| `MONGO_TRANSACTION_STRICT`  | 事务严格模式         | true   |
+
+---
+
+## 初始化
+
+```ts
+import { enableMongoDB, getMongoDBManager } from 'wok-server'
+
+await enableMongoDB()
+const manager = getMongoDBManager()
+```
+
+### 多实例
+
+指定名称即可，环境变量前缀自动变更为该名称大写：
+
+```ts
+await enableMongoDB()                    // 默认，前缀 MONGO_
+await enableMongoDB({ name: 'md2' })    // 自定义，前缀 MD2_
+```
+
+---
+
+## 实体映射
+
+```ts
+import { MongoCollection } from 'wok-server'
+
+export interface User {
+  nickname: string
+  skills: string[]
+  createAt?: Date     // 可选，由组件自动管理
+  updateAt?: Date
+}
+
+export const collUser: MongoCollection<User> = {
+  collectionName: 'user',
+  createdDate: { type: 'date', field: 'createAt' },
+  updatedDate: { type: 'date', field: 'updateAt' }
+}
+```
+
+- 主键固定为 `_id`（`string | ObjectId`），不可自定义映射
+- 实体接口不要声明 `_id` 字段，插入时可传可省略（省略时数据库自动生成 ObjectId）
+- `createdDate`/`updatedDate` 配置后由组件自动填充
+
+---
+
+## CRUD 操作
+
+所有操作以 `MongoCollection<T>` 为第一个参数。
+
+### 插入
+
+```ts
+const result = await manager.insert(collUser, { _id: '007', nickname: 'Spark', skills: [] })
+```
+
+### 查询
+
+```ts
+const user = await manager.findById(collUser, '007')                    // 按 _id
+const list = await manager.findByIdIn(collUser, ['007', '008'])         // 批量 _id
+const jack = await manager.findFirst(collUser, { nickname: 'jack' })    // 第一条
+const all = await manager.findAll(collUser)                             // ⚠️ 全量，危险
+
+// 条件查询
+const results = await manager.find(collUser,
+  { skills: { $exists: true } },
+  { offset: 0, limit: 2 }
+)
+```
+
+查询条件使用 MongoDB 原生 Filter 语法（`{ nick: 'jack' }`, `{ $gt: ... }` 等）。
+
+### 分页
+
+```ts
+const page = await manager.paginate(collUser,
+  { skills: { $exists: true } },
+  { pn: 2, pz: 20, orderBy: ['_id', 'asc'] }
+)
+```
+
+### 更新（四种方法）
+
+| 方法            | 说明                               | 需要完整文档 |
+| :-------------- | :--------------------------------- | :----------- |
+| `update`        | 完整文档更新，失败抛异常           | 是           |
+| `partialUpdate` | 局部更新，只需 id + 更新字段       | 否           |
+| `updateMany`    | 批量更新所有符合条件的             | 否           |
+| `updateOne`     | 只更新一条相等条件的               | 否           |
+
+```ts
+// 完整更新
+const user = await manager.findById(collUser, '007')
+user.nickname = 'ryan'
+await manager.update(collUser, user)
+
+// 局部更新（MongoDB 更新操作符语法）
+await manager.partialUpdate(collUser, '001', { $set: { nickname: 'lily' } })
+
+// 批量更新
+await manager.updateMany(collUser, { credit: { $lte: 10 } }, { $inc: { credit: 1 } })
+```
+
+### 其他
+
+```ts
+await manager.existsById(collUser, 'xyz')
+await manager.existsBy(collUser, { nickname: 'smith' })
+await manager.deleteById(collUser, '007')
+await manager.deleteMany(collUser, { nickname: 'smith' })  // ⚠️ 危险
+const count = await manager.count(collUser, { nickname: 'Steve' })
+```
+
+---
+
+## 事务
+
+```ts
+await manager.tx(async session => {
+  await session.partialUpdate(collOrder, orderId, { $set: { status: 'finished' } })
+  await session.partialUpdate(collAccount, accountId, { $inc: { balance: -amount } })
+}, { timeout: 1000 })
+```
+
+**⚠️ 事务中的所有操作必须通过 `session` 完成**，直接使用 `manager` 不会在事务中生效。
+
+选项可覆盖全局超时时间，支持设置 `readConcern`、`writeConcern`、`readPreference`。
+
+### 严格模式
+
+`MONGO_TRANSACTION_STRICT=true`（默认），事务中禁止：
+1. 批量 `insertMany`
+2. 批量 `updateMany` / `deleteMany`
+3. 大批量查询 `find` / `count` / `paginate`
+4. `findByIdIn` 参数超过 100
+5. 任何操作累计超过 10 次
+
+---
+
+## 版本管理
+
+在 `enableMongoDB` 时传入 `migration.versionList`：
+
+```ts
+await enableMongoDB({
+  migration: {
+    versionList: [
+      async db => {                          // 版本 0
+        await db.createCollection('user')
+        await db.collection('user').createIndex({ nickname: 1 }, { unique: true })
+      },
+      async db => {                          // 版本 1
+        await db.collection('user').insertOne({ nickname: 'jack', ... })
+      }
+    ]
+  }
+})
+```
+
+- 版本号 = 数组下标，从 0 开始
+- **已有元素不可修改**，只能在末尾追加
+- 启动时自动检测当前版本（存储在 `db_version` 集合），执行未应用的版本
+- 迁移不能回滚，出错需手动在数据库中修复后重启
+
+---
+
+## 内部实现要点
+
+### 初始化
+
+`registerConfig` 注册配置 → 创建 `MongoClient` → 可选迁移 → 存入 `managerMap` → 进程退出前自动 `close()`。
+
+### 慢查询计时
+
+所有操作通过 `timingQuery` 包装，记录耗时，超出 `MONGO_SLOW_QUERY_MS` 时输出 WARN 日志（含操作类型、集合名、ID 等）。
+
+### 事务实现
+
+创建 `ClientSession` → `startTransaction` → `Promise.race` 超时竞速 → 根据 `transactionStrict` 创建普通/严格 session → `exec(session)` → `commit` / `abort` / `finally endSession`。

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

@@ -0,0 +1,251 @@
+---
+name: wok-server-mvc
+description: wok-server MVC 组件使用指南，基于 Node.js http 模块，提供路由、拦截器、JSON/上传处理器等。
+license: MIT
+metadata:
+  author: Peak Tai
+  email: peaktai@qq.com
+---
+
+# wok-server MVC 组件
+
+## 概述
+
+MVC 组件基于 Node.js 内置 `http` 模块封装，提供 HTTP 服务构建能力。核心概念：路由（Router）、拦截器（Interceptor）、处理器（Handler）。
+
+## 源码与类型定义
+
+安装 `wok-server` 后，可通过以下路径查看源码与类型定义：
+
+- 源码目录：`node_modules/wok-server/src/mvc/`
+- 类型定义：`node_modules/wok-server/types/` （引用 mvc 组件的 `.d.ts` 文件）
+
+核心源码文件：
+
+| 文件               | 说明                               |
+| :----------------- | :--------------------------------- |
+| `index.ts`         | 模块入口，`startWebServer`/`stopWebServer` |
+| `server.ts`        | `WokServer` 类，HTTP/HTTPS 服务实现 |
+| `router.ts`        | `RouterHandler` 类型与 `Routers` 定义 |
+| `exchange.ts`      | `ServerExchange` 数据交换对象       |
+| `config.ts`        | 服务配置（端口、超时、CORS、TLS 等）|
+| `interceptor.ts`   | `Interceptor` 拦截器接口            |
+| `handler/json.ts`  | `createJsonHandler` JSON 处理器     |
+| `handler/upload.ts`| `createUploadHandler` 二进制上传      |
+| `handler/sse.ts`   | `createSseHandler` SSE 服务端推送      |
+| `handler/restful.ts`| `restful` 方法分派函数             |
+| `handler/index.ts` | 处理器模块聚合导出                  |
+| `query.ts`         | `QueryString` 查询字符串解析        |
+| `static/`          | 静态文件服务                        |
+
+---
+
+## 环境变量
+
+| 环境变量                   | 说明                | 默认值 |
+| :------------------------- | :------------------ | :----- |
+| `SERVER_PORT`              | 端口号              | 8080   |
+| `SERVER_TIMEOUT`           | 超时时间（ms）      | 30000  |
+| `SERVER_ACCESS_LOG`        | 是否启用访问日志    | false  |
+| `SERVER_CORS_ALLOW_ORIGIN` | CORS 允许的源域名   | *      |
+| `SERVER_CORS_ALLOW_HEADERS`| CORS 允许的消息头   | *      |
+| `SERVER_CORS_ALLOW_METHODS`| CORS 允许的请求方法 | *      |
+
+---
+
+## 启动与停止
+
+```ts
+import { startWebServer, stopWebServer } from 'wok-server'
+
+await startWebServer({
+  routers: { '/': async exchange => exchange.respondText('Hello') }
+})
+
+await stopWebServer()
+```
+
+服务全局单例，重复启动抛异常。进程退出前自动停止。
+
+---
+
+## 路由
+
+路由是 `Record<string, RouterHandler>`，key 为路径，value 为异步处理函数。**仅支持明确地址，不支持动态路径（如 `/users/:id`）**。
+
+```ts
+import { RouterHandler } from 'wok-server'
+
+const myHandler: RouterHandler = async exchange => {
+  const body = await exchange.bodyJson()
+  exchange.respondJson({ ok: true })
+}
+```
+
+特殊路径 `'*'` 匹配所有未命中请求，用于自定义 404。
+
+### ServerExchange
+
+路由处理函数的参数，提供请求读取与响应方法：
+
+```ts
+// 读取请求
+exchange.request.method          // 请求方法
+exchange.request.url             // 请求 URL
+exchange.request.headers         // 消息头
+exchange.parseQueryString()      // 解析 QueryString → QueryString 对象
+
+// 读取正文
+const body = await exchange.bodyBuffer()     // Buffer
+const text = await exchange.bodyText()       // string
+const json = await exchange.bodyJson<T>()    // T
+
+// 响应
+exchange.respondText('text', 200)
+exchange.respondJson({ ok: true }, 200)
+exchange.respondErrMsg('错误信息', 400)       // JSON 格式: { message }
+exchange.respondFile('/abs/path/to/file')
+exchange.respondHtml('<h1>Hi</h1>', 200)
+exchange.respond({ statusCode: 200, body: 'raw', headers: { ... } })
+```
+
+---
+
+## 拦截器
+
+类型 `Interceptor: (exchange, next) => Promise<void>`。按数组中顺序执行，调用 `next()` 继续下一拦截器或路由。
+
+```ts
+const authInterceptor: Interceptor = async (exchange, next) => {
+  const token = exchange.request.headers.authorization
+  if (!token) {
+    exchange.respondErrMsg('Unauthorized', 401)
+    return
+  }
+  await next()
+}
+```
+
+典型用途：授权校验、异常统一处理、CORS 预检等。服务选项中 `SERVER_ACCESS_LOG=true` 会自动注入访问日志拦截器（位于最前）。
+
+---
+
+## JSON 请求处理器
+
+`createJsonHandler<REQ, RES>` 封装了请求正文 JSON 解析、校验、i18n 语言切换、响应缓存等常见流程：
+
+```ts
+import { createJsonHandler, notBlank, length } from 'wok-server'
+
+interface Form { code: string; nickname: string }
+interface Resp { id: string }
+
+const createUser = createJsonHandler<Form, Resp>({
+  validation: {
+    code: [notBlank(), length({ max: 64 })],
+    nickname: [notBlank(), length({ max: 64 })]
+  },
+  async handle(body, exchange) {
+    const newUser = await insertUser(body)
+    return { id: newUser.id }
+  }
+})
+```
+
+- 仅处理 POST 请求，非 POST 返 405
+- `validation` 可选，校验前自动通过 `accept-language` 切换校验器语言
+- 支持 `validation` 为函数以动态生成规则
+- `cache` 可选，设置后通过缓存组件缓存 `Buffer` 格式的响应（避免重复序列化）
+
+---
+
+## 文件上传
+
+`createUploadHandler<RES>` 处理 `application/octet-stream` 格式的二进制文件上传，比 multipart/form-data 更简单高效。也支持通过第三方库（如 formidable）处理 multipart/form-data 格式。
+
+详见：[文件上传](references/upload.md)
+
+---
+
+## Restful 方法分派
+
+```ts
+import { restful } from 'wok-server'
+
+routers: {
+  '/users': restful({
+    get: async exchange => { /* 查列表 */ },
+    post: async exchange => { /* 创建 */ },
+    delete: async exchange => { /* 删除 */ }
+  })
+}
+```
+
+---
+
+## 响应 HTML
+
+`exchange.respondHtml()` 支持两种方式：内置 `HtmlStuct` 结构化构建（提供 `HtmlTag` 类型推断，支持动态渲染），或直接传入第三方模板引擎（Handlebars、Vue SSR 等）渲染后的 HTML 字符串。
+
+详见：[响应 HTML](references/respond-html.md)
+
+---
+
+## SSE 服务端推送
+
+`createSseHandler` 封装了 Server-Sent Events 协议细节，通过 `ctx.send()` 即可推送数据，支持命名事件和断线重连。
+
+详见：[Server-Sent Events](references/sse.md)
+
+---
+
+## 静态文件
+
+通过 `static` 参数设置静态文件目录映射，支持前缀匹配、主页自动映射和服务器端缓存。
+
+详见：[静态文件](references/static-files.md)
+
+---
+
+## TLS / HTTPS
+
+```bash
+SERVER_TLS_ENABLE=true
+SERVER_TLS_KEY=/path/to/key.pem
+SERVER_TLS_CERT=/path/to/cert.pem
+```
+
+---
+
+## 内部实现要点
+
+### 请求处理流程
+
+```
+请求到达 → WokServer.handleRequest()
+  → 依次执行拦截器链（含可选的 accessLogInterceptor、CORS 处理）
+  → 路由匹配（精确匹配，未命中使用 '*' handler）
+  → 未捕获异常统一响应 500
+```
+
+### ServerExchange
+
+封装 `IncomingMessage` 和 `ServerResponse`。`bodyBuffer()` 内部有缓存，多次调用只读一次流。`bodyJson` 空正文返回 `{}`。
+
+### createJsonHandler 缓存
+
+缓存值为 `Buffer`（序列化后的 JSON），直接 `response.end(buffer)` 避免重复 `JSON.stringify`。`cache` 函数返回 `{ key, expiresInSeconds }`，存入缓存组件。
+
+---
+
+## 参考文档
+
+以下为扩展功能的详细参考文档：
+
+| 文档                                          | 说明                     |
+| :-------------------------------------------- | :----------------------- |
+| [文件上传](references/upload.md)                         | 二进制上传与 multipart/form-data |
+| [响应 HTML](references/respond-html.md)                 | 内置结构化构建与第三方模板引擎 |
+| [静态文件](references/static-files.md)                   | 静态文件目录映射与缓存   |
+| [WebSocket](references/websocket.md)                     | 通过 socket.io 集成 WebSocket |
+| [Server-Sent Events](references/sse.md)                  | `createSseHandler` 服务端推送 |

package/skills/wok-server-mvc/references/respond-html.md

@@ -0,0 +1,157 @@
+# 响应 HTML
+
+MVC 组件提供了两种 HTML 响应方式：框架内置的结构化 HTML 构建和第三方模板引擎。
+
+## 内置 HTML 构建
+
+`ServerExchange.respondHtml()` 接收 `HtmlStuct` 对象或 HTML 字符串，自动渲染并设置 `Content-Type: text/html; charset=utf-8`。
+
+### HtmlStuct 结构
+
+```ts
+interface HtmlStuct {
+  lang?: string          // <html lang="zh">
+  head: SubElementsOpt   // <head> 子元素
+  body: SubElementsOpt | { attrs?: HtmlAttrs; children: SubElementsOpt }  // <body> 子元素及属性
+}
+
+type SubElementsOpt = Array<HtmlTag | string> | ((add: (...child) => void) => void)
+```
+
+`SubElementsOpt` 既可以是静态数组，也可以是一个函数，通过回调参数 `add` 动态添加子元素，配合循环和分支语句实现动态渲染。
+
+### HtmlTag 标签定义
+
+```ts
+interface HtmlTag {
+  tag: string             // 标签名，如 'div'、'span'、'h1'
+  selfClosing?: boolean   // 是否自闭合，如 <br/>、<img/>
+  attrs?: HtmlAttrs        // 属性（有类型推断，支持 id、class、style 等全局属性）
+  children?: SubElementsOpt // 子元素
+}
+```
+
+### 完整示例
+
+```ts
+await startWebServer({
+  routers: {
+    '/profile': async exchange => {
+      const user = await getUser(exchange.headers.authorization)
+      exchange.respondHtml({
+        lang: 'zh',
+        head: [
+          { tag: 'title', children: ['个人中心'] },
+          { tag: 'script', attrs: { type: 'module', src: 'main.js' } }
+        ],
+        body: {
+          attrs: { style: { 'background-color': 'white' } },
+          children: add => {
+            add({ tag: 'h1', children: ['个人中心'] })
+            if (user) {
+              add({ tag: 'p', children: [`用户名：${user.account}`] })
+            } else {
+              add({
+                tag: 'p',
+                children: [
+                  '请登录后查看',
+                  { tag: 'a', attrs: { href: '/login' }, children: ['点击进行登录'] }
+                ]
+              })
+            }
+            add(footer())
+          }
+        }
+      })
+    }
+  }
+})
+```
+
+### 提取可复用组件
+
+常用的标签组合可封装为函数，返回 `HtmlTag` 类型：
+
+```ts
+function footer(): HtmlTag {
+  return {
+    tag: 'div',
+    attrs: { class: 'footer' },
+    children: [
+      { tag: 'a', attrs: { href: '/about' }, children: ['关于我们'] },
+      { tag: 'a', attrs: { href: '/call' }, children: ['联系我们'] },
+      { tag: 'a', attrs: { href: '/privacy' }, children: ['隐私协议'] }
+    ]
+  }
+}
+```
+
+### 快捷方法
+
+除了 `respondHtml()`，也可直接传入 HTML 字符串：
+
+```ts
+exchange.respondHtml('<h1>Hello World</h1>')
+```
+
+等价于设置 `Content-Type: text/html` 并输出给定字符串。
+
+---
+
+## 第三方模板引擎
+
+如果不喜欢内置的结构化构建方式，也可以使用第三方模板库，渲染后将 HTML 字符串传给 `respondHtml()`。
+
+### Handlebars
+
+```ts
+import { compile } from 'handlebars'
+
+await startWebServer({
+  routers: {
+    '/html': async exchange => {
+      const template = compile(`
+        <!DOCTYPE html>
+        <html>
+        <head><title>Handlebars Example</title></head>
+        <body>
+          <p>Hello, my name is {{name}}.</p>
+          <ul>{{#kids}}<li>{{name}} is {{age}}</li>{{/kids}}</ul>
+        </body>
+        </html>
+      `)
+      const data = {
+        name: 'Alan',
+        kids: [{ name: 'Jimmy', age: '12' }, { name: 'Sally', age: '4' }]
+      }
+      exchange.respondHtml(template(data))
+    }
+  }
+})
+```
+
+### Vue 3.x SSR
+
+```ts
+import { createSSRApp } from 'vue'
+import { renderToString } from 'vue/server-renderer'
+
+await startWebServer({
+  routers: {
+    '/html': async exchange => {
+      const app = createSSRApp({
+        data: () => ({ count: 1 }),
+        template: `<button>{{ count }}</button>`
+      })
+      const html = await renderToString(app)
+      exchange.respondHtml(`<!DOCTYPE html>
+<html>
+  <head><title>Vue SSR</title></head>
+  <body><div id="app">${html}</div></body>
+</html>`)
+    }
+  }
+})
+```
+
+> **提示：** 无论使用哪种方式，最终调用 `exchange.respondHtml()` 即可正确设置响应头与状态码。