zenweb 6.5.0 → 6.6.0

package/README.md

@@ -13,6 +13,8 @@
 
 [ZenWeb 文档](https://zenweb.node.ltd)
 
+- 创建新项目 → 阅读 `TEMPLATE.md`
+
 ## 安装
 
 ```bash

package/TEMPLATE.md

@@ -228,4 +228,4 @@ export class UserService {
 | `@zenweb/form` | 表单构建 |
 | `@zenweb/grid` | 数据表渲染 |
 
-**配置指引：** 安装后阅读 `node_modules/{模块名}/AGENTS.md` 获取详细配置说明。
+**配置指引：** 安装后阅读 `node_modules/{模块名}/README.md` 获取详细配置说明。

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "zenweb",
-  "version": "6.5.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"
   ],
@@ -30,14 +29,14 @@
   "homepage": "https://zenweb.node.ltd",
   "dependencies": {
     "@zenweb/body": "^5.5.0",
-    "@zenweb/controller": "^6.6.0",
-    "@zenweb/core": "^5.4.0",
-    "@zenweb/helper": "^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.3.1",
+    "@zenweb/log": "^5.4.0",
     "@zenweb/messagecode": "^5.6.0",
     "@zenweb/meta": "^5.3.0",
-    "@zenweb/result": "^5.4.0",
+    "@zenweb/result": "^5.5.0",
     "@zenweb/router": "^6.6.0"
   },
   "devDependencies": {

package/AGENTS.md

@@ -1,419 +0,0 @@
-# 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()` 仅用于预期业务错误（给用户看），非预期错误用自定义异常