zenweb 6.3.0 → 6.5.0

package/AGENTS.md

@@ -0,0 +1,419 @@
+# AGENTS.md
+
+AI 专用 API 参考文档，供 AI 编程助手使用。
+
+**使用指引：**
+- 创建新项目 → 阅读 `TEMPLATE.md`
+- 理解现有代码 → 阅读 `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 };
+
+// 依赖注入
+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 { fail, ResultFail } from '@zenweb/result';
+
+// 全局 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';
+```
+
+---
+
+## 控制器
+
+控制器类自动标记为请求级注入，方法参数自动注入。
+
+```ts
+// controller/user.ts - 文件名映射为路由前缀 /user
+export class UserController {
+  @Get()              // GET /user
+  list() { return []; }
+
+  @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' });
+  }
+}
+```
+
+**@Controller 装饰器（可选）：**
+```ts
+@Controller({ prefix: '/admin' })      // 绝对前缀
+@Controller({ prefix: 'manage' })      // 相对前缀，拼接自动前缀
+@Controller({ middleware: [authFn] })  // 控制器级中间件
+```
+
+**生命周期：**
+```ts
+@Controller()
+export class MyController {
+  constructor(private ctx: Context) {}  // 自动注入
+
+  @Init
+  init() { /* 实例化后调用 */ }
+}
+```
+
+**单例控制器**（适用于无状态场景）：
+```ts
+@Controller()
+@Injectable('singleton')
+export class CounterController {
+  counter = 0;
+  @Get() index() { return ++this.counter; }
+}
+```
+
+---
+
+## Router 直接使用（非控制器场景）
+
+不使用控制器装饰器时，可直接通过 `app.router` 注册路由：
+
+```ts
+import { create, Router } from 'zenweb';
+
+const app = create({
+  controller: false,  // 禁用控制器自动发现
+});
+
+// 直接注册路由
+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);
+
+app.start();
+```
+
+---
+
+## 全局中间件
+
+通过 `setup.middleware()` 添加应用级中间件：
+
+```ts
+import { create } from 'zenweb';
+
+const app = create();
+
+// Core 级中间件（所有请求）
+app.setup(function myMiddleware(setup) {
+  setup.middleware(async (ctx, next) => {
+    ctx.set('X-Custom', 'value');
+    return next();
+  });
+});
+```
+
+---
+
+## 消息代码（MessageCode）
+
+用于错误消息格式化，**优先使用统一定义文件**：
+
+```ts
+// message-codes.json（推荐）
+{
+  "user.notfound": "用户不存在",
+  "user.login.fail": "登录失败: {reason}",
+  "error.system": "系统错误"
+}
+
+// 或 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 异常
+```
+
+---
+
+## 依赖注入
+
+**Service 类默认添加 @Injectable 注解**（将 service 类的作用域设置为 request）：
+
+```ts
+@Injectable                    // Service 类必须添加注解！
+export class UserService {
+  constructor(private ctx: Context, private db: DatabaseService) {}  // 自动注入
+}
+```
+
+**无法用构造器注入时，使用 @Inject 属性注入**：
+
+```ts
+@Injectable
+export class MyService {
+  constructor(private ctx: Context) {}  // 构造器注入
+  
+  @Inject private cache!: CacheService;  // 属性注入（后注入）
+}
+```
+
+**作用域：**
+```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(400, '参数错误');
+fail({ code: 10001, message: '余额不足' });
+```
+
+**非预期错误使用自定义异常**（如数据库连接失败、代码 bug），不要用 fail()：
+
+```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',      // 去空格
+});
+```
+
+支持类型：`int`, `float`, `number`, `bool`, `string`, `trim`, `date`, `datetime`, `array`, `object`, `json`
+
+---
+
+## 各模块详细文档
+
+详细 API 参阅各模块 AGENTS.md：
+
+- `node_modules/@zenweb/core/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/meta/AGENTS.md`
+- `node_modules/@zenweb/messagecode/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,129 +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 install zenweb
+npm i zenweb
 
-# for development
-npm install dotenv typescript rimraf tsc-watch --save-dev
+# 开发依赖
+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
 {
-  "extends": "zenweb/tsconfig-app",
   "compilerOptions": {
-    "outDir": "./app"
-  },
-  "include": ["src/**/*"]
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "target": "ES2020",
+    "module": "commonjs"
+  }
 }
 ```
 
-create `.env` file
-
-```bash
-APP_NAME=myweb
-NODE_ENV=development
-DEBUG=*
-```
-
-create `src/index.ts` file
+## 快速开始
 
 ```ts
 import { create } from 'zenweb';
-create().start();
+
+create({
+  controller: {
+    discoverPaths: ['./controller'],
+    autoControllerPrefix: true,
+  },
+}).start();
 ```
 
-create `src/service/hello.ts` file
+## 控制器
+
+文件名映射为路由前缀（开启 `autoControllerPrefix`）：
 
 ```ts
-import { Component, Context } from 'zenweb';
+// controller/user.ts → /user
+import { Get, Post, Context } from 'zenweb';
+import { UserService } from '../service/user';
+
+export class UserController {
+  constructor(private ctx: Context) {}
 
-@Component
-export class HelloService {
-  constructor(
-    private ctx: Context,
-  ){}
+  @Get()               // GET /user
+  list() { return []; }
 
-  getIp() {
-    return this.ctx.ip;
+  @Get('/:id')         // GET /user/:id
+  detail() {
+    const { id } = this.ctx.params;
+    return { id };
+  }
+
+  @Post()              // POST /user
+  create(service: UserService) {
+    return service.create();
   }
 }
 ```
 
-create `src/controller/hello.ts` file
+## Service
+
+Service 类添加 `@Injectable` 注解，作用域为请求级：
 
 ```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}`;
+// service/user.ts
+import { Injectable, Context } from 'zenweb';
+
+@Injectable
+export class UserService {
+  constructor(private ctx: Context) {}
+
+  create() {
+    return { ip: this.ctx.ip };
   }
 }
 ```
 
-start server:
+## 全局 Helper
 
-```bash
-npm run dev
+请求期间无需注入，直接使用：
+
+```ts
+// Body 解析
+await $body.get({ name: '!string', age: 'int' });
+
+// Query 参数
+await $query.get({ id: '!int', keyword: 'trim' });
+
+// 路由参数
+const { id } = $ctx.params;
+
+// 日志
+$log.info('message');
 ```
 
-## 内置模块
-- [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) 统一错误消息格式化
-  - 依赖 inject, result
-- [controller](https://www.npmjs.com/package/@zenweb/controller) 类控制器支持
-  - 依赖 inject, router
-- [helper](https://www.npmjs.com/package/@zenweb/helper) 输入数据验证助手
-  - 依赖 inject, messagecode
-- [body](https://www.npmjs.com/package/@zenweb/body) 请求主体解析，JSON、Form
-  - 依赖 inject, helper
-
-内置模块默认开启，可以通过设置配置项为 **false** 关闭
+## 错误处理
 
+`fail()` 用于预期业务错误：
+
+```ts
+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` 关闭。
 
 ## 可选模块
-- [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/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Core } from '@zenweb/core';
-import { CreateOptions } from './types.js';
+import { CreateOptions } from './types';
 export { Init, Inject, Injectable, $getInstance } from '@zenweb/inject';
 export { Router, RouterMethod, RouterPath } from '@zenweb/router';
 export { ResultFail, fail } from '@zenweb/result';

package/dist/index.js

@@ -1,46 +1,94 @@
-import inject from '@zenweb/inject';
-import meta from '@zenweb/meta';
-import log from '@zenweb/log';
-import router from '@zenweb/router';
-import messagecode from '@zenweb/messagecode';
-import body from '@zenweb/body';
-import result from '@zenweb/result';
-import helper from '@zenweb/helper';
-import controller from '@zenweb/controller';
-import { Core, $initCore } from '@zenweb/core';
-export { Init, Inject, Injectable, $getInstance } from '@zenweb/inject';
-export { Router } from '@zenweb/router';
-export { ResultFail, fail } from '@zenweb/result';
-export { Controller, Mapping, Get, Post, Put, Patch, Delete, All, } from '@zenweb/controller';
-export { Context, SetupHelper, $getCore, $getContext, $core, $ctx, $debug, createDebug, } from '@zenweb/core';
-export { Body, ObjectBody, BodyHelper, RawBody, TextBody, useBodyParser, $body, $getTextBody, $getRawBody, $getObjectBody, } from '@zenweb/body';
-export { QueryHelper, TypeCastHelper, ParamHelper, $param, $query, $helperBase, } from '@zenweb/helper';
-export { $log, $getLogger, } from '@zenweb/log';
-export { Core, };
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Core = exports.$getLogger = exports.$log = exports.$helperBase = exports.$query = exports.$param = exports.ParamHelper = exports.TypeCastHelper = exports.QueryHelper = exports.$getObjectBody = exports.$getRawBody = exports.$getTextBody = exports.$body = exports.useBodyParser = exports.TextBody = exports.RawBody = exports.BodyHelper = exports.ObjectBody = exports.Body = exports.createDebug = exports.$debug = exports.$ctx = exports.$core = exports.$getContext = exports.$getCore = exports.SetupHelper = exports.Context = exports.All = exports.Delete = exports.Patch = exports.Put = exports.Post = exports.Get = exports.Mapping = exports.Controller = exports.fail = exports.ResultFail = exports.Router = exports.$getInstance = exports.Injectable = exports.Inject = exports.Init = void 0;
+exports.create = create;
+const inject_1 = __importDefault(require("@zenweb/inject"));
+const meta_1 = __importDefault(require("@zenweb/meta"));
+const log_1 = __importDefault(require("@zenweb/log"));
+const router_1 = __importDefault(require("@zenweb/router"));
+const messagecode_1 = __importDefault(require("@zenweb/messagecode"));
+const body_1 = __importDefault(require("@zenweb/body"));
+const result_1 = __importDefault(require("@zenweb/result"));
+const helper_1 = __importDefault(require("@zenweb/helper"));
+const controller_1 = __importDefault(require("@zenweb/controller"));
+const core_1 = require("@zenweb/core");
+Object.defineProperty(exports, "Core", { enumerable: true, get: function () { return core_1.Core; } });
+var inject_2 = require("@zenweb/inject");
+Object.defineProperty(exports, "Init", { enumerable: true, get: function () { return inject_2.Init; } });
+Object.defineProperty(exports, "Inject", { enumerable: true, get: function () { return inject_2.Inject; } });
+Object.defineProperty(exports, "Injectable", { enumerable: true, get: function () { return inject_2.Injectable; } });
+Object.defineProperty(exports, "$getInstance", { enumerable: true, get: function () { return inject_2.$getInstance; } });
+var router_2 = require("@zenweb/router");
+Object.defineProperty(exports, "Router", { enumerable: true, get: function () { return router_2.Router; } });
+var result_2 = require("@zenweb/result");
+Object.defineProperty(exports, "ResultFail", { enumerable: true, get: function () { return result_2.ResultFail; } });
+Object.defineProperty(exports, "fail", { enumerable: true, get: function () { return result_2.fail; } });
+var controller_2 = require("@zenweb/controller");
+Object.defineProperty(exports, "Controller", { enumerable: true, get: function () { return controller_2.Controller; } });
+Object.defineProperty(exports, "Mapping", { enumerable: true, get: function () { return controller_2.Mapping; } });
+Object.defineProperty(exports, "Get", { enumerable: true, get: function () { return controller_2.Get; } });
+Object.defineProperty(exports, "Post", { enumerable: true, get: function () { return controller_2.Post; } });
+Object.defineProperty(exports, "Put", { enumerable: true, get: function () { return controller_2.Put; } });
+Object.defineProperty(exports, "Patch", { enumerable: true, get: function () { return controller_2.Patch; } });
+Object.defineProperty(exports, "Delete", { enumerable: true, get: function () { return controller_2.Delete; } });
+Object.defineProperty(exports, "All", { enumerable: true, get: function () { return controller_2.All; } });
+var core_2 = require("@zenweb/core");
+Object.defineProperty(exports, "Context", { enumerable: true, get: function () { return core_2.Context; } });
+Object.defineProperty(exports, "SetupHelper", { enumerable: true, get: function () { return core_2.SetupHelper; } });
+Object.defineProperty(exports, "$getCore", { enumerable: true, get: function () { return core_2.$getCore; } });
+Object.defineProperty(exports, "$getContext", { enumerable: true, get: function () { return core_2.$getContext; } });
+Object.defineProperty(exports, "$core", { enumerable: true, get: function () { return core_2.$core; } });
+Object.defineProperty(exports, "$ctx", { enumerable: true, get: function () { return core_2.$ctx; } });
+Object.defineProperty(exports, "$debug", { enumerable: true, get: function () { return core_2.$debug; } });
+Object.defineProperty(exports, "createDebug", { enumerable: true, get: function () { return core_2.createDebug; } });
+var body_2 = require("@zenweb/body");
+Object.defineProperty(exports, "Body", { enumerable: true, get: function () { return body_2.Body; } });
+Object.defineProperty(exports, "ObjectBody", { enumerable: true, get: function () { return body_2.ObjectBody; } });
+Object.defineProperty(exports, "BodyHelper", { enumerable: true, get: function () { return body_2.BodyHelper; } });
+Object.defineProperty(exports, "RawBody", { enumerable: true, get: function () { return body_2.RawBody; } });
+Object.defineProperty(exports, "TextBody", { enumerable: true, get: function () { return body_2.TextBody; } });
+Object.defineProperty(exports, "useBodyParser", { enumerable: true, get: function () { return body_2.useBodyParser; } });
+Object.defineProperty(exports, "$body", { enumerable: true, get: function () { return body_2.$body; } });
+Object.defineProperty(exports, "$getTextBody", { enumerable: true, get: function () { return body_2.$getTextBody; } });
+Object.defineProperty(exports, "$getRawBody", { enumerable: true, get: function () { return body_2.$getRawBody; } });
+Object.defineProperty(exports, "$getObjectBody", { enumerable: true, get: function () { return body_2.$getObjectBody; } });
+var helper_2 = require("@zenweb/helper");
+Object.defineProperty(exports, "QueryHelper", { enumerable: true, get: function () { return helper_2.QueryHelper; } });
+Object.defineProperty(exports, "TypeCastHelper", { enumerable: true, get: function () { return helper_2.TypeCastHelper; } });
+Object.defineProperty(exports, "ParamHelper", { enumerable: true, get: function () { return helper_2.ParamHelper; } });
+Object.defineProperty(exports, "$param", { enumerable: true, get: function () { return helper_2.$param; } });
+Object.defineProperty(exports, "$query", { enumerable: true, get: function () { return helper_2.$query; } });
+Object.defineProperty(exports, "$helperBase", { enumerable: true, get: function () { return helper_2.$helperBase; } });
+var log_2 = require("@zenweb/log");
+Object.defineProperty(exports, "$log", { enumerable: true, get: function () { return log_2.$log; } });
+Object.defineProperty(exports, "$getLogger", { enumerable: true, get: function () { return log_2.$getLogger; } });
 /**
  * 创建应用实例
  * @param options 模块配置项
  */
-export function create(options) {
+function create(options) {
     options = options || {};
-    const core = (options.global !== false) ? $initCore(options.core) : new Core(options.core);
+    const core = (options.global !== false) ? (0, core_1.$initCore)(options.core) : new core_1.Core(options.core);
     if (options.meta !== false)
-        core.setup(meta(options.meta));
+        core.setup((0, meta_1.default)(options.meta));
     if (options.inject !== false)
-        core.setup(inject());
+        core.setup((0, inject_1.default)());
     if (options.log !== false)
-        core.setup(log(options.log));
+        core.setup((0, log_1.default)(options.log));
     if (options.router !== false)
-        core.setup(router());
+        core.setup((0, router_1.default)());
     if (options.result !== false)
-        core.setup(result(options.result));
+        core.setup((0, result_1.default)(options.result));
     if (options.messagecode !== false)
-        core.setup(messagecode(options.messagecode));
+        core.setup((0, messagecode_1.default)(options.messagecode));
     if (options.helper !== false)
-        core.setup(helper(options.helper));
+        core.setup((0, helper_1.default)(options.helper));
     if (options.body !== false)
-        core.setup(body(options.body));
+        core.setup((0, body_1.default)(options.body));
     if (options.controller !== false)
-        core.setup(controller(options.controller));
+        core.setup((0, controller_1.default)(options.controller));
     return core;
 }

package/dist/types.js

@@ -1 +1,2 @@
-export {};
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "zenweb",
-  "type": "module",
-  "version": "6.3.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": {
-    "build": "rimraf dist && tsc",
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
     "prepack": "npm run build",
-    "dev": "cd example && node --env-file=.env --loader=ts-node/esm index.ts"
+    "dev": "cd example && node --env-file=.env -r ts-node/register index.ts"
   },
   "author": {
     "name": "YeFei",
@@ -28,24 +29,24 @@
   "license": "MIT",
   "homepage": "https://zenweb.node.ltd",
   "dependencies": {
-    "@zenweb/body": "^5.3.0",
-    "@zenweb/controller": "^6.3.0",
-    "@zenweb/core": "^5.2.1",
-    "@zenweb/helper": "^5.3.0",
-    "@zenweb/inject": "^5.3.0",
-    "@zenweb/log": "^5.1.0",
-    "@zenweb/messagecode": "^5.3.0",
-    "@zenweb/meta": "^5.1.1",
-    "@zenweb/result": "^5.2.0",
-    "@zenweb/router": "^6.4.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": "^20.19.39",
+    "@types/node": "^16.18.126",
     "rimraf": "^4.4.1",
     "ts-node": "^10.9.2",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.3"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=16"
   }
 }