zenweb 6.4.0 → 6.6.0

package/README.md

@@ -1,135 +1,172 @@
 # ZenWeb
 
-Modular lightweight web framework based on Koa
+基于 Koa 的模块化轻量级 Web 框架。
 
-## Document
+## 特性
+
+- **开箱即用** - `create()` 整合多个模块，无需逐个安装
+- **全局 Helper** - `$body/$query/$param/$log` 在请求期间任意位置可用
+- **装饰器驱动** - TypeScript 装饰器实现控制器路由和依赖注入
+- **统一响应** - `fail()` 处理业务错误，控制器 return 自动输出
+
+## 文档
 
 [ZenWeb 文档](https://zenweb.node.ltd)
 
-## Install
+- 创建新项目 → 阅读 `TEMPLATE.md`
+
+## 安装
 
 ```bash
-# for production
 npm i zenweb
 
-# for development
+# 开发依赖
 npm i -D dotenv typescript rimraf tsc-watch
 ```
 
-## Project Code
-
-edit `package.json` file at `scripts`:
-
-```json
-"scripts": {
-  "start": "node --enable-source-maps app",
-  "dev": "rimraf app && tsc-watch --onSuccess \"npm run dev-start\"",
-  "dev-start": "node -r dotenv/config --enable-source-maps app",
-  "build": "rimraf app && tsc"
-}
-```
+## TypeScript 配置（必需）
 
-create `tsconfig.json` file
+装饰器功能需要以下配置：
 
 ```json
 {
-  {
   "compilerOptions": {
     "experimentalDecorators": true,
     "emitDecoratorMetadata": true,
     "target": "ES2020",
-    "module": "commonjs",
-    "types": [ "node" ],
-    "esModuleInterop": true,
-    "strict": true,
-    "sourceMap": true,
-    "newLine": "lf",
-    "rootDir": "src",
-    "outDir": "app"
-  },
-  "include": ["src/**/*"]
+    "module": "commonjs"
+  }
 }
 ```
 
-create `.env` file
+## 快速开始
 
-```bash
-APP_NAME=myweb
-NODE_ENV=development
-DEBUG=*
+```ts
+import { create } from 'zenweb';
+
+create({
+  controller: {
+    discoverPaths: ['./controller'],
+    autoControllerPrefix: true,
+  },
+}).start();
 ```
 
-create `src/index.ts` file
+## 控制器
+
+文件名映射为路由前缀（开启 `autoControllerPrefix`）：
 
 ```ts
-import { create } from 'zenweb';
-create().start();
+// 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();
+  }
+}
 ```
 
-create `src/service/hello.ts` file
+## Service
+
+Service 类添加 `@Injectable` 注解，作用域为请求级：
 
 ```ts
+// service/user.ts
 import { Injectable, Context } from 'zenweb';
 
 @Injectable
-export class HelloService {
-  constructor(
-    private ctx: Context,
-  ){}
+export class UserService {
+  constructor(private ctx: Context) {}
 
-  getIp() {
-    return this.ctx.ip;
+  create() {
+    return { ip: this.ctx.ip };
   }
 }
 ```
 
-create `src/controller/hello.ts` file
+## 全局 Helper
+
+请求期间无需注入，直接使用：
 
 ```ts
-import { Get } from 'zenweb';
-import { HelloService } from '../service/hello';
-
-export class HelloController {
-  @Get()
-  index(service: HelloService) {
-    const ip = service.getIp();
-    return `Hello ZenWeb! ${ip}`;
-  }
-}
+// Body 解析
+await $body.get({ name: '!string', age: 'int' });
+
+// Query 参数
+await $query.get({ id: '!int', keyword: 'trim' });
+
+// 路由参数
+const { id } = $ctx.params;
+
+// 日志
+$log.info('message');
 ```
 
-start server:
+## 错误处理
 
-```bash
-npm run dev
+`fail()` 用于预期业务错误：
+
+```ts
+import { fail } from 'zenweb';
+
+if (!user) {
+  fail('用户不存在');  // 返回错误响应，终止执行
+}
 ```
 
+非预期错误（代码 bug、数据库连接失败等）直接抛出 Error，框架返回 500。
+
 ## 集成模块
-- [core](https://www.npmjs.com/package/@zenweb/core) 核心
-- [meta](https://www.npmjs.com/package/@zenweb/meta) 运行基本信息，例如：请求耗时
-- [inject](https://www.npmjs.com/package/@zenweb/inject) 注入支持
-- [router](https://www.npmjs.com/package/@zenweb/router) 路由支持
-- [log](https://www.npmjs.com/package/@zenweb/log) 日志支持
-- [result](https://www.npmjs.com/package/@zenweb/result) 统一结果返回，成功或失败
-- [messagecode](https://www.npmjs.com/package/@zenweb/messagecode) 统一错误消息格式化
-- [controller](https://www.npmjs.com/package/@zenweb/controller) 类控制器支持
-- [helper](https://www.npmjs.com/package/@zenweb/helper) 输入数据验证助手
-- [body](https://www.npmjs.com/package/@zenweb/body) 请求主体解析，JSON、Form
 
-集成模块默认开启，可以通过设置配置项为 **false** 关闭
+已集成，无需单独安装：
 
+| 模块 | 作用 |
+|------|------|
+| `@zenweb/core` | 核心应用 |
+| `@zenweb/inject` | 依赖注入 |
+| `@zenweb/router` | Trie 路由 |
+| `@zenweb/controller` | 控制器装饰器 |
+| `@zenweb/body` | Body 解析 |
+| `@zenweb/helper` | 参数验证 |
+| `@zenweb/result` | 结果处理 |
+| `@zenweb/log` | 日志 |
+| `@zenweb/meta` | 请求元信息 |
+| `@zenweb/messagecode` | 错误消息格式化 |
+
+集成模块默认开启，可通过配置项设为 `false` 关闭。
 
 ## 可选模块
-- [cors](https://www.npmjs.com/package/@zenweb/cors) 跨域支持
-- [sentry](https://www.npmjs.com/package/@zenweb/sentry) sentry 错误收集
-- [metric](https://www.npmjs.com/package/@zenweb/metric) 生产运行健康信息收集
-- [validation](https://www.npmjs.com/package/@zenweb/validation) JSONSchema 验证
-- [mysql](https://www.npmjs.com/package/@zenweb/mysql) MySQL 数据库支持
-- [orm](https://www.npmjs.com/package/@zenweb/orm) ORM 支持
-- [template](https://www.npmjs.com/package/@zenweb/template) 模版渲染
-- [schedule](https://www.npmjs.com/package/@zenweb/schedule) 定时任务
-- [form](https://www.npmjs.com/package/@zenweb/form) 统一表单（多用于后台）
-- [grid](https://www.npmjs.com/package/@zenweb/grid) 统一表格（多用于后台）
-- [upload](https://www.npmjs.com/package/@zenweb/upload) 文件上传支持
-- [xmlBody](https://www.npmjs.com/package/@zenweb/xml-body) XML Body 解析
-- [msgpack](https://www.npmjs.com/package/@zenweb/msgpack) MessagePack 输出
+
+| 模块 | 作用 |
+|------|------|
+| `@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` | 数据表渲染 |

package/TEMPLATE.md

@@ -0,0 +1,231 @@
+# TEMPLATE.md
+
+AI 编程脚手架模板 - 创建 ZenWeb 项目时使用此结构。
+
+---
+
+## 项目结构
+
+```
+project/
+├── src/
+│   ├── index.ts           # 应用入口
+│   ├── controller/        # 控制器目录
+│   │   └── index.ts       # 根路由控制器
+│   ├── service/           # 服务目录
+│   ├── message-codes.json # 错误消息定义（可选）
+│   └── types.ts           # 类型定义（可选）
+├── package.json
+├── tsconfig.json
+├── .env                   # 开发环境变量
+└── .gitignore
+```
+
+---
+
+## package.json
+
+```json
+{
+  "name": "myapp",
+  "version": "1.0.0",
+  "main": "app/index.js",
+  "scripts": {
+    "build": "rimraf app && tsc",
+    "start": "node --enable-source-maps app",
+    "dev-start": "node --env-file=.env --enable-source-maps app",
+    "dev": "rimraf app && tsc-watch --onSuccess \"npm run dev-start\""
+  },
+  "dependencies": {
+    "zenweb": "^6.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^16",
+    "rimraf": "^6",
+    "typescript": "^6",
+    "tsc-watch": "^6"
+  }
+}
+```
+
+---
+
+## tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "target": "ES2020",
+    "module": "commonjs",
+    "types": ["node"],
+    "esModuleInterop": true,
+    "strict": true,
+    "sourceMap": true,
+    "rootDir": "src",
+    "outDir": "app"
+  },
+  "include": ["src/**/*"]
+}
+```
+
+---
+
+## .env（开发环境）
+
+```bash
+APP_NAME=myapp
+NODE_ENV=development
+DEBUG=*
+LOG_DIR=./logs
+```
+
+---
+
+## .gitignore
+
+```
+.env
+app/
+logs/
+node_modules/
+```
+
+---
+
+## src/index.ts（入口文件）
+
+```ts
+import { create } from 'zenweb';
+
+create({
+  controller: {
+    discoverPaths: ['./controller'],
+    autoControllerPrefix: true,
+  },
+}).start();
+```
+
+---
+
+## src/controller/index.ts（根路由）
+
+```ts
+export class IndexController {
+  index() {
+    return 'Hello ZenWeb!';
+  }
+}
+```
+
+---
+
+## src/controller/user.ts（示例控制器）
+
+```ts
+import { Get, Post, Context, $param, $body } from 'zenweb';
+import { UserService } from '../service/user';
+
+export class UserController {
+  constructor(private ctx: Context) {}
+
+  @Get()
+  list(service: UserService) {
+    return service.list();
+  }
+
+  @Get('/:id')
+  async detail() {
+    const { id } = await $param.get({ id: '!int' });
+    return { id };
+  }
+
+  @Post()
+  async create(service: UserService) {
+    const data = await $body.get({ name: '!string', email: 'string' });
+    return service.create(data);
+  }
+}
+```
+
+---
+
+## src/service/user.ts（示例服务）
+
+```ts
+import { Injectable, Context } from 'zenweb';
+
+@Injectable
+export class UserService {
+  constructor(private ctx: Context) {}
+
+  list() {
+    return [];
+  }
+
+  create(data: { name: string; email?: string }) {
+    return { ...data, ip: this.ctx.ip };
+  }
+}
+```
+
+---
+
+## src/message-codes.json（错误消息）
+
+```json
+{
+  "user.notfound": "用户不存在",
+  "user.login.fail": "登录失败: {reason}"
+}
+```
+
+---
+
+## 命名规范
+
+| 类型 | 文件名 | 导出名 |
+|------|--------|--------|
+| 控制器 | `{name}.ts` | `{Name}Controller` |
+| 服务 | `{name}.ts` | `{Name}Service` |
+| 类型定义 | `types.ts` | 自由命名 |
+
+---
+
+## 路由映射规则（autoControllerPrefix: true）
+
+| 文件路径 | 路由前缀 |
+|----------|----------|
+| `controller/index.ts` | `/` |
+| `controller/user.ts` | `/user` |
+| `controller/admin/index.ts` | `/admin` |
+| `controller/admin/user.ts` | `/admin/user` |
+
+---
+
+## 可选模块扩展
+
+询问用户是否需要以下可选模块，如需要则安装并阅读对应模块的 AGENTS.md 文档进行配置：
+
+| 模块 | 作用 |
+|------|------|
+| `@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` | MessagePack 输出 |
+| `@zenweb/ratelimit` | 请求量控制（防CC攻击） |
+| `@zenweb/websocket` | WebSocket 支持 |
+| `@zenweb/xml-body` | XML Body 解析 |
+| `@zenweb/form` | 表单构建 |
+| `@zenweb/grid` | 数据表渲染 |
+
+**配置指引：** 安装后阅读 `node_modules/{模块名}/README.md` 获取详细配置说明。

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "zenweb",
-  "version": "6.4.0",
+  "version": "6.6.0",
   "description": "Modular lightweight web framework based on Koa",
   "main": "dist/index.js",
   "typings": "./dist/index.d.ts",
   "files": [
-    "AGENTS.md",
+    "TEMPLATE.md",
     "dist"
   ],
   "scripts": {
@@ -28,16 +28,16 @@
   "license": "MIT",
   "homepage": "https://zenweb.node.ltd",
   "dependencies": {
-    "@zenweb/body": "^5.4.1",
-    "@zenweb/controller": "^6.4.0",
-    "@zenweb/core": "^5.3.0",
-    "@zenweb/helper": "^5.4.0",
-    "@zenweb/inject": "^5.4.0",
-    "@zenweb/log": "^5.2.0",
-    "@zenweb/messagecode": "^5.5.0",
-    "@zenweb/meta": "^5.2.0",
-    "@zenweb/result": "^5.3.0",
-    "@zenweb/router": "^6.5.0"
+    "@zenweb/body": "^5.5.0",
+    "@zenweb/controller": "^6.6.1",
+    "@zenweb/core": "^5.5.0",
+    "@zenweb/helper": "^5.6.0",
+    "@zenweb/inject": "^5.5.0",
+    "@zenweb/log": "^5.4.0",
+    "@zenweb/messagecode": "^5.6.0",
+    "@zenweb/meta": "^5.3.0",
+    "@zenweb/result": "^5.5.0",
+    "@zenweb/router": "^6.6.0"
   },
   "devDependencies": {
     "@types/node": "^16.18.126",

package/AGENTS.md

@@ -1,276 +0,0 @@
-# AGENTS.md
-
-AI 专用 API 参考文档，随 npm 包发布，供 AI 编程助手使用。
-
-## 模块概述
-
-ZenWeb 是基于 Koa 的模块化轻量级 Web 框架。`create()` 函数整合了多个常用模块，简化新项目配置，无需单独安装已集成模块。各模块详细用法请参阅其各自的 AGENTS.md 文件。
-
-## 导出
-
-```ts
-// 主函数
-export { create, Core, CreateOptions };
-
-// 依赖注入
-export { Init, Inject, Injectable, $getInstance } from '@zenweb/inject';
-
-// 路由
-export { Router, RouterMethod, RouterPath } from '@zenweb/router';
-
-// 结果处理
-export { ResultFail, fail } from '@zenweb/result';
-
-// 控制器装饰器
-export {
-  Controller,
-  Mapping,
-  Get,
-  Post,
-  Put,
-  Patch,
-  Delete,
-  All,
-} from '@zenweb/controller';
-
-// Core 相关
-export {
-  Next,
-  SetupFunction,
-  Context,
-  Middleware,
-  SetupHelper,
-  $getCore,
-  $getContext,
-  $core,
-  $ctx,
-  $debug,
-  createDebug,
-} from '@zenweb/core';
-
-// Body 解析
-export {
-  Body,
-  ObjectBody,
-  BodyHelper,
-  RawBody,
-  TextBody,
-  useBodyParser,
-  $body,
-  $getTextBody,
-  $getRawBody,
-  $getObjectBody,
-} from '@zenweb/body';
-
-// Helper
-export {
-  QueryHelper,
-  TypeCastHelper,
-  ParamHelper,
-  $param,
-  $query,
-  $helperBase,
-} from '@zenweb/helper';
-
-// Log
-export {
-  $log,
-  $getLogger,
-  Logger,
-} from '@zenweb/log';
-```
-
-## create(options?: CreateOptions)
-
-创建应用实例，自动安装集成模块。
-
-```ts
-import { create } from 'zenweb';
-
-create({
-  // 全局实例，默认 true
-  global: true,
-
-  // 模块配置，设为 false 可禁用
-  core: { env: 'production', keys: ['secret'] },
-  meta: { showVersion: true, traceId: true },
-  inject: false,  // 禁用注入
-  log: { dir: '/var/log/app' },
-  router: false,  // 禁用路由
-  messagecode: { codes: { 'error': '错误' } },
-  body: { limit: 1024 * 1024 },
-  result: { failCode: 1, failStatus: 200 },
-  helper: { page: { defaultLimit: 20 } },
-  controller: { discoverPaths: ['./controller'], autoControllerPrefix: true },
-})
-.start();
-```
-
-## CreateOptions 类型
-
-```ts
-interface CreateOptions {
-  global?: boolean;            // 全局实例，默认 true
-  core?: CoreOption;           // @zenweb/core 配置
-  inject?: false;              // 禁用 @zenweb/inject
-  meta?: MetaOption | false;   // @zenweb/meta 配置或禁用
-  log?: LogOption | false;     // @zenweb/log 配置或禁用
-  router?: false;              // 禁用 @zenweb/router
-  messagecode?: MessageCodeOption | false;
-  body?: BodyOption | false;
-  result?: ResultOption | false;
-  helper?: HelperOption | false;
-  controller?: ControllerSetupOption | false;
-}
-```
-
-## 集成模块列表
-
-以下模块已集成，无需单独安装。详细 API 请参阅各模块 AGENTS.md：
-
-| 模块 | 作用 | 默认状态 |
-|------|------|----------|
-| `@zenweb/core` | 核心应用和上下文管理 | 启用 |
-| `@zenweb/meta` | 请求元信息（耗时、请求ID、追踪ID） | 启用 |
-| `@zenweb/inject` | 依赖注入系统 | 启用 |
-| `@zenweb/router` | Trie 高性能路由 | 启用 |
-| `@zenweb/log` | 请求日志 | 启用 |
-| `@zenweb/result` | 统一成功/失败响应处理 | 启用 |
-| `@zenweb/messagecode` | 错误消息代码格式化 | 启用 |
-| `@zenweb/controller` | 类控制器装饰器路由 | 启用 |
-| `@zenweb/helper` | 输入验证和类型转换助手 | 启用 |
-| `@zenweb/body` | 请求主体解析（JSON、Form） | 启用 |
-
-## 可选扩展模块
-
-以下模块需单独安装：
-
-- `@zenweb/cors` - 跨域支持
-- `@zenweb/sentry` - Sentry 错误收集
-- `@zenweb/metric` - 生产运行健康信息
-- `@zenweb/validation` - JSONSchema 验证
-- `@zenweb/mysql` - MySQL 数据库
-- `@zenweb/orm` - ORM 支持
-- `@zenweb/template` - 模板渲染
-- `@zenweb/schedule` - 定时任务
-- `@zenweb/form` - 统一表单
-- `@zenweb/grid` - 统一表格
-- `@zenweb/upload` - 文件上传
-- `@zenweb/xml-body` - XML Body 解析
-- `@zenweb/msgpack` - MessagePack 输出
-
-## 全局 Helper ($前缀)
-
-基于 AsyncLocalStorage，请求期间可在任意位置调用：
-
-```ts
-// Body 解析和类型转换
-await $body.get({ name: 'string', age: '!int' });
-await $body.page({ limit: 10 });
-await $getObjectBody();
-
-// Query 和 Param
-await $query.get({ id: '!int' });
-await $query.page();
-await $param.data();
-
-// 日志
-$log.info('message');
-$log.child({ extra: 'field' }).debug('debug msg');
-
-// 上下文和 Core
-const ctx = $ctx;
-const core = $getCore();
-const ip = $ctx.ip;
-```
-
-## 依赖注入
-
-使用 TypeScript 装饰器（需 `experimentalDecorators` 和 `emitDecoratorMetadata`）：
-
-```ts
-@Injectable                        // 请求级服务（默认）
-@Injectable('singleton')           // 单例服务
-
-class MyService {
-  constructor(private ctx: Context) {}  // 自动注入 Context
-
-  @Init                             // 初始化方法
-  init(other: OtherService) {}
-
-  @Inject other!: OtherService;    // 属性注入
-}
-
-// 控制器方法参数自动注入
-@Get()
-handler(service: MyService) {}
-```
-
-## 控制器模式
-
-```ts
-export class UserController {
-  @Get()              // GET /user (方法名作为路径)
-  index() { return 'list'; }
-
-  @Get('/:id')        // GET /user/:id
-  detail() {
-    return $param.data();  // 获取路由参数
-  }
-
-  @Post()             // POST /user
-  create() {
-    return $body.get({ name: '!string', email: 'string' });
-  }
-
-  @Put('/:id')
-  update() {}
-
-  @Delete('/:id')
-  remove() {}
-}
-```
-
-`controller.discoverPaths` 配置控制器目录，`autoControllerPrefix: true` 自动将文件路径映射为路由前缀。
-
-## 错误处理
-
-```ts
-import { fail } from 'zenweb';
-
-// 立即终止并返回错误响应
-fail('错误消息');
-fail(400, '参数错误');
-fail({ code: 123, message: '自定义错误', status: 200 });
-
-// controller 方法 return 值自动包装为成功响应
-```
-
-## TypeScript 配置要求
-
-```json
-{
-  "compilerOptions": {
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
-    "target": "ES2020",
-    "module": "commonjs",
-    "strict": true
-  }
-}
-```
-
-## 各模块 AGENTS.md 位置
-
-安装后可读取以下文件获取详细 API：
-
-- `node_modules/@zenweb/core/AGENTS.md`
-- `node_modules/@zenweb/meta/AGENTS.md`
-- `node_modules/@zenweb/inject/AGENTS.md`
-- `node_modules/@zenweb/router/AGENTS.md`
-- `node_modules/@zenweb/log/AGENTS.md`
-- `node_modules/@zenweb/result/AGENTS.md`
-- `node_modules/@zenweb/messagecode/AGENTS.md`
-- `node_modules/@zenweb/controller/AGENTS.md`
-- `node_modules/@zenweb/helper/AGENTS.md`
-- `node_modules/@zenweb/body/AGENTS.md`