@dangao/bun-server 1.1.2 → 1.1.4

package/docs/zh/api.md

@@ -0,0 +1,168 @@
+# API 概览
+
+本文档概述 Bun Server Framework 目前提供的主要 API，方便快速查阅。
+
+## 核心
+
+| API                        | 描述                                                                                                                         |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `Application(options?)`    | 应用主类，支持 `use` 注册全局中间件、`registerController`/`registerWebSocketGateway` 注册组件以及 `listen/stop` 管理生命周期 |
+| `Context`                  | 统一的请求上下文，封装 `Request` 并提供 `getQuery/getParam/getBody/setHeader/setStatus/createResponse` 等方法                |
+| `ResponseBuilder`          | 提供 `json/text/html/empty/redirect/error/file` 便捷响应构建器                                                               |
+| `RouteRegistry` / `Router` | 可直接注册函数式路由或获取底层 `Router` 进行手动控制                                                                         |
+
+## 控制器与路由装饰器
+
+- `@Controller(path)`：声明控制器前缀。
+- `@GET/@POST/@PUT/@PATCH/@DELETE(path)`：声明 HTTP 方法。
+- 参数装饰器：`@Body() / @Query(key) / @Param(key) / @Header(key)`。
+- `ControllerRegistry` 会自动解析装饰器并注册路由。
+
+## 依赖注入
+
+- `Container`：`register`、`registerInstance`、`resolve`、`clear`、`isRegistered`。
+- 装饰器：`@Injectable(config?)` 设置生命周期、`@Inject(token?)` 指定依赖。
+- `Lifecycle` 枚举：`Singleton`、`Transient`、`Scoped`（预留）。
+
+## 中间件体系
+
+- `Middleware` 类型：`(context, next) => Response`。
+- `MiddlewarePipeline`：`use`, `run`, `hasMiddlewares`, `clear`。
+- `@UseMiddleware(...middlewares)`：作用于控制器类或方法。
+- 内置中间件：
+  - `createLoggerMiddleware`
+  - `createRequestLoggingMiddleware`
+  - `createCorsMiddleware`
+  - `createErrorHandlingMiddleware`
+  - `createFileUploadMiddleware`
+  - `createStaticFileMiddleware`
+
+## 验证
+
+- 装饰器：`@Validate(rule...)`, `IsString`, `IsNumber`, `IsEmail`, `IsOptional`,
+  `MinLength`。
+- `ValidationError`：`issues` 数组包含 `index / rule / message`。
+- `validateParameters(params, metadata)` 可在自定义场景复用。
+
+## 错误与异常
+
+- `HttpException` 及子类：`BadRequestException`, `UnauthorizedException`,
+  `ForbiddenException`, `NotFoundException`, `InternalServerErrorException`。
+- `ExceptionFilter` 接口与 `ExceptionFilterRegistry`：可注册自定义过滤器。
+- `handleError(error, context)`：全局错误处理核心逻辑；默认错误中间件已自动调用。
+
+## 扩展系统
+
+### 中间件
+
+- `Middleware` 类型：`(context: Context, next: NextFunction) => Response | Promise<Response>`
+- `app.use(middleware)`：注册全局中间件
+- `@UseMiddleware(...middlewares)`：控制器或方法级中间件
+- 内置中间件工厂函数：`createLoggerMiddleware`, `createCorsMiddleware`, `createErrorHandlingMiddleware`, `createFileUploadMiddleware`, `createStaticFileMiddleware`
+
+### 应用扩展
+
+- `ApplicationExtension` 接口：`register(container: Container): void`
+- `app.registerExtension(extension)`：注册应用扩展
+- 官方扩展：`LoggerExtension`, `SwaggerExtension`
+
+### 模块系统
+
+- `@Module(metadata)`：模块装饰器
+- `ModuleMetadata`：支持 `imports`, `controllers`, `providers`, `exports`, `extensions`, `middlewares`
+- `app.registerModule(moduleClass)`：注册模块
+- 官方模块：`LoggerModule.forRoot(options)`, `SwaggerModule.forRoot(options)`
+
+### 拦截器系统
+
+- `Interceptor` 接口：拦截器核心接口
+- `InterceptorRegistry`：拦截器中央注册表
+- `InterceptorChain`：按优先级顺序执行多个拦截器
+- `BaseInterceptor`：创建自定义拦截器的基类
+- `scanInterceptorMetadata`：扫描方法元数据查找拦截器
+
+**内置拦截器**：
+- `@Cache(options)`：缓存方法结果
+- `@Permission(options)`：在执行方法前检查权限
+- `@Log(options)`：记录方法执行日志和耗时
+
+**示例**：
+
+```typescript
+import { BaseInterceptor, INTERCEPTOR_REGISTRY_TOKEN } from '@dangao/bun-server';
+import type { InterceptorRegistry } from '@dangao/bun-server';
+
+// 创建自定义装饰器
+const MY_METADATA_KEY = Symbol('@my-app:my-decorator');
+
+function MyDecorator(): MethodDecorator {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(MY_METADATA_KEY, true, target, propertyKey);
+  };
+}
+
+// 创建拦截器
+class MyInterceptor extends BaseInterceptor {
+  public async execute<T>(...): Promise<T> {
+    // 前置处理
+    await this.before(...);
+    
+    // 执行原方法
+    const result = await Promise.resolve(originalMethod.apply(target, args));
+    
+    // 后置处理
+    return await this.after(...) as T;
+  }
+}
+
+// 注册拦截器
+const registry = app.getContainer().resolve<InterceptorRegistry>(INTERCEPTOR_REGISTRY_TOKEN);
+registry.register(MY_METADATA_KEY, new MyInterceptor(), 100);
+
+// 使用装饰器
+@Controller('/api/users')
+class UserController {
+  @GET('/:id')
+  @MyDecorator()
+  public getUser(@Param('id') id: string) {
+    return { id, name: 'User' };
+  }
+}
+```
+
+详细说明请参考 [自定义注解开发指南](./custom-decorators.md)。
+
+详细说明请参考 [扩展系统文档](./extensions.md)。
+
+## WebSocket
+
+- 装饰器：`@WebSocketGateway(path)` + `@OnOpen`, `@OnMessage`, `@OnClose`。
+- `WebSocketGatewayRegistry`：自动管理依赖注入、在
+  `Application.registerWebSocketGateway` 时登记。
+- 服务器会自动处理握手并将事件委托给网关实例。
+
+## 请求工具
+
+- `BodyParser`：`parse(request)`，自动缓存解析结果。
+- `FileHandler`：解析 `multipart/form-data`，返回结构化文件对象。
+- `RequestWrapper`：用于兼容场景的轻量封装。
+
+## 导出入口
+
+所有上述 API 均可从 `src/index.ts` 导出，通过
+
+```ts
+import {
+  Application,
+  Controller,
+  createLoggerMiddleware,
+  GET,
+  HttpException,
+  Injectable,
+  UseMiddleware,
+  Validate,
+  WebSocketGateway,
+} from "@dangao/bun-server";
+```
+
+即可在应用中使用。

package/docs/zh/best-practices.md

@@ -0,0 +1,38 @@
+# 最佳实践
+
+## 架构与模块化
+
+- **按领域拆分**：每个业务域单独的 Controller + Service + DTO，更易维护与测试。
+- **依赖显式化**：所有服务都通过构造函数注入，避免在方法内部 `container.resolve`。
+- **清理全局状态**：测试环境中记得清空 `RouteRegistry`、`ControllerRegistry` 与文件级缓存。
+
+## 中间件策略
+
+- **全局 vs 局部**：跨路由逻辑（日志、错误处理、鉴权）使用 `app.use`；业务相关逻辑在控制器上使用 `@UseMiddleware`。
+- **保持幂等**：中间件应尽量避免修改共享状态，可通过 `context` 新增字段传递数据。
+- **避免重复解析**：`Context.getBody()` 已缓存结果，不要在中间件和控制器中重复 `await request.json()`。
+
+## 性能建议
+
+- **缓存配置**：频繁读取的配置或数据可使用 Singleton 服务缓存。
+- **路由顺序**：将高频路由优先注册，减少匹配遍历时间。
+- **WebSocket**：处理长连接时避免阻塞操作，可将耗时任务交给队列或其他线程。
+
+## 安全
+
+- **输入验证**：所有外部输入（Body/Query/Param）都应使用验证装饰器或手动校验。
+- **静态文件**：使用内置 `createStaticFileMiddleware` 可自动阻止路径穿越。
+- **文件上传**：限制文件大小与类型，必要时结合病毒扫描或内容审核。
+
+## 日志与监控
+
+- **结构化日志**：`createLoggerMiddleware` 支持自定义 logger，可统一输出 JSON 格式，方便集中收集。
+- **请求追踪**：在中间件中注入 trace-id 到 `Context`，贯穿后续日志与下游调用。
+- **指标**：结合 `createRequestLoggingMiddleware` 或自定义中间件统计响应时间，供性能优化参考。
+
+## 部署
+
+- **多实例**：Bun 进程可结合容器/PM2 等方式多实例部署，并在外层做负载均衡。
+- **可观测**：建议接入健康检查路由（GET `/health`）以及基础指标导出（如 Prometheus）。
+- **灰度发布**：合理配置中间件，使得灰度流量可按 Header/Token 进行分流。
+

package/docs/zh/custom-decorators.md

@@ -0,0 +1,466 @@
+# 自定义注解开发指南
+
+本文档介绍如何在 Bun Server Framework 中创建自定义装饰器和拦截器。
+
+## 目录
+
+- [概述](#概述)
+- [创建自定义装饰器](#创建自定义装饰器)
+- [创建拦截器](#创建拦截器)
+- [使用 BaseInterceptor](#使用-baseinterceptor)
+- [访问容器和上下文](#访问容器和上下文)
+- [元数据系统](#元数据系统)
+- [示例](#示例)
+
+## 概述
+
+Bun Server Framework
+提供了强大的拦截器机制，允许您创建自定义装饰器和拦截器来实现
+AOP（面向切面编程）。这使您能够添加横切关注点，如缓存、日志记录、权限检查等。
+
+### 核心概念
+
+- **装饰器**：一个 TypeScript 装饰器，用于在方法上添加元数据
+- **拦截器**：一个拦截方法执行并可以修改行为的类
+- **元数据键**：用于将装饰器与拦截器关联的 Symbol
+- **拦截器注册表**：管理所有拦截器的中央注册表
+
+## 创建自定义装饰器
+
+### 基本装饰器模式
+
+自定义装饰器是一个返回 `MethodDecorator` 的函数。它使用 `reflect-metadata`
+在方法上存储元数据。
+
+```typescript
+import "reflect-metadata";
+
+// 1. 定义元数据键（使用 Symbol 确保唯一性）
+export const MY_METADATA_KEY = Symbol("@my-app:my-decorator");
+
+// 2. 定义元数据类型
+export interface MyDecoratorOptions {
+  option1: string;
+  option2?: number;
+}
+
+// 3. 创建装饰器函数
+export function MyDecorator(options: MyDecoratorOptions): MethodDecorator {
+  return (target, propertyKey, descriptor) => {
+    // 在方法上存储元数据
+    Reflect.defineMetadata(MY_METADATA_KEY, options, target, propertyKey);
+  };
+}
+```
+
+### 装饰器命名规范
+
+- 使用 PascalCase 命名装饰器：`@Cache()`, `@Permission()`, `@Log()`
+- 使用描述性名称，表明装饰器的用途
+- 元数据键应遵循模式：`Symbol('@namespace:feature')`
+
+### 装饰器函数签名
+
+```typescript
+function MyDecorator(options?: MyOptions): MethodDecorator {
+  return (
+    target: any,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) => {
+    // 实现
+  };
+}
+```
+
+## 创建拦截器
+
+### 实现 Interceptor 接口
+
+拦截器必须实现 `Interceptor` 接口：
+
+```typescript
+import type { Interceptor } from "@dangao/bun-server";
+import type { Container } from "@dangao/bun-server";
+import type { Context } from "@dangao/bun-server";
+
+class MyInterceptor implements Interceptor {
+  public async execute<T>(
+    target: unknown,
+    propertyKey: string | symbol,
+    originalMethod: (...args: unknown[]) => T | Promise<T>,
+    args: unknown[],
+    container: Container,
+    context?: Context,
+  ): Promise<T> {
+    // 前置处理逻辑
+    console.log(`执行 ${String(propertyKey)}`);
+
+    // 执行原方法
+    const result = await Promise.resolve(originalMethod.apply(target, args));
+
+    // 后置处理逻辑
+    console.log(`完成 ${String(propertyKey)}`);
+
+    return result;
+  }
+}
+```
+
+### 注册拦截器
+
+拦截器必须注册到 `InterceptorRegistry`：
+
+```typescript
+import { Application } from "@dangao/bun-server";
+import { INTERCEPTOR_REGISTRY_TOKEN } from "@dangao/bun-server";
+import type { InterceptorRegistry } from "@dangao/bun-server";
+
+const app = new Application({ port: 3000 });
+const registry = app.getContainer().resolve<InterceptorRegistry>(
+  INTERCEPTOR_REGISTRY_TOKEN,
+);
+
+// 使用元数据键和优先级注册拦截器
+registry.register(MY_METADATA_KEY, new MyInterceptor(), 100);
+```
+
+### 优先级系统
+
+拦截器按优先级顺序执行（数字越小越先执行）：
+
+- 优先级 0-50：系统拦截器（如事务）
+- 优先级 51-100：框架拦截器
+- 优先级 101+：应用拦截器
+
+## 使用 BaseInterceptor
+
+`BaseInterceptor` 提供了一个便捷的基类，包含常用操作的钩子：
+
+```typescript
+import { BaseInterceptor } from "@dangao/bun-server";
+import type { Container } from "@dangao/bun-server";
+import type { Context } from "@dangao/bun-server";
+
+class MyInterceptor extends BaseInterceptor {
+  public async execute<T>(
+    target: unknown,
+    propertyKey: string | symbol,
+    originalMethod: (...args: unknown[]) => T | Promise<T>,
+    args: unknown[],
+    container: Container,
+    context?: Context,
+  ): Promise<T> {
+    try {
+      // 前置处理
+      await this.before(target, propertyKey, args, container, context);
+
+      // 执行原方法
+      const result = await Promise.resolve(originalMethod.apply(target, args));
+
+      // 后置处理
+      return await this.after(
+        target,
+        propertyKey,
+        result,
+        container,
+        context,
+      ) as T;
+    } catch (error) {
+      // 错误处理
+      return await this.onError(target, propertyKey, error, container, context);
+    }
+  }
+
+  protected async before(
+    target: unknown,
+    propertyKey: string | symbol,
+    args: unknown[],
+    container: Container,
+    context?: Context,
+  ): Promise<void> {
+    // 覆盖以添加前置处理逻辑
+  }
+
+  protected async after<T>(
+    target: unknown,
+    propertyKey: string | symbol,
+    result: T,
+    container: Container,
+    context?: Context,
+  ): Promise<T> {
+    // 覆盖以添加后置处理逻辑
+    return result;
+  }
+
+  protected async onError(
+    target: unknown,
+    propertyKey: string | symbol,
+    error: unknown,
+    container: Container,
+    context?: Context,
+  ): Promise<never> {
+    // 覆盖以自定义错误处理
+    throw error;
+  }
+}
+```
+
+### 辅助方法
+
+`BaseInterceptor` 提供了几个辅助方法：
+
+```typescript
+// 从方法获取元数据
+// 注意：getMetadata() 的签名是 (target, propertyKey, metadataKey)
+const metadata = this.getMetadata<MyOptions>(
+  target,
+  propertyKey,
+  MY_METADATA_KEY,
+);
+
+// 从容器解析服务
+const service = this.resolveService<MyService>(container, MyService);
+
+// 访问上下文
+const header = this.getHeader(context!, "Authorization");
+const query = this.getQuery(context!, "page");
+const param = this.getParam(context!, "id");
+```
+
+## 访问容器和上下文
+
+### 从容器解析服务
+
+```typescript
+class MyInterceptor extends BaseInterceptor {
+  public async execute<T>(...): Promise<T> {
+    // 使用辅助方法解析服务
+    const userService = this.resolveService<UserService>(container, UserService);
+
+    // 或直接解析
+    const config = container.resolve<ConfigService>(CONFIG_SERVICE_TOKEN);
+
+    // 使用服务
+    const user = await userService.find(userId);
+    // ...
+  }
+}
+```
+
+### 访问请求上下文
+
+```typescript
+class MyInterceptor extends BaseInterceptor {
+  public async execute<T>(...): Promise<T> {
+    if (context) {
+      // 获取请求头
+      const authHeader = this.getHeader(context, 'Authorization');
+      const contentType = this.getHeader(context, 'Content-Type');
+
+      // 获取查询参数
+      const page = this.getQuery(context, 'page');
+      const limit = this.getQuery(context, 'limit');
+
+      // 获取路径参数
+      const userId = this.getParam(context, 'id');
+
+      // 获取请求体
+      const body = await context.getBody();
+
+      // 设置响应头
+      context.setHeader('X-Custom-Header', 'value');
+    }
+  }
+}
+```
+
+## 元数据系统
+
+### 存储元数据
+
+```typescript
+import "reflect-metadata";
+
+const METADATA_KEY = Symbol("my-metadata");
+
+// 存储元数据
+Reflect.defineMetadata(METADATA_KEY, { value: "data" }, target, propertyKey);
+```
+
+### 读取元数据
+
+**重要**：装饰器将元数据存储在原型（类）上，而不是实例上。在拦截器中读取元数据时，需要正确处理这一点。
+
+**方式 1：使用 `BaseInterceptor.getMetadata()`（推荐）**
+
+```typescript
+class MyInterceptor extends BaseInterceptor {
+  public async execute<T>(...): Promise<T> {
+    // getMetadata() 自动处理原型链查找
+    const metadata = this.getMetadata<MyOptions>(target, propertyKey, METADATA_KEY);
+  }
+}
+```
+
+**方式 2：手动原型链查找**
+
+如果不使用 `BaseInterceptor`，需要手动检查原型链：
+
+```typescript
+// 读取元数据（处理实例和原型）
+let metadata: MyOptions | undefined;
+if (typeof target === "object" && target !== null) {
+  // 首先尝试直接查找（如果 target 是原型）
+  metadata = Reflect.getMetadata(METADATA_KEY, target, propertyKey);
+
+  // 如果未找到且 target 是实例，检查原型
+  if (metadata === undefined) {
+    const prototype = Object.getPrototypeOf(target);
+    if (prototype && prototype !== Object.prototype) {
+      metadata = Reflect.getMetadata(METADATA_KEY, prototype, propertyKey);
+    }
+
+    // 也检查构造函数原型作为后备
+    if (metadata === undefined) {
+      const constructor = (target as any).constructor;
+      if (
+        constructor && typeof constructor === "function" &&
+        constructor.prototype
+      ) {
+        metadata = Reflect.getMetadata(
+          METADATA_KEY,
+          constructor.prototype,
+          propertyKey,
+        );
+      }
+    }
+  }
+}
+
+// 检查元数据是否存在
+const exists = metadata !== undefined;
+```
+
+### 拦截器中的元数据
+
+```typescript
+class MyInterceptor extends BaseInterceptor {
+  public async execute<T>(...): Promise<T> {
+    // 使用辅助方法获取元数据
+    // 注意：getMetadata() 的签名是 (target, propertyKey, metadataKey)
+    const options = this.getMetadata<MyOptions>(target, propertyKey, MY_METADATA_KEY);
+
+    if (options) {
+      // 使用选项
+      console.log(`选项值: ${options.value}`);
+    }
+  }
+}
+```
+
+## 示例
+
+### 示例 1：简单日志拦截器
+
+```typescript
+import 'reflect-metadata';
+import { BaseInterceptor } from '@dangao/bun-server';
+import type { Container } from '@dangao/bun-server';
+import type { Context } from '@dangao/bun-server';
+
+const LOG_METADATA_KEY = Symbol('@my-app:log');
+
+export function Log(message?: string): MethodDecorator {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(LOG_METADATA_KEY, { message }, target, propertyKey);
+  };
+}
+
+export class LogInterceptor extends BaseInterceptor {
+  public async execute<T>(...): Promise<T> {
+    const metadata = this.getMetadata<{ message?: string }>(target, propertyKey, LOG_METADATA_KEY);
+    const logMessage = metadata?.message || `执行 ${String(propertyKey)}`;
+
+    console.log(`[LOG] ${logMessage} - 开始`);
+    const start = Date.now();
+
+    try {
+      const result = await Promise.resolve(originalMethod.apply(target, args));
+      const duration = Date.now() - start;
+      console.log(`[LOG] ${logMessage} - 完成，耗时 ${duration}ms`);
+      return result;
+    } catch (error) {
+      const duration = Date.now() - start;
+      console.error(`[LOG] ${logMessage} - 失败，耗时 ${duration}ms`, error);
+      throw error;
+    }
+  }
+}
+```
+
+### 示例 2：限流拦截器
+
+```typescript
+import 'reflect-metadata';
+import { BaseInterceptor, HttpException } from '@dangao/bun-server';
+import type { Container } from '@dangao/bun-server';
+import type { Context } from '@dangao/bun-server';
+
+const RATE_LIMIT_METADATA_KEY = Symbol('@my-app:rate-limit');
+
+export interface RateLimitOptions {
+  maxRequests: number;
+  windowMs: number;
+}
+
+export function RateLimit(options: RateLimitOptions): MethodDecorator {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(RATE_LIMIT_METADATA_KEY, options, target, propertyKey);
+  };
+}
+
+export class RateLimitInterceptor extends BaseInterceptor {
+  private readonly requests = new Map<string, number[]>();
+
+  public async execute<T>(...): Promise<T> {
+    const options = this.getMetadata<RateLimitOptions>(target, propertyKey, RATE_LIMIT_METADATA_KEY);
+    if (!options || !context) {
+      return await Promise.resolve(originalMethod.apply(target, args));
+    }
+
+    const clientId = this.getHeader(context, 'X-Client-Id') || context.request.headers.get('X-Forwarded-For') || 'unknown';
+    const now = Date.now();
+    const windowStart = now - options.windowMs;
+
+    // 清理旧请求
+    const requests = this.requests.get(clientId) || [];
+    const recentRequests = requests.filter(time => time > windowStart);
+
+    if (recentRequests.length >= options.maxRequests) {
+      throw new HttpException(429, '请求过于频繁');
+    }
+
+    recentRequests.push(now);
+    this.requests.set(clientId, recentRequests);
+
+    return await Promise.resolve(originalMethod.apply(target, args));
+  }
+}
+```
+
+## 最佳实践
+
+1. **使用 Symbol 作为元数据键**：确保唯一性并避免冲突
+2. **遵循命名规范**：使用一致的命名模式
+3. **文档化您的装饰器**：为用户提供清晰的文档
+4. **优雅处理错误**：始终在拦截器中处理错误
+5. **考虑性能**：最小化拦截器执行开销
+6. **使用 BaseInterceptor**：利用基类实现常见模式
+7. **测试您的拦截器**：编写全面的测试
+
+## 相关资源
+
+- [API 文档](./api.md)
+- [示例](../examples/)
+- [内置拦截器](../packages/bun-server/src/interceptor/builtin/)