# wok-server

**Repository Path**: tai/wok-server

## Basic Information

- **Project Name**: wok-server
- **Description**: 一个基于 NodeJs 和 TypeScript 的后端框架，轻量级、克制、简洁。A lightweight, restrained, and concise backend framework based on Node.js and TypeScript.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 9
- **Forks**: 3
- **Created**: 2023-12-29
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

[English](./README.en.md) | 简体中文

# Wok Server

[![npm version](https://img.shields.io/npm/v/wok-server)](https://www.npmjs.com/package/wok-server)
[![license](https://img.shields.io/npm/l/wok-server)](https://github.com/nicepkg/wok-server/blob/master/LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)

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

## 功能概览

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

## 快速开始

```bash
npm i wok-server
```

```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` 即可看到输出。

更多配置通过环境变量设置，详见[完整文档](https://gitee.com/tai/wok-server/blob/master/documentation/zh-cn/index.md)。

### AI 技能安装

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


```bash
npx skills add peaktai/wok-server --all
```

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

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

## 为什么选择 Wok Server

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

### 纯对象配置，没有魔法

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

```ts
export interface User {
  id: string
  name: string
}

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

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

### 显式优于隐式

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

```ts
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 文件，框架只负责"按顺序执行 + 版本记录"：

```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` |

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

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

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

### 简单直接的类型系统

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

```ts
// 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 学习一次模式，到处复用，不容易混淆