@dangao/bun-server 1.9.0 → 1.12.0

package/docs/lifecycle.md

@@ -0,0 +1,72 @@
+# Lifecycle Hooks
+
+Bun Server supports lifecycle hooks that let providers participate in application startup and shutdown. Implement the appropriate interface on your injectable services.
+
+## Interfaces
+
+| Interface | Method | When Called |
+|-----------|--------|-------------|
+| `OnModuleInit` | `onModuleInit()` | After all module providers are registered |
+| `OnModuleDestroy` | `onModuleDestroy()` | During shutdown (reverse order) |
+| `OnApplicationBootstrap` | `onApplicationBootstrap()` | After all modules init, before server listens |
+| `OnApplicationShutdown` | `onApplicationShutdown(signal?)` | When graceful shutdown begins |
+
+## Execution Order
+
+**Startup**: `onModuleInit` (all modules) -> `onApplicationBootstrap` (all modules) -> server starts
+
+**Shutdown**: `onApplicationShutdown` (reverse order) -> `onModuleDestroy` (reverse order)
+
+## Example: DatabaseService with init/destroy
+
+```ts
+import {
+  Injectable,
+  OnModuleInit,
+  OnModuleDestroy,
+} from '@dangao/bun-server';
+
+@Injectable()
+class DatabaseService implements OnModuleInit, OnModuleDestroy {
+  private connected = false;
+
+  public async onModuleInit(): Promise<void> {
+    console.log('[DatabaseService] Connecting...');
+    await this.connect();
+    this.connected = true;
+  }
+
+  public async onModuleDestroy(): Promise<void> {
+    console.log('[DatabaseService] Closing connection...');
+    await this.disconnect();
+    this.connected = false;
+  }
+
+  public isConnected(): boolean {
+    return this.connected;
+  }
+
+  private async connect(): Promise<void> {
+    // Open DB connection
+  }
+
+  private async disconnect(): Promise<void> {
+    // Close DB connection
+  }
+}
+```
+
+## Example: Application-level hooks
+
+```ts
+@Injectable()
+class AppService implements OnApplicationBootstrap, OnApplicationShutdown {
+  public onApplicationBootstrap(): void {
+    console.log('Application bootstrapped');
+  }
+
+  public onApplicationShutdown(signal?: string): void {
+    console.log(`Shutting down (signal: ${signal ?? 'none'})`);
+  }
+}
+```

package/docs/testing.md

@@ -0,0 +1,110 @@
+# Testing Module
+
+The Testing Module provides utilities for unit and integration testing of Bun Server applications. Use `Test.createTestingModule()` to build an isolated test environment with provider overrides.
+
+## API Overview
+
+### Test.createTestingModule()
+
+Creates a test module builder with the given module metadata (controllers, providers, imports).
+
+```ts
+const builder = Test.createTestingModule({
+  controllers: [UserController],
+  providers: [UserService],
+});
+```
+
+### overrideProvider().useValue() / .useClass() / .useFactory()
+
+Override a provider with a mock or alternative implementation:
+
+```ts
+const module = await Test.createTestingModule({
+  controllers: [GreetController],
+  providers: [{ provide: GREETER_TOKEN, useClass: RealGreeter }],
+})
+  .overrideProvider(GREETER_TOKEN)
+  .useValue(mockGreeter)  // or .useClass(MockGreeter) or .useFactory(() => mock)
+  .compile();
+```
+
+- **useValue**: Replace with a fixed value (e.g. mock object)
+- **useClass**: Replace with an alternative class
+- **useFactory**: Replace with a factory function
+
+### TestingModule.get()
+
+Resolve a provider from the DI container:
+
+```ts
+const service = module.get(UserService);
+```
+
+### TestingModule.createApplication()
+
+Create an `Application` instance with all providers and controllers registered. Does not start the server.
+
+```ts
+const app = module.createApplication({ port: 0 });
+```
+
+### TestingModule.createHttpClient()
+
+Creates an `Application`, starts it on a random port, and returns a `TestHttpClient` for HTTP requests.
+
+```ts
+const client = await module.createHttpClient();
+const res = await client.get('/api/users');
+await client.close();
+```
+
+### TestHttpClient Methods
+
+| Method | Description |
+|--------|-------------|
+| `get(path, options?)` | GET request |
+| `post(path, options?)` | POST request |
+| `put(path, options?)` | PUT request |
+| `delete(path, options?)` | DELETE request |
+| `patch(path, options?)` | PATCH request |
+| `close()` | Stop the test server |
+
+Options support `headers`, `body`, and `query`.
+
+## Example with bun:test
+
+```ts
+import { describe, expect, test } from 'bun:test';
+import { Test, Controller, GET, Inject } from '@dangao/bun-server';
+
+const GREETER_TOKEN = Symbol('Greeter');
+
+@Controller('/api')
+class GreetController {
+  public constructor(@Inject(GREETER_TOKEN) private greeter: { greet: (s: string) => string }) {}
+
+  @GET('/greet')
+  public greet(): object {
+    return { message: this.greeter.greet('World') };
+  }
+}
+
+describe('GreetController', () => {
+  test('should return mock greeting', async () => {
+    const mockGreeter = { greet: (name: string) => `Mock: ${name}` };
+
+    const module = await Test.createTestingModule({
+      controllers: [GreetController],
+      providers: [{ provide: GREETER_TOKEN, useValue: mockGreeter }],
+    }).compile();
+
+    const client = await module.createHttpClient();
+    const res = await client.get('/api/greet');
+    await client.close();
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ message: 'Mock: World' });
+  });
+});
+```

package/docs/zh/async-module.md

@@ -0,0 +1,98 @@
+# 异步模块配置
+
+当模块配置需要异步加载（如远程配置中心、密钥库、数据库连接等）时，可使用 `forRootAsync()` 模式。
+
+## AsyncModuleOptions 接口
+
+```ts
+interface AsyncModuleOptions<T> {
+  imports?: ModuleClass[];   // 需要导入的模块（提供 inject 依赖）
+  inject?: ProviderToken[];  // 注入到 useFactory 的 provider tokens
+  useFactory: (...deps: unknown[]) => T | Promise<T>;  // 异步工厂函数
+}
+```
+
+## 支持的模块
+
+- **ConfigModule**：异步加载配置
+- **DatabaseModule**：异步配置数据库连接
+- **CacheModule**：异步配置缓存（如 Redis 连接）
+
+## 示例：ConfigModule.forRootAsync
+
+```ts
+import {
+  Application,
+  ConfigModule,
+  ConfigService,
+  CONFIG_SERVICE_TOKEN,
+  Controller,
+  GET,
+  Inject,
+  Module,
+} from '@dangao/bun-server';
+
+async function loadRemoteConfig(): Promise<{ app: { name: string; port: number } }> {
+  console.log('[Config] 正在加载远程配置...');
+  await new Promise((resolve) => setTimeout(resolve, 200));
+  return {
+    app: { name: 'AsyncConfigApp', port: 3000 },
+  };
+}
+
+@Controller('/api')
+class AppController {
+  public constructor(
+    @Inject(CONFIG_SERVICE_TOKEN) private readonly config: ConfigService,
+  ) {}
+
+  @GET('/config')
+  public getConfig(): object {
+    return {
+      name: this.config.get('app.name'),
+      port: this.config.get('app.port'),
+    };
+  }
+}
+
+@Module({
+  imports: [
+    ConfigModule.forRootAsync({
+      useFactory: async () => {
+        const remoteConfig = await loadRemoteConfig();
+        return { defaultConfig: remoteConfig };
+      },
+    }),
+  ],
+  controllers: [AppController],
+})
+class AppModule {}
+
+const app = new Application({ port: 3000 });
+app.registerModule(AppModule);
+await app.listen();
+```
+
+## 示例：DatabaseModule.forRootAsync 配合 ConfigService
+
+```ts
+import { ConfigModule, CONFIG_SERVICE_TOKEN } from '@dangao/bun-server';
+import type { ConfigService } from '@dangao/bun-server';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ defaultConfig: { db: { url: '...' } } }),
+    DatabaseModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [CONFIG_SERVICE_TOKEN],
+      useFactory: (config: ConfigService) => ({
+        url: config.get<string>('db.url'),
+        // 其他数据库配置
+      }),
+    }),
+  ],
+})
+class AppModule {}
+```
+
+异步 provider 在 `Application.listen()` 期间顺序初始化，确保在应用开始处理请求前配置已就绪。

package/docs/zh/client-generation.md

@@ -0,0 +1,92 @@
+# 类型安全客户端生成
+
+Bun Server 支持从服务端路由自动生成类型安全的 API 客户端，便于前端或微服务调用。
+
+## ClientGenerator.generate()
+
+从当前已注册的 `RouteRegistry` 提取路由清单：
+
+```ts
+import { ClientGenerator } from '@dangao/bun-server';
+
+const manifest = ClientGenerator.generate();
+// { routes: [{ method, path, controllerName, methodName }, ...] }
+```
+
+## createClient(manifest, config)
+
+根据清单和配置创建 API 客户端：
+
+```ts
+import { createClient } from '@dangao/bun-server';
+
+const client = createClient(manifest, {
+  baseUrl: 'http://localhost:3001',
+  headers: { 'X-API-Key': 'xxx' },
+});
+```
+
+## 客户端结构
+
+客户端按控制器名称分组（去除 `Controller` 后缀并首字母小写），每个方法名对应一个函数：
+
+- `UserController` → `client.user`
+- `getUser` → `client.user.getUser({ params: { id: '1' } })`
+
+## 完整示例
+
+```ts
+import {
+  Application,
+  Controller,
+  GET,
+  POST,
+  Param,
+  Body,
+  Module,
+  ClientGenerator,
+  createClient,
+} from '@dangao/bun-server';
+
+@Controller('/api/users')
+class UserController {
+  @GET('/')
+  public listUsers(): object {
+    return [{ id: '1', name: 'Alice' }, { id: '2', name: 'Bob' }];
+  }
+
+  @GET('/:id')
+  public getUser(@Param('id') id: string): object {
+    return { id, name: 'Alice' };
+  }
+
+  @POST('/')
+  public createUser(@Body() body: unknown): object {
+    return { ...(body as object), id: '3' };
+  }
+}
+
+@Module({ controllers: [UserController] })
+class AppModule {}
+
+const app = new Application({ port: 3001, enableSignalHandlers: false });
+app.registerModule(AppModule);
+await app.listen();
+
+// 从已注册控制器生成路由清单
+const manifest = ClientGenerator.generate();
+
+// 创建类型安全客户端
+const client = createClient(manifest, {
+  baseUrl: 'http://localhost:3001',
+});
+
+// 调用 API
+const users = await client.user.listUsers();
+const user = await client.user.getUser({ params: { id: '42' } });
+const newUser = await client.user.createUser({ body: { name: 'Charlie' } });
+
+await app.stop();
+```
+
+`ClientRequestOptions` 支持 `params`、`query`、`body`、`headers`，路径中的 `:id` 等占位符会通过 `params` 自动替换。

package/docs/zh/cluster.md

@@ -0,0 +1,74 @@
+# 零配置集群
+
+`ClusterManager` 提供零配置集群模式，自动派生多个 worker 进程，利用多核 CPU 提升吞吐量。
+
+## ClusterManager 类
+
+```ts
+import { ClusterManager } from '@dangao/bun-server';
+
+const manager = new ClusterManager({
+  workers: 'auto',           // 或具体数字，'auto' 表示 CPU 核心数
+  scriptPath: import.meta.path,
+  port: 3300,
+  hostname: '0.0.0.0',      // 可选
+});
+
+manager.start();
+```
+
+## 主进程 / 工作进程
+
+- **ClusterManager.isWorker()**：判断当前进程是否为 worker
+- **ClusterManager.getWorkerId()**：获取当前 worker ID（仅 worker 进程有效，主进程返回 -1）
+
+主进程负责派生 worker，worker 进程运行应用逻辑。每个 worker 使用 `reusePort` 绑定同一端口。
+
+## Linux reusePort 限制
+
+`reusePort`（SO_REUSEPORT）仅在 **Linux** 上有效。macOS 和 Windows 会忽略该选项，多 worker 将无法共享同一端口，需在对应系统上单独验证行为。
+
+## 使用示例
+
+```ts
+import { ClusterManager, Application, Controller, GET, Module } from '@dangao/bun-server';
+
+const PORT = Number(process.env.PORT ?? 3300);
+
+if (!ClusterManager.isWorker()) {
+  // 主进程：派生 worker
+  const manager = new ClusterManager({
+    workers: process.env.WORKERS ? Number(process.env.WORKERS) : 'auto',
+    scriptPath: import.meta.path,
+    port: PORT,
+  });
+  manager.start();
+
+  process.on('SIGINT', async () => {
+    await manager.stop();
+    process.exit(0);
+  });
+} else {
+  // Worker 进程：运行应用
+  @Controller('/api')
+  class PerfController {
+    @GET('/ping')
+    public ping(): object {
+      return { pong: true, worker: ClusterManager.getWorkerId() };
+    }
+  }
+
+  @Module({ controllers: [PerfController] })
+  class WorkerModule {}
+
+  const app = new Application({
+    port: PORT,
+    reusePort: true,
+    enableSignalHandlers: true,
+  });
+  app.registerModule(WorkerModule);
+  await app.listen();
+}
+```
+
+Worker 异常退出时，主进程会自动重启对应 worker。

package/docs/zh/custom-decorators.md

@@ -29,12 +29,10 @@ AOP（面向切面编程）。这使您能够添加横切关注点，如缓存
 
 ### 基本装饰器模式
 
-自定义装饰器是一个返回 `MethodDecorator` 的函数。它使用 `reflect-metadata`
+自定义装饰器是一个返回 `MethodDecorator` 的函数。它使用 Reflect 元数据 API
 在方法上存储元数据。
 
 ```typescript
-import "reflect-metadata";
-
 // 1. 定义元数据键（使用 Symbol 确保唯一性）
 export const MY_METADATA_KEY = Symbol("@my-app:my-decorator");
 
@@ -280,8 +278,6 @@ class MyInterceptor extends BaseInterceptor {
 ### 存储元数据
 
 ```typescript
-import "reflect-metadata";
-
 const METADATA_KEY = Symbol("my-metadata");
 
 // 存储元数据
@@ -364,7 +360,6 @@ class MyInterceptor extends BaseInterceptor {
 ### 示例 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';
@@ -402,7 +397,6 @@ export class LogInterceptor extends BaseInterceptor {
 ### 示例 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';

package/docs/zh/dashboard.md

@@ -0,0 +1,69 @@
+# 监控仪表盘模块
+
+`DashboardModule` 提供 Web UI 和 API，用于监控应用状态、路由和健康检查。
+
+## 配置
+
+```ts
+import { DashboardModule } from '@dangao/bun-server';
+
+DashboardModule.forRoot({
+  path: '/_dashboard',  // UI 路径，默认 /_dashboard
+  auth: {               // 可选，Basic Auth
+    username: 'admin',
+    password: 'admin',
+  },
+});
+```
+
+## 可用端点
+
+- **UI**：`GET /_dashboard`，监控仪表盘主页面
+- **系统信息**：`GET /_dashboard/api/system`，运行时间、内存、平台、Bun 版本
+- **路由列表**：`GET /_dashboard/api/routes`，已注册路由及控制器、方法名
+- **健康检查**：`GET /_dashboard/api/health`，若已注册 HealthModule 则执行健康指示器
+
+## Basic Auth
+
+配置 `auth` 后，访问上述端点需提供 Basic 认证。未配置时无需认证。
+
+## 使用示例
+
+```ts
+import {
+  Application,
+  Controller,
+  GET,
+  Module,
+  DashboardModule,
+} from '@dangao/bun-server';
+
+@Controller('/api')
+class AppController {
+  @GET('/hello')
+  public hello(): object {
+    return { message: 'Hello from Dashboard!' };
+  }
+}
+
+@Module({
+  imports: [
+    DashboardModule.forRoot({
+      path: '/_dashboard',
+      auth: { username: 'admin', password: 'admin' },
+    }),
+  ],
+  controllers: [AppController],
+})
+class AppModule {}
+
+const app = new Application({ port: 3000 });
+app.registerModule(AppModule);
+await app.listen();
+// Dashboard UI: http://localhost:3000/_dashboard
+// 认证：admin / admin
+```
+
+## UI 界面
+
+仪表盘 UI 展示系统信息、路由列表和健康状态，便于运维和调试。

package/docs/zh/debug.md

@@ -0,0 +1,81 @@
+# 调试与请求重放模块
+
+`DebugModule` 在开发模式下录制 HTTP 请求，支持查看和重放，便于调试和问题复现。
+
+## 配置
+
+```ts
+import { DebugModule } from '@dangao/bun-server';
+
+DebugModule.forRoot({
+  enabled: true,      // 是否启用，默认 true
+  maxRecords: 500,    // 最大录制数（环形缓冲区），默认 500
+  recordBody: true,  // 是否录制请求体，默认 true
+  path: '/_debug',   // Debug UI 路径，默认 /_debug
+});
+```
+
+## 录制内容
+
+每条记录包含：
+
+- **request**：方法、路径、头部、请求体（可选）
+- **response**：状态码、响应头、响应体大小
+- **timing**：总耗时
+- **metadata**：匹配路由、控制器、方法名
+
+## Debug UI 端点
+
+- **UI**：`GET /_debug`，调试界面
+- **记录列表**：`GET /_debug/api/records`，获取所有录制
+- **清空记录**：`DELETE /_debug/api/records`
+- **单条记录**：`GET /_debug/api/records/:id`
+- **请求重放**：`POST /_debug/api/replay/:id`，按原请求重放并返回结果
+
+## 使用示例
+
+```ts
+import {
+  Application,
+  Controller,
+  GET,
+  POST,
+  Body,
+  Module,
+  DebugModule,
+} from '@dangao/bun-server';
+
+@Controller('/api')
+class AppController {
+  @GET('/hello')
+  public hello(): object {
+    return { message: 'Hello!' };
+  }
+
+  @POST('/echo')
+  public echo(@Body() body: unknown): unknown {
+    return body;
+  }
+}
+
+@Module({
+  imports: [
+    DebugModule.forRoot({
+      enabled: true,
+      maxRecords: 100,
+      recordBody: true,
+      path: '/_debug',
+    }),
+  ],
+  controllers: [AppController],
+})
+class AppModule {}
+
+const app = new Application({ port: 3000 });
+app.registerModule(AppModule);
+await app.listen();
+// Debug UI: http://localhost:3000/_debug
+// 发送请求后可在 UI 中查看录制并重放
+```
+
+建议仅在开发环境启用，生产环境可通过 `enabled: false` 关闭。

package/docs/zh/extensions.md

@@ -511,8 +511,6 @@ app.listen();
 ### 创建装饰器
 
 ```typescript
-import "reflect-metadata";
-
 // 缓存装饰器
 export function Cache(ttl: number) {
   return function (

package/docs/zh/guide.md

@@ -15,7 +15,6 @@ HTTP 请求 → 中间件 → 安全 → 路由 → 拦截器(前置) → 验证
 ## 1. 初始化应用
 
 ```ts
-import "reflect-metadata";
 import { Application } from "@dangao/bun-server";
 
 const app = new Application({ port: 3000 });