zenweb 6.4.0 → 6.5.0

package/AGENTS.md

@@ -1,276 +1,419 @@
 # AGENTS.md
 
-AI 专用 API 参考文档，随 npm 包发布，供 AI 编程助手使用。
+AI 专用 API 参考文档，供 AI 编程助手使用。
 
-## 模块概述
+**使用指引：**
+- 创建新项目 → 阅读 `TEMPLATE.md`
+- 理解现有代码 → 阅读 `AGENTS.md`
 
-ZenWeb 是基于 Koa 的模块化轻量级 Web 框架。`create()` 函数整合了多个常用模块，简化新项目配置，无需单独安装已集成模块。各模块详细用法请参阅其各自的 AGENTS.md 文件。
+---
 
-## 导出
+## 概述
+
+ZenWeb 是基于 Koa 的模块化轻量级 Web 框架。`create()` 整合多个模块，开箱即用。
+
+**核心设计：**
+- AsyncLocalStorage 全局 Helper，请求期间任意位置可用
+- TypeScript 装饰器驱动的控制器和依赖注入
+- 统一的成功/失败响应格式
+
+---
+
+## 快速启动
+
+```ts
+import { create } from 'zenweb';
+
+create({
+  controller: {
+    discoverPaths: ['./controller'],
+    autoControllerPrefix: true,
+  },
+}).start();
+```
+
+---
+
+## TypeScript 配置（必需）
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "target": "ES2020",
+    "module": "commonjs"
+  }
+}
+```
+
+---
+
+## 导出概览
 
 ```ts
 // 主函数
-export { create, Core, CreateOptions };
+export { create, Core };
 
 // 依赖注入
-export { Init, Inject, Injectable, $getInstance } from '@zenweb/inject';
+export { Injectable, Init, Inject, $getInstance } from '@zenweb/inject';
+
+// 控制器装饰器
+export { Controller, Get, Post, Put, Patch, Delete, All, Mapping } from '@zenweb/controller';
 
 // 路由
 export { Router, RouterMethod, RouterPath } from '@zenweb/router';
 
 // 结果处理
-export { ResultFail, fail } from '@zenweb/result';
+export { fail, ResultFail } 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';
+// 全局 Helper（$前缀，AsyncLocalStorage）
+export { $ctx, $getCore, $getContext, $core, $debug, createDebug } from '@zenweb/core';
+export { $body, $getObjectBody, $getRawBody, $getTextBody } from '@zenweb/body';
+export { $param, $query, $helperBase } from '@zenweb/helper';
+export { $log, $getLogger, Logger } from '@zenweb/log';
+
+// Core 类型
+export { Context, Middleware, Next, SetupFunction, SetupHelper } from '@zenweb/core';
 ```
 
-## create(options?: CreateOptions)
+---
+
+## 控制器
 
-创建应用实例，自动安装集成模块。
+控制器类自动标记为请求级注入，方法参数自动注入。
 
 ```ts
-import { create } from 'zenweb';
+// controller/user.ts - 文件名映射为路由前缀 /user
+export class UserController {
+  @Get()              // GET /user
+  list() { return []; }
 
-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();
+  @Get('/:id')        // GET /user/:id
+  async detail(ctx: Context, service: UserService) {
+    const { id } = await $param.get({ id: '!int' });
+    return service.getById(id);
+  }
+
+  @Post()             // POST /user
+  async create() {
+    return await $body.get({ name: '!string', email: 'string' });
+  }
+}
 ```
 
-## CreateOptions 类型
+**@Controller 装饰器（可选）：**
+```ts
+@Controller({ prefix: '/admin' })      // 绝对前缀
+@Controller({ prefix: 'manage' })      // 相对前缀，拼接自动前缀
+@Controller({ middleware: [authFn] })  // 控制器级中间件
+```
+
+**生命周期：**
+```ts
+@Controller()
+export class MyController {
+  constructor(private ctx: Context) {}  // 自动注入
+
+  @Init
+  init() { /* 实例化后调用 */ }
+}
+```
 
+**单例控制器**（适用于无状态场景）：
 ```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;
+@Controller()
+@Injectable('singleton')
+export class CounterController {
+  counter = 0;
+  @Get() index() { return ++this.counter; }
 }
 ```
 
-## 集成模块列表
-
-以下模块已集成，无需单独安装。详细 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，请求期间可在任意位置调用：
+---
+
+## Router 直接使用（非控制器场景）
+
+不使用控制器装饰器时，可直接通过 `app.router` 注册路由：
 
 ```ts
-// Body 解析和类型转换
-await $body.get({ name: 'string', age: '!int' });
-await $body.page({ limit: 10 });
-await $getObjectBody();
+import { create, Router } from 'zenweb';
 
-// Query 和 Param
-await $query.get({ id: '!int' });
-await $query.page();
-await $param.data();
+const app = create({
+  controller: false,  // 禁用控制器自动发现
+});
 
-// 日志
-$log.info('message');
-$log.child({ extra: 'field' }).debug('debug msg');
+// 直接注册路由
+app.router.get('/hello', ctx => {
+  ctx.body = 'Hello';
+});
+
+// 子路由
+const subRouter = new Router({ prefix: '/admin' });
+subRouter.get('/dashboard', ctx => ctx.body = 'dashboard');
+app.router.add(subRouter);
 
-// 上下文和 Core
-const ctx = $ctx;
-const core = $getCore();
-const ip = $ctx.ip;
+app.start();
 ```
 
-## 依赖注入
+---
+
+## 全局中间件
 
-使用 TypeScript 装饰器（需 `experimentalDecorators` 和 `emitDecoratorMetadata`）：
+通过 `setup.middleware()` 添加应用级中间件：
 
 ```ts
-@Injectable                        // 请求级服务（默认）
-@Injectable('singleton')           // 单例服务
+import { create } from 'zenweb';
+
+const app = create();
 
-class MyService {
-  constructor(private ctx: Context) {}  // 自动注入 Context
+// Core 级中间件（所有请求）
+app.setup(function myMiddleware(setup) {
+  setup.middleware(async (ctx, next) => {
+    ctx.set('X-Custom', 'value');
+    return next();
+  });
+});
+```
+
+---
 
-  @Init                             // 初始化方法
-  init(other: OtherService) {}
+## 消息代码（MessageCode）
 
-  @Inject other!: OtherService;    // 属性注入
+用于错误消息格式化，**优先使用统一定义文件**：
+
+```ts
+// message-codes.json（推荐）
+{
+  "user.notfound": "用户不存在",
+  "user.login.fail": "登录失败: {reason}",
+  "error.system": "系统错误"
 }
 
-// 控制器方法参数自动注入
-@Get()
-handler(service: MyService) {}
+// 或 message-codes.ts
+export default {
+  'user.notfound': '用户不存在',
+  'user.login.fail': '登录失败: {reason}',
+};
+
+// 配置（默认自动加载 ./message-codes.json）
+create({
+  messagecode: {
+    autoLoadFilenames: ['./message-codes.json', './codes/custom.ts'],
+  },
+});
+
+// 使用
+ctx.messageCodeResolver.format('user.login.fail', { reason: '密码错误' });
+ctx.messageCodeResolver.fail('user.notfound');  // 直接抛出 fail 异常
 ```
 
-## 控制器模式
+---
 
-```ts
-export class UserController {
-  @Get()              // GET /user (方法名作为路径)
-  index() { return 'list'; }
+## 依赖注入
 
-  @Get('/:id')        // GET /user/:id
-  detail() {
-    return $param.data();  // 获取路由参数
-  }
+**Service 类默认添加 @Injectable 注解**（将 service 类的作用域设置为 request）：
 
-  @Post()             // POST /user
-  create() {
-    return $body.get({ name: '!string', email: 'string' });
-  }
+```ts
+@Injectable                    // Service 类必须添加注解！
+export class UserService {
+  constructor(private ctx: Context, private db: DatabaseService) {}  // 自动注入
+}
+```
 
-  @Put('/:id')
-  update() {}
+**无法用构造器注入时，使用 @Inject 属性注入**：
 
-  @Delete('/:id')
-  remove() {}
+```ts
+@Injectable
+export class MyService {
+  constructor(private ctx: Context) {}  // 构造器注入
+  
+  @Inject private cache!: CacheService;  // 属性注入（后注入）
 }
 ```
 
-`controller.discoverPaths` 配置控制器目录，`autoControllerPrefix: true` 自动将文件路径映射为路由前缀。
+**作用域：**
+```ts
+@Injectable                    // 请求级（默认）
+@Injectable('singleton')       // 单例，不可注入 request 级依赖
+@Injectable('prototype')       // 每次注入创建新实例
+```
+
+---
+
+## 全局 Helper
+
+请求期间任意位置可用，无需注入：
+
+```ts
+// Body
+await $body.get({ name: '!string', age: 'int' });
+await $body.page({ limit: 10 });
+
+// Query
+await $query.get({ id: '!int', keyword: 'trim' });
+await $query.page({ allowOrder: ['id'] });
+
+// Param（路由参数）
+$ctx.params;                  // 原始参数对象 { id: '123' }
+await $param.get({ id: '!int' });  // 带类型转换
+
+// 日志
+$log.info('message');
+$log.child({ requestId: 'abc' }).debug('with context');
+
+// 上下文
+$ctx.ip; $ctx.path; $ctx.header;
+$getCore().name;
+```
+
+---
 
 ## 错误处理
 
+**fail() 用于预期业务错误**（给用户看的错误）：
+
 ```ts
 import { fail } from 'zenweb';
 
-// 立即终止并返回错误响应
-fail('错误消息');
+// 业务预期的错误，如参数验证失败、用户不存在等
+fail('用户不存在');
 fail(400, '参数错误');
-fail({ code: 123, message: '自定义错误', status: 200 });
-
-// controller 方法 return 值自动包装为成功响应
+fail({ code: 10001, message: '余额不足' });
 ```
 
-## TypeScript 配置要求
+**非预期错误使用自定义异常**（如数据库连接失败、代码 bug），不要用 fail()：
 
-```json
-{
-  "compilerOptions": {
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
-    "target": "ES2020",
-    "module": "commonjs",
-    "strict": true
+```ts
+class DatabaseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'DatabaseError';
   }
 }
+
+// 非预期错误，框架会返回 500 并隐藏详情
+throw new DatabaseError('连接失败');
+```
+
+**控制器 return 值通过 ctx.success(data) 输出，默认不做包装：**
+```ts
+return { name: 'test' };  // → { name: 'test' }
+
+// 如需包装需在 create() 中配置
+create({
+  result: {
+    successWrap: (ctx, data) => ({ code: 0, data }),
+  },
+});
+```
+
+---
+
+## create() 配置
+
+```ts
+create({
+  global: true,            // 全局实例，默认 true
+  core: { keys: ['secret'] },
+  meta: false,             // 禁用模块
+  log: { dir: '/var/log' },
+  result: { failCode: 1, failStatus: 400 },
+  body: { limit: 1024 * 1024 },
+  helper: { page: { defaultLimit: 20 } },
+  controller: {
+    discoverPaths: ['./controller'],
+    autoControllerPrefix: true,
+  },
+})
+```
+
+---
+
+## 集成模块
+
+已集成，无需单独安装：
+
+| 模块 | 作用 |
+|------|------|
+| `@zenweb/core` | 核心应用 |
+| `@zenweb/inject` | 依赖注入 |
+| `@zenweb/router` | Trie 路由 |
+| `@zenweb/controller` | 控制器装饰器 |
+| `@zenweb/body` | Body 解析 |
+| `@zenweb/helper` | 参数验证 |
+| `@zenweb/result` | 结果处理 |
+| `@zenweb/log` | 日志 |
+| `@zenweb/meta` | 请求元信息 |
+| `@zenweb/messagecode` | 错误消息格式化 |
+
+**可选扩展：**
+
+| 模块 | 作用 |
+|------|------|
+| `@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` | 数据表渲染 |
+
+---
+
+## 类型转换语法
+
+```ts
+await $body.get({
+  name: '!string',    // 必填字符串
+  age: 'int',         // 可选整数
+  tags: 'string[]',   // 字符串数组
+  active: '!bool',    // 必填布尔
+  email: 'trim',      // 去空格
+});
 ```
 
-## 各模块 AGENTS.md 位置
+支持类型：`int`, `float`, `number`, `bool`, `string`, `trim`, `date`, `datetime`, `array`, `object`, `json`
+
+---
 
-安装后可读取以下文件获取详细 API：
+## 各模块详细文档
+
+详细 API 参阅各模块 AGENTS.md：
 
 - `node_modules/@zenweb/core/AGENTS.md`
-- `node_modules/@zenweb/meta/AGENTS.md`
 - `node_modules/@zenweb/inject/AGENTS.md`
+- `node_modules/@zenweb/controller/AGENTS.md`
+- `node_modules/@zenweb/body/AGENTS.md`
+- `node_modules/@zenweb/helper/AGENTS.md`
+- `node_modules/@zenweb/result/AGENTS.md`
 - `node_modules/@zenweb/router/AGENTS.md`
 - `node_modules/@zenweb/log/AGENTS.md`
-- `node_modules/@zenweb/result/AGENTS.md`
+- `node_modules/@zenweb/meta/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`
+
+---
+
+## AI 使用要点
+
+1. **已集成模块从 zenweb 导入**，可选模块（cors, mysql, orm 等）从各自模块导入
+   ```ts
+   import { Injectable, Context, fail } from 'zenweb';  // 集成模块
+   import { MySQL } from '@zenweb/mysql';               // 可选模块
+   ```
+2. 优先用全局 Helper `$body/$query/$param/$log`，比 DI 更简洁
+3. **Service 类必须添加 @Injectable 注解**，优先用构造器参数注入
+4. 必填字段用 `!` 前缀，避免空值问题
+5. 单例服务不可依赖 Context，用方法参数传递
+6. 控制器文件名映射路由前缀（`autoControllerPrefix: true`）
+7. `fail()` 仅用于预期业务错误（给用户看），非预期错误用自定义异常

package/README.md

@@ -1,135 +1,170 @@
 # 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
+## 安装
 
 ```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/{模块名}/AGENTS.md` 获取详细配置说明。

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "zenweb",
-  "version": "6.4.0",
+  "version": "6.5.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 +29,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.0",
+    "@zenweb/core": "^5.4.0",
+    "@zenweb/helper": "^5.5.0",
+    "@zenweb/inject": "^5.5.0",
+    "@zenweb/log": "^5.3.1",
+    "@zenweb/messagecode": "^5.6.0",
+    "@zenweb/meta": "^5.3.0",
+    "@zenweb/result": "^5.4.0",
+    "@zenweb/router": "^6.6.0"
   },
   "devDependencies": {
     "@types/node": "^16.18.126",