@dangao/bun-server 2.1.0 → 2.2.0

package/docs/lifecycle.md

@@ -1,21 +1,29 @@
 # Lifecycle Hooks
 
-Bun Server supports lifecycle hooks that let providers participate in application startup and shutdown. Implement the appropriate interface on your injectable services.
+Bun Server supports lifecycle hooks that let components (`@Injectable` / `@Controller`) participate from creation to destruction.
 
 ## Interfaces
 
 | Interface | Method | When Called |
 |-----------|--------|-------------|
+| `ComponentClassBeforeCreate` | `static onBeforeCreate()` | Right before the component instance is created |
+| `OnAfterCreate` | `onAfterCreate()` | Right after instance creation and post processors |
 | `OnModuleInit` | `onModuleInit()` | After all module providers are registered |
 | `OnModuleDestroy` | `onModuleDestroy()` | During shutdown (reverse order) |
+| `OnBeforeDestroy` | `onBeforeDestroy()` | Before `onModuleDestroy` during shutdown (reverse order) |
+| `OnAfterDestroy` | `onAfterDestroy()` | After `onModuleDestroy` during shutdown (reverse order) |
 | `OnApplicationBootstrap` | `onApplicationBootstrap()` | After all modules init, before server listens |
 | `OnApplicationShutdown` | `onApplicationShutdown(signal?)` | When graceful shutdown begins |
 
 ## Execution Order
 
+**Creation (per component instance)**: `onBeforeCreate` (static) -> instantiate -> `onAfterCreate`
+
 **Startup**: `onModuleInit` (all modules) -> `onApplicationBootstrap` (all modules) -> server starts
 
-**Shutdown**: `onApplicationShutdown` (reverse order) -> `onModuleDestroy` (reverse order)
+**Shutdown**: `onApplicationShutdown` (reverse order) -> `onBeforeDestroy` (reverse order) -> `onModuleDestroy` (reverse order) -> `onAfterDestroy` (reverse order)
+
+For `Lifecycle.Scoped` components, destroy hooks are executed automatically at the end of each request context.
 
 ## Provider Deduplication
 
@@ -23,19 +31,41 @@ When the same provider instance is exported or registered by multiple tokens,
 `onModuleInit` now runs only once for that instance. This avoids duplicate
 initialization side effects in shared singleton objects.
 
-## Example: DatabaseService with init/destroy
+## Example: Component hooks from create to destroy
 
 ```ts
 import {
   Injectable,
+  Controller,
+  GET,
+  Module,
   OnModuleInit,
   OnModuleDestroy,
+  type ComponentClassBeforeCreate,
+  OnAfterCreate,
+  OnBeforeDestroy,
+  OnAfterDestroy,
 } from '@dangao/bun-server';
 
 @Injectable()
-class DatabaseService implements OnModuleInit, OnModuleDestroy {
+class DatabaseService
+  implements
+    OnAfterCreate,
+    OnModuleInit,
+    OnBeforeDestroy,
+    OnModuleDestroy,
+    OnAfterDestroy
+{
   private connected = false;
 
+  public static onBeforeCreate(): void {
+    console.log('[DatabaseService] Before create');
+  }
+
+  public onAfterCreate(): void {
+    console.log('[DatabaseService] After create');
+  }
+
   public async onModuleInit(): Promise<void> {
     console.log('[DatabaseService] Connecting...');
     await this.connect();
@@ -48,6 +78,14 @@ class DatabaseService implements OnModuleInit, OnModuleDestroy {
     this.connected = false;
   }
 
+  public onBeforeDestroy(): void {
+    console.log('[DatabaseService] Before destroy');
+  }
+
+  public onAfterDestroy(): void {
+    console.log('[DatabaseService] After destroy');
+  }
+
   public isConnected(): boolean {
     return this.connected;
   }
@@ -60,6 +98,36 @@ class DatabaseService implements OnModuleInit, OnModuleDestroy {
     // Close DB connection
   }
 }
+
+@Controller('/health')
+class HealthController implements OnAfterCreate, OnBeforeDestroy, OnAfterDestroy {
+  public static onBeforeCreate(): void {
+    console.log('[HealthController] Before create');
+  }
+
+  public onAfterCreate(): void {
+    console.log('[HealthController] After create');
+  }
+
+  public onBeforeDestroy(): void {
+    console.log('[HealthController] Before destroy');
+  }
+
+  public onAfterDestroy(): void {
+    console.log('[HealthController] After destroy');
+  }
+
+  @GET('/')
+  public get(): object {
+    return { ok: true };
+  }
+}
+
+@Module({
+  controllers: [HealthController],
+  providers: [DatabaseService],
+})
+class AppModule {}
 ```
 
 ## Example: Application-level hooks
@@ -75,4 +143,6 @@ class AppService implements OnApplicationBootstrap, OnApplicationShutdown {
     console.log(`Shutting down (signal: ${signal ?? 'none'})`);
   }
 }
+
+const _beforeCreateHook: ComponentClassBeforeCreate = DatabaseService;
 ```

package/docs/zh/lifecycle.md

@@ -1,24 +1,31 @@
 # 生命周期钩子
 
-Bun Server 提供四个生命周期接口，用于在模块和应用启动、关闭时执行初始化或清理逻辑。
+Bun Server 支持组件级生命周期钩子，可让 `@Injectable` / `@Controller` 从创建前到销毁后执行自定义逻辑。
 
 ## 接口定义
 
-- **OnModuleInit**：`onModuleInit()`，在模块所有 providers 注册完成后调用
-- **OnModuleDestroy**：`onModuleDestroy()`，在应用关闭时调用（反向顺序）
+- **ComponentClassBeforeCreate**：`static onBeforeCreate()`，组件实例创建前调用
+- **OnAfterCreate**：`onAfterCreate()`，组件实例创建并完成后处理后调用
+- **OnModuleInit**：`onModuleInit()`，在模块所有组件初始化阶段调用
 - **OnApplicationBootstrap**：`onApplicationBootstrap()`，在所有模块初始化完成后、服务器开始监听前调用
 - **OnApplicationShutdown**：`onApplicationShutdown(signal?)`，在优雅停机开始时调用
+- **OnBeforeDestroy**：`onBeforeDestroy()`，在 `onModuleDestroy()` 前调用（反向顺序）
+- **OnModuleDestroy**：`onModuleDestroy()`，在应用关闭时调用（反向顺序）
+- **OnAfterDestroy**：`onAfterDestroy()`，在 `onModuleDestroy()` 后调用（反向顺序）
 
 ## 执行顺序
 
+**创建阶段（每个组件实例）**：`onBeforeCreate`（静态）→ 实例化 → `onAfterCreate`
+
 **启动阶段**：`onModuleInit` → `onApplicationBootstrap`
 
-**关闭阶段**：`onApplicationShutdown` → `onModuleDestroy`（均为反向顺序，即后注册的先执行）
+**关闭阶段**：`onApplicationShutdown` → `onBeforeDestroy` → `onModuleDestroy` → `onAfterDestroy`（均为反向顺序，即后注册的先执行）
 
-## Provider 去重行为
+对于 `Lifecycle.Scoped` 组件，请求上下文结束时会自动触发其销毁钩子。
 
-当同一个 provider 实例通过多个 token 重复注册/导出时，`onModuleInit`
-现只会执行一次，避免共享单例出现重复初始化副作用。
+## 组件去重行为
+
+当同一个组件实例通过多个 token 重复注册/导出时，生命周期钩子只会执行一次，避免共享单例出现重复副作用。
 
 ## 示例：DatabaseService 的初始化和销毁
 
@@ -41,6 +48,14 @@ import type {
 class DatabaseService implements OnModuleInit, OnModuleDestroy {
   private connected = false;
 
+  public static onBeforeCreate(): void {
+    console.log('[DatabaseService] 创建前');
+  }
+
+  public onAfterCreate(): void {
+    console.log('[DatabaseService] 创建后');
+  }
+
   public async onModuleInit(): Promise<void> {
     console.log('[DatabaseService] 正在连接数据库...');
     await new Promise((resolve) => setTimeout(resolve, 100));
@@ -54,6 +69,14 @@ class DatabaseService implements OnModuleInit, OnModuleDestroy {
     console.log('[DatabaseService] 已断开');
   }
 
+  public onBeforeDestroy(): void {
+    console.log('[DatabaseService] 销毁前');
+  }
+
+  public onAfterDestroy(): void {
+    console.log('[DatabaseService] 销毁后');
+  }
+
   public isConnected(): boolean {
     return this.connected;
   }
@@ -72,6 +95,22 @@ class AppService implements OnApplicationBootstrap, OnApplicationShutdown {
 
 @Controller('/api')
 class AppController {
+  public static onBeforeCreate(): void {
+    console.log('[AppController] 创建前');
+  }
+
+  public onAfterCreate(): void {
+    console.log('[AppController] 创建后');
+  }
+
+  public onBeforeDestroy(): void {
+    console.log('[AppController] 销毁前');
+  }
+
+  public onAfterDestroy(): void {
+    console.log('[AppController] 销毁后');
+  }
+
   @GET('/status')
   public status(): object {
     return { status: 'running', timestamp: Date.now() };
@@ -89,4 +128,4 @@ app.registerModule(AppModule);
 await app.listen();
 ```
 
-按 Ctrl+C 触发关闭时，将依次执行 `onApplicationShutdown` 和 `onModuleDestroy`。
+按 Ctrl+C 触发关闭时，将依次执行 `onApplicationShutdown`、`onBeforeDestroy`、`onModuleDestroy`、`onAfterDestroy`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dangao/bun-server",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/core/application.ts

@@ -324,6 +324,7 @@ export class Application {
    */
   private async handleRequest(context: Context): Promise<Response> {
     const logger = LoggerManager.getLogger();
+    const moduleRegistry = ModuleRegistry.getInstance();
     logger.debug('[Request] Incoming', {
       method: context.method,
       path: context.path,
@@ -332,34 +333,46 @@ export class Application {
 
     // 使用 AsyncLocalStorage 包裹请求处理，确保所有中间件和控制器都在请求上下文中执行
     return await contextStore.run(context, async () => {
-      // 对于 POST、PUT、PATCH 请求，提前解析 body 并缓存
-      // 这样可以确保 Request.body 流只读取一次
-      if (['POST', 'PUT', 'PATCH'].includes(context.method)) {
-        await context.getBody();
-      }
+      try {
+        // 对于 POST、PUT、PATCH 请求，提前解析 body 并缓存
+        // 这样可以确保 Request.body 流只读取一次
+        if (['POST', 'PUT', 'PATCH'].includes(context.method)) {
+          await context.getBody();
+        }
 
-      // 先通过路由解析出处理器信息，便于安全中间件等基于路由元数据做决策
-      const registry = RouteRegistry.getInstance();
-      const router = registry.getRouter();
+        // 先通过路由解析出处理器信息，便于安全中间件等基于路由元数据做决策
+        const registry = RouteRegistry.getInstance();
+        const router = registry.getRouter();
 
-      // 预解析路由，仅设置上下文信息，不执行处理器
-      await router.preHandle(context);
+        // 预解析路由，仅设置上下文信息，不执行处理器
+        await router.preHandle(context);
 
-      // 再进入中间件管道，由中间件（如安全过滤器）根据 routeHandler 和 Auth 元数据做校验，
-      // 最后再由路由真正执行控制器方法
-      return await this.middlewarePipeline.run(context, async () => {
-        const response = await router.handle(context);
-        if (response) {
-          return response;
-        }
+        // 再进入中间件管道，由中间件（如安全过滤器）根据 routeHandler 和 Auth 元数据做校验，
+        // 最后再由路由真正执行控制器方法
+        return await this.middlewarePipeline.run(context, async () => {
+          const response = await router.handle(context);
+          if (response) {
+            return response;
+          }
 
-        logger.debug('[Router] No route matched', {
-          method: context.method,
-          path: context.path,
+          logger.debug('[Router] No route matched', {
+            method: context.method,
+            path: context.path,
+          });
+          context.setStatus(404);
+          return context.createErrorResponse({ error: 'Not Found' });
         });
-        context.setStatus(404);
-        return context.createErrorResponse({ error: 'Not Found' });
-      });
+      } finally {
+        try {
+          await moduleRegistry.disposeScopedInstances(context);
+        } catch (error) {
+          logger.warn('[Application] Failed to dispose scoped instances', {
+            path: context.path,
+            method: context.method,
+            errorMessage: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
     });
   }
 

package/src/di/container.ts

@@ -14,6 +14,13 @@ import {
 import { LoggerManager } from "@dangao/logsmith";
 import type { Constructor } from "@/core/types";
 import { contextStore } from "../core/context-service";
+import {
+  callComponentBeforeCreate,
+  callOnAfterCreate,
+  callOnBeforeDestroy,
+  callOnModuleDestroy,
+  callOnAfterDestroy,
+} from "./lifecycle";
 
 /**
  * 依赖注入容器
@@ -365,6 +372,7 @@ export class Container {
    * @returns 实例
    */
   private instantiate<T>(constructor: Constructor<T>): T {
+    callComponentBeforeCreate(constructor);
     const plan = this.getDependencyPlan(constructor);
 
     let instance: T;
@@ -379,7 +387,9 @@ export class Container {
     }
 
     // 应用后处理器
-    return this.applyPostProcessors(instance, constructor);
+    const processed = this.applyPostProcessors(instance, constructor);
+    callOnAfterCreate(processed);
+    return processed;
   }
 
   /**
@@ -409,6 +419,50 @@ export class Container {
     // scopedInstances 使用 WeakMap，当 Context 对象被 GC 时会自动清理
   }
 
+  /**
+   * 获取指定请求上下文下的 scoped 实例
+   * @param context - 请求上下文对象
+   * @returns 去重后的 scoped 实例列表
+   */
+  public getScopedInstances(context: object): unknown[] {
+    const scopedMap = this.scopedInstances.get(context);
+    if (!scopedMap || scopedMap.size === 0) {
+      return [];
+    }
+    const seen = new Set<unknown>();
+    const instances: unknown[] = [];
+    for (const instance of scopedMap.values()) {
+      if (!seen.has(instance)) {
+        seen.add(instance);
+        instances.push(instance);
+      }
+    }
+    return instances;
+  }
+
+  /**
+   * 清理指定请求上下文的 scoped 实例缓存
+   * @param context - 请求上下文对象
+   */
+  public clearScopedInstances(context: object): void {
+    this.scopedInstances.delete(context);
+  }
+
+  /**
+   * 触发指定请求上下文下 scoped 实例的销毁钩子并清理缓存
+   * @param context - 请求上下文对象
+   */
+  public async disposeScopedInstances(context: object): Promise<void> {
+    const instances = this.getScopedInstances(context);
+    if (instances.length === 0) {
+      return;
+    }
+    await callOnBeforeDestroy(instances);
+    await callOnModuleDestroy(instances);
+    await callOnAfterDestroy(instances);
+    this.clearScopedInstances(context);
+  }
+
   /**
    * 检查是否已注册
    * @param token - 提供者标识符

package/src/di/lifecycle.ts

@@ -30,6 +30,38 @@ export interface OnApplicationShutdown {
   onApplicationShutdown(signal?: string): Promise<void> | void;
 }
 
+/**
+ * 组件创建前钩子（静态类方法）
+ * 在实例化前调用，适用于 Controller / Injectable 类
+ */
+export type ComponentClassBeforeCreate = {
+  onBeforeCreate(): void;
+};
+
+/**
+ * 组件创建后钩子（实例）
+ * 在实例化并完成后处理后调用
+ */
+export interface OnAfterCreate {
+  onAfterCreate(): void;
+}
+
+/**
+ * 组件销毁前钩子（实例）
+ * 在 onModuleDestroy 之前调用（反向顺序）
+ */
+export interface OnBeforeDestroy {
+  onBeforeDestroy(): Promise<void> | void;
+}
+
+/**
+ * 组件销毁后钩子（实例）
+ * 在 onModuleDestroy 之后调用（反向顺序）
+ */
+export interface OnAfterDestroy {
+  onAfterDestroy(): Promise<void> | void;
+}
+
 export function hasOnModuleInit(instance: unknown): instance is OnModuleInit {
   return (
     instance !== null &&
@@ -70,6 +102,64 @@ export function hasOnApplicationShutdown(instance: unknown): instance is OnAppli
   );
 }
 
+export function hasComponentBeforeCreate(target: unknown): target is ComponentClassBeforeCreate {
+  return (
+    target !== null &&
+    target !== undefined &&
+    typeof target === 'function' &&
+    'onBeforeCreate' in target &&
+    typeof (target as ComponentClassBeforeCreate).onBeforeCreate === 'function'
+  );
+}
+
+export function hasOnAfterCreate(instance: unknown): instance is OnAfterCreate {
+  return (
+    instance !== null &&
+    instance !== undefined &&
+    typeof instance === 'object' &&
+    'onAfterCreate' in instance &&
+    typeof (instance as OnAfterCreate).onAfterCreate === 'function'
+  );
+}
+
+export function hasOnBeforeDestroy(instance: unknown): instance is OnBeforeDestroy {
+  return (
+    instance !== null &&
+    instance !== undefined &&
+    typeof instance === 'object' &&
+    'onBeforeDestroy' in instance &&
+    typeof (instance as OnBeforeDestroy).onBeforeDestroy === 'function'
+  );
+}
+
+export function hasOnAfterDestroy(instance: unknown): instance is OnAfterDestroy {
+  return (
+    instance !== null &&
+    instance !== undefined &&
+    typeof instance === 'object' &&
+    'onAfterDestroy' in instance &&
+    typeof (instance as OnAfterDestroy).onAfterDestroy === 'function'
+  );
+}
+
+/**
+ * 调用组件类静态 onBeforeCreate
+ */
+export function callComponentBeforeCreate(target: unknown): void {
+  if (hasComponentBeforeCreate(target)) {
+    target.onBeforeCreate();
+  }
+}
+
+/**
+ * 调用组件实例 onAfterCreate
+ */
+export function callOnAfterCreate(instance: unknown): void {
+  if (hasOnAfterCreate(instance)) {
+    instance.onAfterCreate();
+  }
+}
+
 /**
  * 按顺序调用 onModuleInit
  */
@@ -115,3 +205,27 @@ export async function callOnApplicationShutdown(instances: unknown[], signal?: s
     }
   }
 }
+
+/**
+ * 按反向顺序调用 onBeforeDestroy
+ */
+export async function callOnBeforeDestroy(instances: unknown[]): Promise<void> {
+  for (let i = instances.length - 1; i >= 0; i--) {
+    const instance = instances[i];
+    if (hasOnBeforeDestroy(instance)) {
+      await instance.onBeforeDestroy();
+    }
+  }
+}
+
+/**
+ * 按反向顺序调用 onAfterDestroy
+ */
+export async function callOnAfterDestroy(instances: unknown[]): Promise<void> {
+  for (let i = instances.length - 1; i >= 0; i--) {
+    const instance = instances[i];
+    if (hasOnAfterDestroy(instance)) {
+      await instance.onAfterDestroy();
+    }
+  }
+}

package/src/di/module-registry.ts

@@ -11,6 +11,8 @@ import {
   callOnModuleDestroy,
   callOnApplicationBootstrap,
   callOnApplicationShutdown,
+  callOnBeforeDestroy,
+  callOnAfterDestroy,
 } from './lifecycle';
 
 interface ModuleRef {
@@ -225,9 +227,9 @@ export class ModuleRegistry {
   }
 
   /**
-   * 解析所有模块中的 provider 实例，用于生命周期钩子调用
+   * 解析所有模块中的组件实例（providers + controllers），用于生命周期钩子调用
    */
-  public resolveAllProviderInstances(): unknown[] {
+  public resolveAllComponentInstances(): unknown[] {
     const instances: unknown[] = [];
     const seen = new Set<unknown>();
     for (const [, ref] of this.moduleRefs) {
@@ -262,42 +264,88 @@ export class ModuleRegistry {
           // skip providers that can't be resolved (e.g. pending async providers)
         }
       }
+      for (const controller of ref.metadata.controllers) {
+        try {
+          const instance = ref.container.resolve(controller);
+          if (!seen.has(instance)) {
+            seen.add(instance);
+            instances.push(instance);
+          }
+        } catch (_error) {
+          // skip controllers that can't be resolved
+        }
+      }
     }
     return instances;
   }
 
   /**
-   * 调用所有 provider 的 onModuleInit 钩子
+   * 调用所有组件（providers + controllers）的 onModuleInit 钩子
    */
   public async callModuleInitHooks(): Promise<void> {
-    const instances = this.resolveAllProviderInstances();
+    const instances = this.resolveAllComponentInstances();
     await callOnModuleInit(instances);
   }
 
   /**
-   * 调用所有 provider 的 onApplicationBootstrap 钩子
+   * 调用所有组件（providers + controllers）的 onApplicationBootstrap 钩子
    */
   public async callBootstrapHooks(): Promise<void> {
-    const instances = this.resolveAllProviderInstances();
+    const instances = this.resolveAllComponentInstances();
     await callOnApplicationBootstrap(instances);
   }
 
   /**
-   * 调用所有 provider 的 onModuleDestroy 钩子
+   * 调用所有组件（providers + controllers）的 onModuleDestroy 钩子
    */
   public async callModuleDestroyHooks(): Promise<void> {
-    const instances = this.resolveAllProviderInstances();
+    const instances = this.resolveAllComponentInstances();
+    await callOnBeforeDestroy(instances);
     await callOnModuleDestroy(instances);
+    await callOnAfterDestroy(instances);
   }
 
   /**
-   * 调用所有 provider 的 onApplicationShutdown 钩子
+   * 调用所有组件（providers + controllers）的 onApplicationShutdown 钩子
    */
   public async callShutdownHooks(signal?: string): Promise<void> {
-    const instances = this.resolveAllProviderInstances();
+    const instances = this.resolveAllComponentInstances();
     await callOnApplicationShutdown(instances, signal);
   }
 
+  /**
+   * 调用当前请求上下文下 scoped 组件的销毁钩子并清理缓存
+   */
+  public async disposeScopedInstances(context: object): Promise<void> {
+    const containers: Container[] = [];
+    if (this.rootContainer) {
+      containers.push(this.rootContainer);
+    }
+    containers.push(...this.getAllModuleContainers());
+
+    const instances: unknown[] = [];
+    const seen = new Set<unknown>();
+    for (const container of containers) {
+      const scopedInstances = container.getScopedInstances(context);
+      for (const instance of scopedInstances) {
+        if (!seen.has(instance)) {
+          seen.add(instance);
+          instances.push(instance);
+        }
+      }
+    }
+
+    if (instances.length > 0) {
+      await callOnBeforeDestroy(instances);
+      await callOnModuleDestroy(instances);
+      await callOnAfterDestroy(instances);
+    }
+
+    for (const container of containers) {
+      container.clearScopedInstances(context);
+    }
+  }
+
   private registerExport(parentContainer: Container, moduleRef: ModuleRef, token: ProviderToken): void {
     if (!moduleRef.container.isRegistered(token)) {
       throw new Error(

package/src/index.ts

@@ -42,6 +42,10 @@ export type {
   OnModuleDestroy,
   OnApplicationBootstrap,
   OnApplicationShutdown,
+  ComponentClassBeforeCreate,
+  OnAfterCreate,
+  OnBeforeDestroy,
+  OnAfterDestroy,
 } from './di/lifecycle';
 export {
   InterceptorRegistry,