English | 简体中文

Wok Server

一个基于 Node.js 和 TypeScript 的后端框架，轻量、克制、简洁。

功能概览

• 基础设施 — 配置管理、日志、国际化、缓存
• Web 层 — 路由、参数校验、MVC
• 数据库 — MySQL、MongoDB
• 其他 — 周期任务

快速开始

npm i wok-server

import { startWebServer } from 'wok-server'

startWebServer({
  routers: {
    '/': async exchange => exchange.respondText('Hello world!')
  }
}).catch(e => {
  console.error('Start server failed', e)
})

启动后访问 http://localhost:8080 即可看到输出。

更多配置通过环境变量设置，详见完整文档。

AI 技能安装

wok-server 提供了 AI 技能，安装后可以让 AI 编程助手更好地理解和使用 wok-server 组件。

npx skills add peaktai/wok-server --all

国内用户访问 github 速度慢，可以使用 gitee 仓库地址来安装。

npx skills add https://gitee.com/tai/wok-server.git --all

为什么选择 Wok Server

核心原则只有一个：实用主义。每一个设计决策，都是在"简单透明"和"功能强大"之间选择了前者——不是因为做不到，而是因为选择不做。

纯对象配置，没有魔法

实体和数据库的映射就是一个普通对象，不需要学习装饰器、反射或任何框架特有的语法：

export interface User {
  id: string
  name: string
}

export const tableUser: Table<User> = {
  tableName: 'user',
  id: 'id',
  columns: ['name']
}

所有信息一目了然，出问题直接看这一个文件。不需要理解隐式的元数据系统，AI 和人类都容易理解。

显式优于隐式

读写分离、数据源选择都由代码显式决定，不会出现"写后读到旧数据"的意外：

const masterMgr = getMysqlManager('master')
const slaveMgr = getMysqlManager('slave')

// 写操作显式走主库
await masterMgr.insert(tableUser, { id: '001', nickname: 'jack' })

// 读操作显式走从库
const user = await slaveMgr.findById(tableUser, '001')

代码多一点，但完全可控。调试时清晰知道 SQL 发到了哪里。

纯 SQL 迁移，零学习成本

迁移就是按顺序执行的 SQL 文件，框架只负责"按顺序执行 + 版本记录"：

-- 001_init.sql
CREATE TABLE `user` (
  `id` varchar(32) NOT NULL PRIMARY KEY,
  `nickname` varchar(100) DEFAULT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 002_add_age.sql
ALTER TABLE `user` ADD COLUMN `age` int DEFAULT NULL AFTER `nickname`;

会 SQL 就会写迁移，完全透明，DBA 可直接审查，任何数据库特性都能用。

统一且直觉的 API

查询 API 遵循统一模式，学会一个，其他都是同一模式：

操作	单条	列表	分页	部分字段
查询	findFirst	find	paginate	findSelect / paginateSelect

条件查询用链式方法，不需要记忆操作符类名：

await mgr.findFirst(tableUser, c =>
  c.like('name', 'Bob%').gt('age', 18).between('score', 60, 100)
)

方法名就是自然语言，不需要 import 任何东西。

简单直接的类型系统

类型是约束工具，不是智力游戏：

// findById 返回 User | undefined
const user = await mgr.findById(tableUser, '001')

// insert 参数自动处理可选字段和元组表达式
await mgr.insert(tableUser, { id: '001', name: 'Bob' })

// findSelect 返回 Pick<User, K>
const list = await mgr.findSelect(tableUser, ['id', 'name'])

没有复杂的条件类型、映射类型体操或 DeepPartial 等抽象概念。用简单的泛型参数实现类型安全，配合 IDE 智能补全，开发效率高。

函数式为主，学习成本低

以函数式风格为主，少量面向对象，保持克制，不引入代理、装饰器等增强技术。轻量封装，兼容第三方 HTTP 生态。注释即文档，方法及参数均有详细说明。内置国际化支持，可扩展多语言。

对 AI 编程友好

wok-server 的简单透明设计，在 AI 辅助编程时代有天然优势：

• 纯对象配置 = AI 容易理解上下文，不需要理解框架特有的元数据系统
• 显式调用 = AI 从代码本身就能理解意图，不需要追踪隐式的配置
• 纯 SQL 迁移 = AI 直接生成可执行代码，没有生成步骤、没有交互、没有黑盒转换
• 无关联 ORM 自动加载 = AI 写 join 时必须显式写 SQL，性能问题更容易从 SQL 本身识别
• 统一的元组表达式 = AI 学习一次模式，到处复用，不容易混淆