wok-server 0.5.0 → 0.7.0

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

@@ -0,0 +1,388 @@
+---
+name: wok-server-mysql
+description: wok-server MySQL 组件使用指南，提供单表 CRUD、多数据源、版本管理和事务的完整支持。
+license: MIT
+metadata:
+  author: Peak Tai
+  email: peaktai@qq.com
+---
+
+# wok-server MySQL 组件
+
+## 概述
+
+MySQL 组件基于 [mysql2](https://www.npmjs.com/package/mysql2) 封装，提供便捷的单表操作。支持：实体映射 CRUD、多数据源、SQL 版本管理、事务、慢查询告警。
+
+## 源码与类型定义
+
+安装 `wok-server` 后，可通过以下路径查看源码与类型定义：
+
+- 源码目录：`node_modules/wok-server/src/mysql/`
+- 类型定义：`node_modules/wok-server/types/` （引用 mysql 组件的 `.d.ts` 文件）
+
+核心源码文件：
+
+| 文件               | 说明                               |
+| :----------------- | :--------------------------------- |
+| `index.ts`         | 模块入口，`enableMysql`/`getMysqlManager` |
+| `config.ts`        | 配置定义与默认值                    |
+| `table-info.ts`    | `Table<T>` 表映射接口               |
+| `manager/`         | 管理器层：`BaseMysqlManager`、`MysqlManager`、`MysqlTxSession` |
+| `manager/ops/`     | 各操作的 SQL 生成与执行             |
+| `manager/ops/criteria.ts` | `MysqlCriteria` 条件构建器    |
+| `migration.ts`     | SQL 文件版本管理                    |
+| `exception.ts`     | `MysqlException` 异常类             |
+
+---
+
+## 环境变量
+
+| 环境变量                       | 说明                 | 默认值       |
+| :----------------------------- | :------------------- | :----------- |
+| `MYSQL_HOST`                   | 主机名               | localhost    |
+| `MYSQL_PORT`                   | 端口号               | 3306         |
+| `MYSQL_USER`                   | 用户名               | root         |
+| `MYSQL_PASSWORD`               | 密码                 | 123456       |
+| `MYSQL_DATABASE`               | 数据库名             | example      |
+| `MYSQL_CHARSET`                | 字符集               | utf8mb4      |
+| `MYSQL_CONNECTION_LIMIT`       | 最大连接数           | 10           |
+| `MYSQL_MAX_IDLE`               | 最大闲置连接数       | 10           |
+| `MYSQL_IDLE_TIMEOUT`           | 闲置超时（ms）       | 60000        |
+| `MYSQL_CONNECT_TIMEOUT`        | 连接超时（ms）       | 10000        |
+| `MYSQL_DEBUG`                  | 调试模式，输出 SQL   | false        |
+| `MYSQL_SLOW_SQL_WARN`          | 慢查询警告           | true         |
+| `MYSQL_SLOW_SQL_MS`            | 慢查询阈值（ms）     | 200          |
+| `MYSQL_TIMEZONE`               | 时区                 | +08:00       |
+| `MYSQL_VERSION_CONTROL_ENABLED`| 版本管理开启         | false        |
+| `MYSQL_VERSION_CONTROL_DIR`    | 迁移文件目录         | db_migration |
+| `MYSQL_TRANSACTION_TIMEOUT`    | 事务超时（ms）       | 5000         |
+| `MYSQL_TRANSACTION_STRICT`     | 事务严格模式         | true         |
+| `MYSQL_MAX_OPS_IN_STRICT_TX`   | 严格事务最大操作次数 | 10           |
+
+---
+
+## 初始化
+
+```ts
+import { enableMysql, getMysqlManager } from 'wok-server'
+
+await enableMysql()
+const manager = getMysqlManager()
+```
+
+多数据源（如读写分离等高级用法）见[参考文档](./references/multi-datasource.md)。
+
+---
+
+## 实体类配置
+
+表映射配置由 `Table<T>` 接口定义，字段分三部分：主键、普通列、时间列，三者不允许重叠。
+
+```ts
+import { Table } from 'wok-server'
+
+export interface User {
+  id: string
+  nickname: string
+  hobby?: string
+  create_at?: number
+  update_at?: number
+}
+
+export const tableUser: Table<User> = {
+  tableName: 'user',
+  id: 'id',
+  columns: ['nickname', 'hobby'],
+  createdDate: { type: 'number', column: 'create_at' },
+  updatedDate: { type: 'number', column: 'update_at' }
+}
+```
+
+`createdDate` 和 `updatedDate` 配置的字段由框架自动管理：`insert`/`insertMany` 时自动填入创建时间和更新时间，`update`/`partialUpdate`/`updateMany` 时自动更新 `updatedDate` 字段。业务代码中不需要手动设置这两个字段的值。
+
+> **⚠️ 重要：框架不支持字段名称映射。** 实体类型的字段名必须和数据库列名一模一样。比如数据库列名是 `entry_date`，实体字段不能写为 `entryDate` 或 `entryDate` 再用装饰器映射，必须是 `entry_date: Date`。如果之前用惯了其他 ORM 框架，很容易在这里习惯性写成驼峰而掉坑，务必注意。
+
+### 类型映射规则
+
+| JS 类型        | MySQL 字段类型                                                        |
+| :------------- | :------------------------------------------------------------------- |
+| `boolean`      | TINYINT                                                              |
+| `number`       | TINYINT, SMALLINT, INT, MEDIUMINT, YEAR, FLOAT, DOUBLE, BIGINT       |
+| `Date`         | TIMESTAMP, DATE, DATETIME                                             |
+| `Buffer`       | TINYBLOB, MEDIUMBLOB, LONGBLOB, BLOB, BINARY, VARBINARY, BIT         |
+| `string`       | CHAR, VARCHAR, TINYTEXT, MEDIUMTEXT, LONGTEXT, TEXT, ENUM, SET, DECIMAL, TIME |
+| `object`/`array` | JSON                                                                |
+
+实体字段类型必须与数据库列类型匹配对应的 JS 原生类型，否则查询结果会不正确。可空字段在实体中也定义为可选（`?`）。
+
+---
+
+## CRUD 操作
+
+所有操作以 `Table<T>` 为第一个参数。
+
+### 查询
+
+```ts
+const user = await manager.findById(tableUser, '001')           // 按 ID 查
+const users = await manager.findByIdIn(tableUser, ['001','002'])  // 批量 ID 查
+const list = await manager.findAll(tableUser)                   // ⚠️ 全表，危险
+```
+
+### 条件查询
+
+使用 `MysqlCriteria` 构建条件，默认 AND 关系：
+
+```ts
+const user = await manager.findFirst(tableUser, c =>
+  c.like('nickname', 'ff0%').gt('balance', 75).lt('balance', 77)
+)
+```
+
+**链式条件方法**：`eq`、`neq`、`gt`、`gte`、`lt`、`lte`、`like`、`notLike`、`between`、`in`、`notIn`、`isNull`、`isNotNull`、`or`、`and`、`expr`。
+
+`expr()` 方法支持在 WHERE 子句中插入自定义 SQL 表达式：
+
+```ts
+c => c.like('id', 'critex%').expr('?? * ? > ?', ['balance', 2, 50])
+// SQL: where `id` like 'critex%' and `balance` * 2 > 50
+```
+
+### 复杂查询
+
+```ts
+const list = await manager.find({
+  table: tableUser,
+  criteria: c => c.between('balance', 700, 800).like('id', 'find%'),
+  offset: 1,
+  limit: 10,
+  orderBy: [['balance', 'asc']]
+})
+
+// 自定义排序表达式
+const list2 = await manager.find({
+  table: tableUser,
+  criteria: c => c.like('nickname', 'ob%'),
+  orderBy: [['expr', '?? * ?', ['balance', 2], 'desc']]
+})
+// SQL: ORDER BY `balance` * 2 desc
+```
+
+### 分页
+
+```ts
+const page = await manager.paginate({
+  table: tableUser,
+  criteria: c => c.like('id', 'pg0%'),
+  pn: 2, pz: 5,
+  orderBy: [['balance', 'asc'], ['id', 'asc']]
+})
+// { total: number, list: T[] }
+
+// 指定字段分页查询
+const page2 = await manager.paginateSelect({
+  table: tableUser,
+  criteria: c => c.like('id', 'pg0%'),
+  select: ['id', 'nickname', 'balance'],
+  pn: 2, pz: 5
+})
+// { total: number, list: Pick<T, 'id'|'nickname'|'balance'>[] }
+```
+
+### 插入
+
+```ts
+const newUser = await manager.insert(tableUser, { id: 'in001', nickname: '小明' })
+await manager.insertMany(tableUser, [
+  { id: 'im001', nickname: '张飞' },
+  { id: 'im002', nickname: '关羽' }
+])
+
+// 插入时使用表达式（InsertValue）
+await manager.insert(tableUser, {
+  id: 'in002',
+  nickname: '小红',
+  balance: ['expr', '?? * ?', ['score', 2]],
+  createAt: ['now']
+})
+```
+
+支持三种表达式：`['now']`（NOW()）、`['set', value]`（解决元组冲突）、`['expr', sql, values?]`（自定义 SQL）。
+
+### Upsert
+
+```ts
+// 单条 upsert，主键冲突则更新
+await manager.upsert(tableUser, { id: 'us001', nickname: '赵云', balance: 10 })
+
+// 批量 upsert
+await manager.upsertMany(tableUser, [
+  { id: 'us002', nickname: '马超', balance: 20 },
+  { id: 'us003', nickname: '黄忠', balance: 30 }
+])
+
+// 冲突时自定义更新（使用 Updater）
+await manager.upsertWithUpdater(
+  tableUser,
+  { id: 'us001', nickname: '赵云', balance: 10 },
+  { balance: ['inc', 5], nickname: '赵云-updated' }
+)
+```
+
+### 更新
+
+```ts
+// 完整更新（需要完整文档）
+await manager.update(tableUser, { id: 'xxx', nickname: '王五' })
+
+// 局部更新
+await manager.partialUpdate(tableUser, {
+  id: 'pu000',
+  // 自增 +22
+  balance: ['inc', 22],
+  // 自增 +1（默认值）
+  visits: ['inc'],
+  // NULL 安全的字符串追加
+  nickname: ['concat', '-suffix'],
+  // 设置为 NOW()
+  last_login_at: ['now'],
+  // 自定义表达式
+  score: ['expr', '?? * ?', ['score', 2]]
+})
+
+// 批量更新
+await manager.updateMany(tableUser, c => c.like('nickname', 'um%'), { balance: ['inc', 2] })
+```
+
+> **0.7.0 版本**开始，`null` 不再自动置 NULL。如需将字段设置为 NULL，必须显式使用 `['setNull']`。
+> `['func']` 已移除，请使用 `['expr']` 替代（如 `['func', 'NOW()']` → `['expr', 'NOW()']`）。
+
+### 删除
+
+```ts
+await manager.deleteById(tableUser, 'd0001')
+await manager.deleteMany({ table: tableUser, criteria: { status: 'DISABLED' }, limit: 100 })
+await manager.deleteOne(tableUser, { id: 'only_one' })
+```
+
+**⚠️ `deleteMany` 是危险操作**，建议严格限制条件并设置 `limit` 参数。
+
+### 自定义 SQL
+
+```ts
+// 查询
+const list = await manager.query<{ author: string; book: string }>(
+  'select u.nickname as author, b.name as book from ?? u left join ?? b on u.id=b.author_id where b.id is not null',
+  ['user', 'book']
+)
+
+// 修改
+const affected = await manager.modify(`update user set nickname='无名' where nickname='佚名'`)
+```
+
+### 全部方法
+
+| 方法           | 说明                         | 危险 |
+| :------------- | :--------------------------- | :--- |
+| `findById`     | 按 id 查询                   |      |
+| `findByIdIn`   | 批量 id 查询                 |      |
+| `findFirst`    | 查第一条符合条件的           |      |
+| `find`         | 条件查询，支持 offset/limit  | ⚠️   |
+| `findSelect`   | 条件查询，指定返回列         | ⚠️   |
+| `findAll`      | 全表查询                     | ⚠️   |
+| `existsBy`     | 条件判断存在                 |      |
+| `existsById`   | id 判断存在                  |      |
+| `count`        | 统计数量                     | ⚠️   |
+| `paginate`     | 分页查询                     | ⚠️   |
+| `paginateSelect` | 指定字段分页查询            | ⚠️   |
+| `insert`       | 插入单条                     |      |
+| `insertMany`   | 批量插入                     |      |
+| `upsert`       | 插入单条，主键冲突则更新     |      |
+| `upsertMany`   | 批量 upsert                  |      |
+| `upsertWithUpdater` | upsert 单条，冲突时自定义更新 |  |
+| `update`       | 完整更新                     |      |
+| `partialUpdate`| 局部更新                     |      |
+| `updateOne`    | 更新第一条相等条件           |      |
+| `updateMany`   | 批量更新                     | ⚠️   |
+| `deleteById`   | 按 id 删除                   |      |
+| `deleteOne`    | 删除第一条相等条件           |      |
+| `deleteMany`   | 批量删除                     | ⚠️   |
+| `query`        | 自定义 SQL 查询              |      |
+| `modify`       | 自定义 SQL 修改              |      |
+
+---
+
+## JSON 类型支持
+
+在实体中直接定义 JSON 字段对应的 TS 类型即可，框架自动解析：
+
+```ts
+interface Question {
+  id: string
+  options: { title: string; correct?: boolean }[]
+}
+
+export const tableQuestion: Table<Question> = {
+  tableName: 'question', id: 'id', columns: ['options']
+}
+```
+
+条件查询支持 `json_extract` 和 `json_length`，使用元组代替列名：
+
+```ts
+await manager.findFirst(tableQuestion, c =>
+  c.eq(['json_extract', 'question_setter', '$.id'], 'x333')
+)
+await manager.findFirst(tableQuestion, c =>
+  c.gt(['json_length', 'options'], 3)
+)
+```
+
+---
+
+## 事务
+
+```ts
+await manager.tx(async session => {
+  await session.partialUpdate(tableAccount, { id: accId, balance: ['inc', -amount] })
+  await session.insert(tableOrder, { id: orderId, amount })
+}, { timeout: 3000 })
+```
+
+事务操作**必须使用 `session` 对象**，直接调用 `manager` 的方法不会在事务中生效。
+
+选项：
+- `timeout`：超时时间（ms），超时后自动回滚并抛出 `MysqlException`
+- `isolationLevel`：隔离级别（`REPEATABLE READ` 等）
+- `accessMode`：读写模式（`READ WRITE` / `READ ONLY`）
+
+### 严格模式
+
+`MYSQL_TRANSACTION_STRICT=true` 时启用严格模式，限制事务中的操作次数（`MYSQL_MAX_OPS_IN_STRICT_TX`，默认 10 次）。超限抛出 `MysqlException`。
+
+---
+
+## 内部实现要点
+
+### 连接管理
+
+`enableMysql` 注册配置 → 可选迁移 → 创建 `Pool` → 构建 `MysqlManager` → 存入 `managerMap`。进程退出前自动关闭连接池。
+
+### 查询流程
+
+`MysqlManager` 从连接池获取连接 → `Promise.race` 超时竞速 → 执行 SQL → 释放连接。
+
+### 慢查询
+
+所有 CRUD 操作（除自定义 SQL）自动计时，超过 `MYSQL_SLOW_SQL_MS` 时输出 WARN 日志。
+
+### Migration 实现
+
+版本管理的完整使用说明见[参考文档](./references/version-control.md)。
+
+---
+
+## 参考
+
+- [多数据源（读写分离等高级用法）](./references/multi-datasource.md)
+- [版本管理](./references/version-control.md)

package/skills/wok-server-mysql/references/multi-datasource.md

@@ -0,0 +1,76 @@
+# MySQL 多数据源
+
+## 启用多数据源
+
+```ts
+await enableMysql()          // 默认，以 MYSQL_ 为前缀
+await enableMysql('d2')      // 自定义，以 D2_ 为前缀
+
+const mgr1 = getMysqlManager()      // 默认
+const mgr2 = getMysqlManager('d2')  // d2
+```
+
+名称必须以英文字母开头，由字母数字下划线组成，不超过 32 位。环境变量前缀自动转换为大写。
+
+环境变量配置示例：
+
+```bash
+# 默认 enableMysql()，前缀 MYSQL_
+MYSQL_HOST=localhost
+MYSQL_PORT=3306
+MYSQL_USER=test
+MYSQL_PASSWORD=abc123
+MYSQL_DATABASE=test1
+
+# enableMysql('d2')，前缀 D2_
+D2_HOST=localhost
+D2_PORT=3306
+D2_USER=test2
+D2_PASSWORD=abcdefg
+D2_DATABASE=test2
+```
+
+---
+
+## 技巧：读写分离
+
+实体类的表配置（`Table<T>`）与数据库实例没有强制绑定关系，同一套表配置可以给多个 `MysqlManager` 使用。利用这个特性和多数据源，可以实现读写分离。
+
+```ts
+import { enableMysql, getMysqlManager } from 'wok-server'
+import { tableUser } from './user'
+
+// 主库（读写）
+await enableMysql('master')
+// 只读库
+await enableMysql('slave')
+
+const masterMgr = getMysqlManager('master')
+const slaveMgr = getMysqlManager('slave')
+
+// 写操作使用主库
+const newUser = await masterMgr.insert(tableUser, { id: '001', nickname: 'jack' })
+
+// 读操作使用只读库
+const user = await slaveMgr.findById(tableUser, '001')
+```
+
+环境变量分别配置两个源：
+
+```bash
+# 主库
+MASTER_HOST=master-db.example.com
+MASTER_PORT=3306
+MASTER_USER=writer
+MASTER_PASSWORD=xxx
+MASTER_DATABASE=mydb
+
+# 只读库
+SLAVE_HOST=slave-db.example.com
+SLAVE_PORT=3306
+SLAVE_USER=reader
+SLAVE_PASSWORD=xxx
+SLAVE_DATABASE=mydb
+```
+
+在 `main.ts` 入口中分别初始化后，将两个 manager 导出，业务模块按读写需求选择使用即可。

package/skills/wok-server-mysql/references/version-control.md

@@ -0,0 +1,22 @@
+# MySQL 版本管理
+
+开启 `MYSQL_VERSION_CONTROL_ENABLED=true`，在 `db_migration/` 目录下创建 SQL 文件，文件名为纯数字：
+
+```
+db_migration/
+  1.sql        # 版本号从 1 开始，必须连续递增
+  2.sql
+  3.sql
+```
+
+文件名必须是纯数字 + `.sql` 后缀（如 `1.sql`、`2.sql`），非数字前缀会导致 `parseInt` 失败而抛异常。编号必须从 1 开始连续递增，不连续也会抛异常。
+
+启动时自动在事务中检测当前版本，顺序执行未执行的 SQL 并更新版本号。
+
+版本信息存储在 `db_version` 表（单行 `key='db_version'`，`version` 列）。
+
+> **⚠️ 注意事项：开销非常高的 SQL 不能放在版本管理中执行。** 比如在大表上创建/修改索引这类操作，执行耗时长且会锁表，可能阻塞线上服务。此类操作应单独在线上手动执行，不要放入迁移文件。
+
+## 实现细节
+
+使用独立的 `multipleStatements` 连接在事务中执行：读取当前版本 → 筛选待执行版本 → 逐个执行 SQL 并更新 `db_version` → 提交。出错需手动在数据库中修复后重新启动。

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

@@ -0,0 +1,158 @@
+---
+name: wok-server-task
+description: wok-server 任务调度组件使用指南，提供固定频率、固定延迟和每日定时三种调度模式。
+license: MIT
+metadata:
+  author: Peak Tai
+  email: peaktai@qq.com
+---
+
+# wok-server 任务调度组件
+
+## 概述
+
+任务调度组件提供周期性任务功能，封装了启动、执行、超时、异常记录和耗时告警。提供三种调度模式。
+
+## 源码与类型定义
+
+安装 `wok-server` 后，可通过以下路径查看源码与类型定义：
+
+- 源码目录：`node_modules/wok-server/src/task/`
+- 类型定义：`node_modules/wok-server/types/` （引用 task 组件的 `.d.ts` 文件）
+
+核心源码文件：
+
+| 文件             | 说明                               |
+| :--------------- | :--------------------------------- |
+| `index.ts`       | 模块聚合导出                       |
+| `task.ts`        | `Task` 接口、`TaskController`、`execTask` |
+| `fixed-delay.ts` | `scheduleWithFixedDelay` 固定延迟  |
+| `fixed-rate.ts`  | `scheduleWithFixedRate` 固定频率    |
+| `daily.ts`       | `scheduleDailyTask` 每日定时       |
+
+---
+
+## 三种调度模式
+
+### scheduleWithFixedDelay — 固定延迟
+
+```ts
+function scheduleWithFixedDelay(
+  initialDelay: number,  // 首次延迟（秒），0-86400
+  delay: number,         // 每次间隔（秒），1-86400
+  task: Task,
+  timeout?: number       // 任务超时（ms），可选
+): TaskController
+```
+
+**每次任务执行完毕后等待 `delay` 秒再执行下一次**。适合对间隔有严格要求的场景。
+
+```ts
+import { scheduleWithFixedDelay } from 'wok-server'
+
+const controller = scheduleWithFixedDelay(10, 60, {
+  name: '记录在线人数',
+  async run() {
+    const count = await countAuth()
+    await createPcu({ count, time: new Date() })
+  }
+})
+
+controller.stop()  // 停止任务
+```
+
+### scheduleWithFixedRate — 固定频率
+
+```ts
+function scheduleWithFixedRate(
+  initialDelay: number,  // 首次延迟（秒），0-86400
+  period: number,        // 执行周期（秒），1-86400
+  task: Task,
+  timeout?: number       // 任务超时（ms），可选
+): TaskController
+```
+
+参数完全相同，区别在于：**以任务的开始时间计算周期**。如果任务执行时间超过周期，下次任务立即执行。与固定延迟区别的核心在于内部 `exec` 中的 `setTimeout` 计算方式不同——固定频率使用 `res.start + period - now`，首次执行时记录 `start` 时间戳。
+
+### scheduleDailyTask — 每日定时
+
+```ts
+function scheduleDailyTask(
+  hours: number,    // 时（0-23）
+  minutes: number,  // 分（0-59）
+  task: Task,
+  timeout?: number
+): TaskController
+```
+
+```ts
+const dc = scheduleDailyTask(1, 30, {
+  name: '学习报表',
+  async run() { /* 每天 1:30 执行 */ }
+})
+```
+
+计算逻辑：当前时间在当天目标时间之前 → 当天执行；否则推迟到明天。
+
+---
+
+## Task 接口与 TaskController
+
+```ts
+interface Task {
+  name: string              // 任务名称，用于日志跟踪
+  run: () => Promise<void>  // 异步执行函数
+}
+
+class TaskController {
+  isStopped(): boolean      // 是否已停止
+  stop(): void              // 停止任务，当前正在执行的不会被中断
+}
+```
+
+---
+
+## 内置日志行为
+
+`execTask` 函数统一封装了任务的执行过程：
+
+- **开始时**：DEBUG 日志 `START TASK：{name}`
+- **成功完成**：DEBUG 日志记录耗时
+- **执行 > 5 分钟**：WARN 日志 `Task "{name}" takes too long`
+- **异常**：ERROR 日志 `TASK ERROR: {name}`（包含异常详情）
+- **超时**：如果设置了 timeout 并超时，`Promise.race` 抛出超时错误，被 catch 记录
+
+---
+
+## 参数校验
+
+所有调度函数都会对传入的延迟/周期参数进行校验：
+
+```ts
+validate(
+  { initialDelay, delay },
+  {
+    initialDelay: [notNull(), min(0), max(3600 * 24)],
+    delay: [notNull(), min(1), max(3600 * 24)]
+  }
+)
+```
+
+参数不合法时直接抛出 `ValidationException`。
+
+---
+
+## 内部实现要点
+
+### 调度循环
+
+两个固定模式的差异仅在循环逻辑：
+
+- **FixedDelay**：`await execTask → setTimeout(exec, delay)` — 等上次执行完再开始计时
+- **FixedRate**：`const res = await execTask → setTimeout(exec, res.start + period - now)` — 用开始时间计算，可能立即执行
+
+两者都在首次使用 `setTimeout` 延迟 `initialDelay` 秒，之后通过递归 `setTimeout`（而非 `setInterval`）控制，避免任务积压。
+
+### execTask 超时机制
+
+通过 `Promise.race([task.run(), timeoutPromise])` 实现。超时后外部 catch 记录 ERROR 日志，不会中断调度循环。