wok-server 0.6.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-mysql/SKILL.md

@@ -139,7 +139,14 @@ const user = await manager.findFirst(tableUser, c =>
 )
 ```
 
-**链式条件方法**：`eq`、`neq`、`gt`、`gte`、`lt`、`lte`、`like`、`notLike`、`between`、`in`、`notIn`、`isNull`、`isNotNull`、`or`、`and`。
+**链式条件方法**：`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
+```
 
 ### 复杂查询
 
@@ -151,6 +158,14 @@ const list = await manager.find({
   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
 ```
 
 ### 分页
@@ -163,6 +178,15 @@ const page = await manager.paginate({
   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'>[] }
 ```
 
 ### 插入
@@ -173,6 +197,36 @@ 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' }
+)
 ```
 
 ### 更新
@@ -181,13 +235,28 @@ await manager.insertMany(tableUser, [
 // 完整更新（需要完整文档）
 await manager.update(tableUser, { id: 'xxx', nickname: '王五' })
 
-// 局部更新（使用元组语法：['inc', 22] 表示 +22，[null] 表示置空）
-await manager.partialUpdate(tableUser, { id: 'pu000', balance: ['inc', 22] })
+// 局部更新
+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
@@ -225,8 +294,12 @@ const affected = await manager.modify(`update user set nickname='无名' where n
 | `existsById`   | id 判断存在                  |      |
 | `count`        | 统计数量                     | ⚠️   |
 | `paginate`     | 分页查询                     | ⚠️   |
+| `paginateSelect` | 指定字段分页查询            | ⚠️   |
 | `insert`       | 插入单条                     |      |
 | `insertMany`   | 批量插入                     |      |
+| `upsert`       | 插入单条，主键冲突则更新     |      |
+| `upsertMany`   | 批量 upsert                  |      |
+| `upsertWithUpdater` | upsert 单条，冲突时自定义更新 |  |
 | `update`       | 完整更新                     |      |
 | `partialUpdate`| 局部更新                     |      |
 | `updateOne`    | 更新第一条相等条件           |      |

package/src/mysql/config.ts

@@ -57,7 +57,7 @@ export interface MysqlConfig {
    */
   maxIdle: number
   /**
-   * 闲置的超时时间，也即多久不用算闲置，单位毫秒
+   * 闲置的超时时间，当一个数据库连接不再被业务使用、处于闲置状态的时间超过这个阈值，连接池就会自动回收并关闭这个连接，释放资源。
    */
   idleTimeout: number
   /**
@@ -123,7 +123,7 @@ export const configValidation: ValidationOpts<MysqlConfig> = {
   maxIdle: [notNull(), min(1), max(999)],
   idleTimeout: [notNull(), min(1000), max(60000)],
   slowSqlWarn: [notNull()],
-  slowSqlMs: [notNull(), min(1), max(3600000)],
+  slowSqlMs: [notNull(), min(0), max(3600000)],
   transactionTimeout: [notNull(), min(0), max(60000)],
   transactionStrict: [notNull()],
   maxOpsInStrictTx: [notNull(), min(1)]

package/src/mysql/manager/base.ts

@@ -8,8 +8,11 @@ import {
   MixCriteria,
   MysqlPage,
   MysqlPaginateOpts,
+  MysqlPaginateSelectOpts,
+  OrderBy,
   UpdateOpts,
   Updater,
+  InsertValue,
   count,
   deleteMany,
   deleteById,
@@ -24,13 +27,17 @@ import {
   insertMany,
   modify,
   paginate,
+  paginateSelect,
   partialUpdate,
   query,
   update,
   updateMany,
   updateOne,
   FindSelectOpts,
-  findSelect
+  findSelect,
+  upsert,
+  upsertMany,
+  upsertWithUpdater
 } from './ops'
 import { promiseGetConnection } from './utils'
 
@@ -162,7 +169,7 @@ export abstract class BaseMysqlManager {
   findFirst<T>(
     table: Table<T>,
     criteria?: MixCriteria<T>,
-    orderBy?: Array<[keyof T, 'asc' | 'desc']>
+    orderBy?: OrderBy<T>
   ): Promise<T | null> {
     return this.queryWithConnection(conn =>
       findFirst(this.opts.config, conn, table, criteria, orderBy)
@@ -175,7 +182,7 @@ export abstract class BaseMysqlManager {
    * @param data 数据，数据必须是 T 的实例, T 必须是已配置的实体类类型，否则无法完成操作
    * @returns 插入后的数据
    */
-  insert<T>(table: Table<T>, data: T): Promise<T> {
+  insert<T>(table: Table<T>, data: InsertValue<T>): Promise<T> {
     return this.queryWithConnection(conn => insert(this.opts.config, conn, table, data))
   }
   /**
@@ -183,9 +190,40 @@ export abstract class BaseMysqlManager {
    * @param table 表
    * @param list 要插入的数据列表
    */
-  insertMany<T>(table: Table<T>, list: T[]): Promise<void> {
+  insertMany<T>(table: Table<T>, list: InsertValue<T>[]): Promise<void> {
     return this.queryWithConnection(conn => insertMany(this.opts.config, conn, table, list))
   }
+  /**
+   * Upsert 单条数据
+   * 如果主键冲突则更新，否则插入
+   * @param table 表信息
+   * @param data 数据
+   * @returns
+   */
+  upsert<T>(table: Table<T>, data: InsertValue<T>): Promise<T> {
+    return this.queryWithConnection(conn => upsert(this.opts.config, conn, table, data))
+  }
+  /**
+   * Upsert 多条数据
+   * 如果主键冲突则更新，否则插入
+   * @param table 表
+   * @param list 要插入的数据列表
+   * @returns 影响的行数
+   */
+  upsertMany<T>(table: Table<T>, list: InsertValue<T>[]): Promise<number> {
+    return this.queryWithConnection(conn => upsertMany(this.opts.config, conn, table, list))
+  }
+  /**
+   * Upsert 单条数据（支持自定义更新器）
+   * 如果主键冲突则按自定义逻辑更新，否则插入
+   * @param table 表信息
+   * @param data 插入的数据
+   * @param updater 冲突时的更新器
+   * @returns
+   */
+  upsertWithUpdater<T>(table: Table<T>, data: InsertValue<T>, updater: Updater<T>): Promise<T> {
+    return this.queryWithConnection(conn => upsertWithUpdater(this.opts.config, conn, table, data, updater))
+  }
   /**
    * 更新
    * @param table 表信息
@@ -264,6 +302,15 @@ export abstract class BaseMysqlManager {
     return this.queryWithConnection(conn => paginate(this.opts.config, conn, opts))
   }
 
+  /**
+   * 指定字段分页查询
+   * @param opts
+   * @returns
+   */
+  paginateSelect<T, K extends keyof T>(opts: MysqlPaginateSelectOpts<T, K>): Promise<MysqlPage<Pick<T, K>>> {
+    return this.queryWithConnection(conn => paginateSelect(this.opts.config, conn, opts))
+  }
+
   /**
    * 自定义查询，指定 sql 、参数和返回值类型
    * @param sql 预编译 sql ，参数使用 ”?“（英文问号） 占位，注意查询的字段名称会与返回值类型的字段映射，如果 sql 中的字段名称很特殊（比如纯数字等），需要设置别名，避免产生映射错误

package/src/mysql/manager/ops/criteria.ts

@@ -53,12 +53,21 @@ interface Criterion<T> {
     | 'isNotNull'
     | 'notLike'
     | 'between'
+    | 'expr'
   key?: MysqlCriteriaKey<T>
   value?: any
   /**
    * 嵌套的其它查询， or 和 and  条件下有效
    */
   criteria?: MysqlCriteria<T>
+  /**
+   * 自定义表达式的 SQL 片段（expr 条件下有效）
+   */
+  exprSql?: string
+  /**
+   * 自定义表达式的参数值
+   */
+  exprValues?: any[]
 }
 
 /**
@@ -208,6 +217,19 @@ export class MysqlCriteria<T> {
     this.criteria.push({ type: 'isNotNull', key: field })
     return this
   }
+  /**
+   * 自定义表达式查询
+   * 如 .expr('?? * ? > ?', ['balance', 2, 50])
+   * 如 .expr('MATCH(??, ??) AGAINST(? IN BOOLEAN MODE)', ['title', 'content', keyword])
+   * 如 .expr('VECTOR_DISTANCE(??, STRING_TO_VECTOR(?)) < ?', ['content_vec', embedding, threshold])
+   * @param sql SQL 片段，使用 ?? 引用列名，? 引用参数值
+   * @param values 参数值数组，按 SQL 中占位符顺序传入
+   * @returns
+   */
+  expr(sql: string, values?: any[]) {
+    this.criteria.push({ type: 'expr', exprSql: sql, exprValues: values || [] })
+    return this
+  }
   /**
    * 判定是否空，未设置条件.
    * @returns
@@ -220,6 +242,12 @@ export class MysqlCriteria<T> {
    */
   check() {
     for (const criterion of this.criteria) {
+      if (criterion.type === 'expr') {
+        if (!criterion.exprSql) {
+          throw new MysqlException('expr clause exprSql cannot be empty')
+        }
+        continue
+      }
       if (criterion.type === 'or' || criterion.type === 'and') {
         if (!criterion.criteria) {
           throw new MysqlException(`${criterion.type} clause cannot be empty`)
@@ -357,6 +385,12 @@ export class MysqlCriteria<T> {
           continue
         }
       }
+      // 自定义表达式
+      else if (criterion.type === 'expr' && criterion.exprSql) {
+        sqlFragments.push(`and ${criterion.exprSql} `)
+        values.push(...(criterion.exprValues || []))
+        continue
+      }
     }
     if (!sqlFragments.length) {
       throw new MysqlException('No valid query criteria have been set.')

package/src/mysql/manager/ops/delete.ts

@@ -4,6 +4,7 @@ import { Table } from '../../table-info'
 import { promiseQuery } from '../utils'
 import { MixCriteria, buildQuery } from './criteria'
 import { MysqlConfig } from '../../config'
+import { OrderBy, buildOrderBy } from './order-by'
 
 /**
  * 按 id 删除.
@@ -49,7 +50,7 @@ export interface DeleteManyOpts<T> {
   /**
    * 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
    */
-  orderBy?: Array<[keyof T, 'asc' | 'desc']>
+  orderBy?: OrderBy<T>
 }
 
 /**
@@ -77,15 +78,9 @@ export async function deleteMany<T>(
   }
   // 排序
   if (opts.orderBy && opts.orderBy.length) {
-    opts.orderBy.forEach((orderBy, idx) => {
-      const [field, sort] = orderBy
-      if (idx == 0) {
-        sql += ` order by ?? ${sort} `
-      } else {
-        sql += ` , ?? ${sort} `
-      }
-      values.push(field)
-    })
+    const ob = buildOrderBy(opts.orderBy)
+    sql += ob.sql
+    values.push(...ob.values)
   }
   // 数量限制
   if (opts.limit) {

package/src/mysql/manager/ops/find.ts

@@ -3,6 +3,7 @@ import { Table } from '../../table-info'
 import { MixCriteria, buildQuery } from './criteria'
 import { promiseQuery } from '../utils'
 import { MysqlConfig } from '../../config'
+import { OrderBy, buildOrderBy } from './order-by'
 
 /**
  * 按 id 查询
@@ -67,7 +68,7 @@ export interface FindOpts<T> {
   /**
    * 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
    */
-  orderBy?: Array<[keyof T, 'asc' | 'desc']>
+  orderBy?: OrderBy<T>
 }
 /**
  * 条件查询
@@ -89,15 +90,9 @@ export async function find<T>(
   }
   // 排序
   if (opts.orderBy && opts.orderBy.length) {
-    opts.orderBy.forEach((orderBy, idx) => {
-      const [field, sort] = orderBy
-      if (idx == 0) {
-        sql += ` order by ?? ${sort} `
-      } else {
-        sql += ` , ?? ${sort} `
-      }
-      values.push(field)
-    })
+    const ob = buildOrderBy(opts.orderBy)
+    sql += ob.sql
+    values.push(...ob.values)
   }
   // 数量限制
   if (opts.limit) {
@@ -141,15 +136,9 @@ export async function findSelect<T, K extends keyof T>(
   }
   // 排序
   if (opts.orderBy && opts.orderBy.length) {
-    opts.orderBy.forEach((orderBy, idx) => {
-      const [field, sort] = orderBy
-      if (idx == 0) {
-        sql += ` order by ?? ${sort} `
-      } else {
-        sql += ` , ?? ${sort} `
-      }
-      values.push(field)
-    })
+    const ob = buildOrderBy(opts.orderBy)
+    sql += ob.sql
+    values.push(...ob.values)
   }
   // 数量限制
   if (opts.limit) {
@@ -198,7 +187,7 @@ export async function findFirst<T>(
   /**
    * 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
    */
-  orderBy?: Array<[keyof T, 'asc' | 'desc']>
+  orderBy?: OrderBy<T>
 ): Promise<T | null> {
   let query = criteria ? buildQuery(criteria) : undefined
   let sql = `select * from ?? `
@@ -209,15 +198,9 @@ export async function findFirst<T>(
   }
   // 排序
   if (orderBy && orderBy.length) {
-    orderBy.forEach((orderBy, idx) => {
-      const [field, sort] = orderBy
-      if (idx == 0) {
-        sql += ` order by ?? ${sort} `
-      } else {
-        sql += ` , ?? ${sort} `
-      }
-      values.push(field)
-    })
+    const ob = buildOrderBy(orderBy)
+    sql += ob.sql
+    values.push(...ob.values)
   }
   sql += ' limit 1'
   const res = await promiseQuery(config, conn, sql, values)

package/src/mysql/manager/ops/index.ts

@@ -6,6 +6,8 @@ export * from './exist'
 export * from './find'
 export * from './insert'
 export * from './modify'
+export * from './order-by'
+export * from './upsert'
 export * from './paginate'
 export * from './query'
 export * from './update'