ZenWeb

基于 Koa 的模块化轻量级 Web 框架。

特性

• 开箱即用 - create() 整合多个模块，无需逐个安装
• 全局 Helper - $body/$query/$param/$log 在请求期间任意位置可用
• 装饰器驱动 - TypeScript 装饰器实现控制器路由和依赖注入
• 统一响应 - fail() 处理业务错误，控制器 return 自动输出

文档

ZenWeb 文档

安装

npm i zenweb

# 开发依赖
npm i -D dotenv typescript rimraf tsc-watch

TypeScript 配置（必需）

装饰器功能需要以下配置：

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES2020",
    "module": "commonjs"
  }
}

快速开始

import { create } from 'zenweb';

create({
  controller: {
    discoverPaths: ['./controller'],
    autoControllerPrefix: true,
  },
}).start();

控制器

文件名映射为路由前缀（开启 autoControllerPrefix）：

// controller/user.ts → /user
import { Get, Post, Context } from 'zenweb';
import { UserService } from '../service/user';

export class UserController {
  constructor(private ctx: Context) {}

  @Get()               // GET /user
  list() { return []; }

  @Get('/:id')         // GET /user/:id
  detail() {
    const { id } = this.ctx.params;
    return { id };
  }

  @Post()              // POST /user
  create(service: UserService) {
    return service.create();
  }
}

Service

Service 类添加 @Injectable 注解，作用域为请求级：

// service/user.ts
import { Injectable, Context } from 'zenweb';

@Injectable
export class UserService {
  constructor(private ctx: Context) {}

  create() {
    return { ip: this.ctx.ip };
  }
}

全局 Helper

请求期间无需注入，直接使用：

// Body 解析
await $body.get({ name: '!string', age: 'int' });

// Query 参数
await $query.get({ id: '!int', keyword: 'trim' });

// 路由参数
const { id } = $ctx.params;

// 日志
$log.info('message');

错误处理

fail() 用于预期业务错误：

import { fail } from 'zenweb';

if (!user) {
  fail('用户不存在');  // 返回错误响应，终止执行
}

非预期错误（代码 bug、数据库连接失败等）直接抛出 Error，框架返回 500。

集成模块

已集成，无需单独安装：

| 模块 | 作用 | |------|------| | @zenweb/core | 核心应用 | | @zenweb/inject | 依赖注入 | | @zenweb/router | Trie 路由 | | @zenweb/controller | 控制器装饰器 | | @zenweb/body | Body 解析 | | @zenweb/helper | 参数验证 | | @zenweb/result | 结果处理 | | @zenweb/log | 日志 | | @zenweb/meta | 请求元信息 | | @zenweb/messagecode | 错误消息格式化 |

集成模块默认开启，可通过配置项设为 false 关闭。

可选模块

| 模块 | 作用 | |------|------| | @zenweb/cors | 跨域支持 | | @zenweb/sentry | Sentry 错误收集 | | @zenweb/metric | 运行健康信息 | | @zenweb/mysql | MySQL 数据库 | | @zenweb/tenant | 多租户数据库连接池 | | @zenweb/orm | ORM 支持 | | @zenweb/template | 模版渲染 | | @zenweb/schedule | 定时任务 | | @zenweb/upload | 文件上传 | | @zenweb/cache | Redis 缓存支持 | | @zenweb/cache-opt | Redis 缓存优化 | | @zenweb/msgpack | @zenweb/result MessagePack 支持 | | @zenweb/ratelimit | 请求量控制（防CC攻击） | | @zenweb/websocket | WebSocket 支持（分布式会话共享） | | @zenweb/xml-body | @zenweb/body XML 解析支持 | | @zenweb/form | 表单构建 | | @zenweb/grid | 数据表渲染 |