@dangao/bun-server 1.4.0 → 1.6.0

package/dist/core/application.d.ts

@@ -15,6 +15,16 @@ export interface ApplicationOptions {
      * 主机名
      */
     hostname?: string;
+    /**
+     * 优雅停机超时时间（毫秒）
+     * 默认 30 秒
+     */
+    gracefulShutdownTimeout?: number;
+    /**
+     * 是否启用信号监听（SIGTERM、SIGINT）
+     * 默认 true
+     */
+    enableSignalHandlers?: boolean;
 }
 /**
  * 应用主类
@@ -26,6 +36,7 @@ export declare class Application {
     private readonly middlewarePipeline;
     private readonly websocketRegistry;
     private readonly extensions;
+    private signalHandlersInstalled;
     constructor(options?: ApplicationOptions);
     /**
      * 注册全局中间件
@@ -46,9 +57,16 @@ export declare class Application {
      */
     private initializeConfigCenter;
     /**
-     * 停止应用
+     * 停止应用（立即停止，不等待请求完成）
      */
     stop(): Promise<void>;
+    /**
+     * 优雅停机
+     * 停止接受新请求，等待正在处理的请求完成，然后关闭应用
+     * @param timeout - 超时时间（毫秒），默认使用配置的 gracefulShutdownTimeout 或 30000
+     * @returns Promise，在停机完成时 resolve
+     */
+    gracefulShutdown(timeout?: number): Promise<void>;
     /**
      * 关闭所有扩展
      */
@@ -99,5 +117,13 @@ export declare class Application {
      * @returns DI 容器
      */
     getContainer(): import("..").Container;
+    /**
+     * 安装信号处理器（SIGTERM、SIGINT）
+     */
+    private installSignalHandlers;
+    /**
+     * 移除信号处理器
+     */
+    private removeSignalHandlers;
 }
 //# sourceMappingURL=application.d.ts.map

package/dist/core/application.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../../src/core/application.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAsB,MAAM,UAAU,CAAC;AAMzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAM3C;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAC,CAAY;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA2B;IAC7D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;gBAEtC,OAAO,GAAE,kBAAuB;IAsBnD;;;OAGG;IACI,GAAG,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI;IAIxC;;OAEG;IACU,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BpE;;OAEG;YACW,oBAAoB;IAqBlC;;;OAGG;YACW,sBAAsB;IAyBpC;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IASlC;;OAEG;YACW,eAAe;IAkB7B;;;;OAIG;YACW,aAAa;IA8B3B;;;OAGG;IACI,kBAAkB,CAAC,eAAe,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI;IAKtE;;;OAGG;IACI,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAgBrD;;;OAGG;IACI,wBAAwB,CAAC,YAAY,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI;IAIzE;;;OAGG;IACI,iBAAiB,CAAC,SAAS,EAAE,oBAAoB,GAAG,IAAI;IAK/D;;;OAGG;IACI,SAAS,IAAI,SAAS,GAAG,SAAS;IAIzC;;;OAGG;YACW,gBAAgB;IAsB9B;;;OAGG;YACW,kBAAkB;IAwBhC;;;OAGG;IACI,YAAY;CAGpB"}
+{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../../src/core/application.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAsB,MAAM,UAAU,CAAC;AAMzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAO3C;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAEjC;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAC,CAAY;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA2B;IAC7D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;IACzD,OAAO,CAAC,uBAAuB,CAAkB;gBAE9B,OAAO,GAAE,kBAAuB;IAsBnD;;;OAGG;IACI,GAAG,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI;IAIxC;;OAEG;IACU,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkCpE;;OAEG;YACW,oBAAoB;IAqBlC;;;OAGG;YACW,sBAAsB;IAyBpC;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAYlC;;;;;OAKG;IACU,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB9D;;OAEG;YACW,eAAe;IAkB7B;;;;OAIG;YACW,aAAa;IA8B3B;;;OAGG;IACI,kBAAkB,CAAC,eAAe,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI;IAKtE;;;OAGG;IACI,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAgBrD;;;OAGG;IACI,wBAAwB,CAAC,YAAY,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI;IAIzE;;;OAGG;IACI,iBAAiB,CAAC,SAAS,EAAE,oBAAoB,GAAG,IAAI;IAK/D;;;OAGG;IACI,SAAS,IAAI,SAAS,GAAG,SAAS;IAIzC;;;OAGG;YACW,gBAAgB;IAsB9B;;;OAGG;YACW,kBAAkB;IAwBhC;;;OAGG;IACI,YAAY;IAInB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA2B7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;CAS7B"}

package/dist/core/server.d.ts

@@ -22,6 +22,11 @@ export interface ServerOptions {
      * WebSocket 网关注册表
      */
     websocketRegistry?: WebSocketGatewayRegistry;
+    /**
+     * 优雅停机超时时间（毫秒）
+     * 默认 30 秒
+     */
+    gracefulShutdownTimeout?: number;
 }
 /**
  * 服务器封装类
@@ -30,15 +35,34 @@ export interface ServerOptions {
 export declare class BunServer {
     private server?;
     private readonly options;
+    private activeRequests;
+    private isShuttingDown;
+    private shutdownPromise?;
+    private shutdownResolve?;
     constructor(options: ServerOptions);
     /**
      * 启动服务器
      */
     start(): void;
     /**
-     * 停止服务器
+     * 停止服务器（立即停止，不等待请求完成）
      */
     stop(): void;
+    /**
+     * 优雅停机
+     * 停止接受新请求，等待正在处理的请求完成
+     * @param timeout - 超时时间（毫秒），默认使用配置的 gracefulShutdownTimeout 或 30000
+     * @returns Promise，在停机完成时 resolve
+     */
+    gracefulShutdown(timeout?: number): Promise<void>;
+    /**
+     * 获取当前活跃请求数
+     */
+    getActiveRequests(): number;
+    /**
+     * 检查是否正在关闭
+     */
+    isShuttingDownState(): boolean;
     /**
      * 获取服务器实例
      * @returns Bun Server 实例

package/dist/core/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/core/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,KAAK,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE1D;;OAEG;IACH,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;CAC9C;AAED;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAC,CAAkC;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;gBAErB,OAAO,EAAE,aAAa;IAIzC;;OAEG;IACI,KAAK,IAAI,IAAI;IAsDpB;;OAEG;IACI,IAAI,IAAI,IAAI;IASnB;;;OAGG;IACI,SAAS,IAAI,MAAM,CAAC,uBAAuB,CAAC,GAAG,SAAS;IAI/D;;;OAGG;IACI,SAAS,IAAI,OAAO;IAI3B;;OAEG;IACI,OAAO,IAAI,MAAM;IAIxB;;OAEG;IACI,WAAW,IAAI,MAAM,GAAG,SAAS;CAGzC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/core/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,KAAK,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE1D;;OAEG;IACH,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;IAE7C;;;OAGG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAC,CAAkC;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,cAAc,CAAa;IACnC,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,eAAe,CAAC,CAAgB;IACxC,OAAO,CAAC,eAAe,CAAC,CAAa;gBAElB,OAAO,EAAE,aAAa;IAIzC;;OAEG;IACI,KAAK,IAAI,IAAI;IAmGpB;;OAEG;IACI,IAAI,IAAI,IAAI;IAWnB;;;;;OAKG;IACU,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2C9D;;OAEG;IACI,iBAAiB,IAAI,MAAM;IAIlC;;OAEG;IACI,mBAAmB,IAAI,OAAO;IAIrC;;;OAGG;IACI,SAAS,IAAI,MAAM,CAAC,uBAAuB,CAAC,GAAG,SAAS;IAI/D;;;OAGG;IACI,SAAS,IAAI,OAAO;IAI3B;;OAEG;IACI,OAAO,IAAI,MAAM;IAIxB;;OAEG;IACI,WAAW,IAAI,MAAM,GAAG,SAAS;CAGzC"}

package/dist/index.js

@@ -3235,6 +3235,10 @@ import { LoggerManager } from "@dangao/logsmith";
 class BunServer {
   server;
   options;
+  activeRequests = 0;
+  isShuttingDown = false;
+  shutdownPromise;
+  shutdownResolve;
   constructor(options) {
     this.options = options;
   }
@@ -3243,36 +3247,64 @@ class BunServer {
       throw new Error("Server is already running");
     }
     const logger = LoggerManager.getLogger();
+    this.activeRequests = 0;
+    this.isShuttingDown = false;
+    this.shutdownPromise = undefined;
+    this.shutdownResolve = undefined;
     this.server = Bun.serve({
       port: this.options.port ?? 3000,
       hostname: this.options.hostname,
       fetch: (request, server) => {
+        if (this.isShuttingDown) {
+          return new Response("Server is shutting down", { status: 503 });
+        }
         const upgradeHeader = request.headers.get("upgrade");
         if (this.options.websocketRegistry && upgradeHeader && upgradeHeader.toLowerCase() === "websocket") {
           const url = new URL(request.url);
           if (!this.options.websocketRegistry.hasGateway(url.pathname)) {
             return new Response("WebSocket gateway not found", { status: 404 });
           }
+          const context2 = new Context(request);
+          const queryParams = new URLSearchParams(url.searchParams);
           const upgraded = server.upgrade(request, {
-            data: { path: url.pathname }
+            data: {
+              path: url.pathname,
+              query: queryParams,
+              context: context2
+            }
           });
           if (upgraded) {
             return;
           }
           return new Response("WebSocket upgrade failed", { status: 400 });
         }
+        this.activeRequests++;
         const context = new Context(request);
-        return this.options.fetch(context);
+        const responsePromise = this.options.fetch(context);
+        if (responsePromise instanceof Promise) {
+          responsePromise.finally(() => {
+            this.activeRequests--;
+            if (this.isShuttingDown && this.activeRequests === 0 && this.shutdownResolve) {
+              this.shutdownResolve();
+            }
+          }).catch(() => {});
+        } else {
+          this.activeRequests--;
+          if (this.isShuttingDown && this.activeRequests === 0 && this.shutdownResolve) {
+            this.shutdownResolve();
+          }
+        }
+        return responsePromise;
       },
       websocket: {
-        open: (ws) => {
-          this.options.websocketRegistry?.handleOpen(ws);
+        open: async (ws) => {
+          await this.options.websocketRegistry?.handleOpen(ws);
         },
-        message: (ws, message) => {
-          this.options.websocketRegistry?.handleMessage(ws, message);
+        message: async (ws, message) => {
+          await this.options.websocketRegistry?.handleMessage(ws, message);
         },
-        close: (ws, code, reason) => {
-          this.options.websocketRegistry?.handleClose(ws, code, reason);
+        close: async (ws, code, reason) => {
+          await this.options.websocketRegistry?.handleClose(ws, code, reason);
         }
       }
     });
@@ -3285,9 +3317,45 @@ class BunServer {
       const logger = LoggerManager.getLogger();
       this.server.stop();
       this.server = undefined;
+      this.isShuttingDown = false;
+      this.activeRequests = 0;
       logger.info("Server stopped");
     }
   }
+  async gracefulShutdown(timeout) {
+    if (!this.server || this.isShuttingDown) {
+      return;
+    }
+    const logger = LoggerManager.getLogger();
+    const shutdownTimeout = timeout ?? this.options.gracefulShutdownTimeout ?? 30000;
+    logger.info(`Starting graceful shutdown (timeout: ${shutdownTimeout}ms, active requests: ${this.activeRequests})`);
+    this.isShuttingDown = true;
+    if (this.activeRequests === 0) {
+      this.stop();
+      logger.info("Graceful shutdown completed (no active requests)");
+      return;
+    }
+    if (!this.shutdownPromise) {
+      this.shutdownPromise = new Promise((resolve) => {
+        this.shutdownResolve = resolve;
+      });
+    }
+    const timeoutPromise = new Promise((resolve) => {
+      setTimeout(() => {
+        logger.warn(`Graceful shutdown timeout (${shutdownTimeout}ms), forcing shutdown`);
+        resolve();
+      }, shutdownTimeout);
+    });
+    await Promise.race([this.shutdownPromise, timeoutPromise]);
+    this.stop();
+    logger.info(`Graceful shutdown completed (remaining active requests: ${this.activeRequests})`);
+  }
+  getActiveRequests() {
+    return this.activeRequests;
+  }
+  isShuttingDownState() {
+    return this.isShuttingDown;
+  }
   getServer() {
     return this.server;
   }
@@ -3341,6 +3409,8 @@ function getHandlerMetadata(target) {
 }
 
 // src/websocket/registry.ts
+init_param_binder();
+init_decorators2();
 class WebSocketGatewayRegistry {
   static instance;
   container;
@@ -3381,47 +3451,90 @@ class WebSocketGatewayRegistry {
   getGateway(path) {
     return this.gateways.get(path);
   }
-  getGatewayInstance(definition) {
-    if (!definition.instance) {
-      definition.instance = this.container.resolve(definition.gatewayClass);
-    }
-    return definition.instance;
+  createGatewayInstance(definition) {
+    return this.container.resolve(definition.gatewayClass);
   }
-  invokeHandler(ws, definition, handlerName, ...args) {
+  async invokeHandler(ws, definition, handlerName, ...args) {
     if (!handlerName) {
       return;
     }
-    const instance = this.getGatewayInstance(definition);
+    const instance = this.createGatewayInstance(definition);
     const handler = instance[handlerName];
-    if (typeof handler === "function") {
+    if (typeof handler !== "function") {
+      return;
+    }
+    const prototype = definition.gatewayClass.prototype;
+    const paramMetadata = getParamMetadata(prototype, handlerName);
+    if (paramMetadata.length > 0) {
+      let context = ws.data?.context;
+      if (!context) {
+        const url = new URL(ws.data.path || "/", "http://localhost");
+        if (ws.data.query) {
+          ws.data.query.forEach((value, key) => {
+            url.searchParams.set(key, value);
+          });
+        }
+        const request = new Request(url.toString(), {
+          method: "GET",
+          headers: new Headers
+        });
+        context = new Context(request);
+        ws.data.context = context;
+      }
+      const boundParams = await ParamBinder.bind(prototype, handlerName, context, this.container);
+      const finalArgs = [];
+      const maxParamIndex = paramMetadata.length > 0 ? Math.max(...paramMetadata.map((m) => m.index)) : -1;
+      const totalParamCount = Math.max(maxParamIndex + 1, args.length + 1);
+      for (let i = 0;i < totalParamCount; i++) {
+        const meta = paramMetadata.find((m) => m.index === i);
+        if (meta) {
+          finalArgs[i] = boundParams[i];
+        } else if (i === 0) {
+          finalArgs[i] = ws;
+        } else {
+          const argIndex = i - 1;
+          if (argIndex < args.length) {
+            finalArgs[i] = args[argIndex];
+          } else {
+            finalArgs[i] = undefined;
+          }
+        }
+      }
+      if (args.length > maxParamIndex) {
+        for (let i = maxParamIndex + 1;i < args.length; i++) {
+          finalArgs.push(args[i]);
+        }
+      }
+      handler.apply(instance, finalArgs);
+    } else {
       handler.apply(instance, [ws, ...args]);
     }
   }
-  handleOpen(ws) {
+  async handleOpen(ws) {
     const path = ws.data?.path;
     const definition = path ? this.getGateway(path) : undefined;
     if (!definition) {
       ws.close(1008, "Gateway not found");
       return;
     }
-    this.invokeHandler(ws, definition, definition.handlers.open);
+    await this.invokeHandler(ws, definition, definition.handlers.open);
   }
-  handleMessage(ws, message) {
+  async handleMessage(ws, message) {
     const path = ws.data?.path;
     const definition = path ? this.getGateway(path) : undefined;
     if (!definition) {
       ws.close(1008, "Gateway not found");
       return;
     }
-    this.invokeHandler(ws, definition, definition.handlers.message, message);
+    await this.invokeHandler(ws, definition, definition.handlers.message, message);
   }
-  handleClose(ws, code, reason) {
+  async handleClose(ws, code, reason) {
     const path = ws.data?.path;
     const definition = path ? this.getGateway(path) : undefined;
     if (!definition) {
       return;
     }
-    this.invokeHandler(ws, definition, definition.handlers.close, code, reason);
+    await this.invokeHandler(ws, definition, definition.handlers.close, code, reason);
   }
 }
 
@@ -3840,12 +3953,15 @@ ConfigModule = __legacyDecorateClassTS([
 ], ConfigModule);
 
 // src/core/application.ts
+import { LoggerManager as LoggerManager8 } from "@dangao/logsmith";
+
 class Application {
   server;
   options;
   middlewarePipeline;
   websocketRegistry;
   extensions = [];
+  signalHandlersInstalled = false;
   constructor(options = {}) {
     this.options = options;
     this.middlewarePipeline = new MiddlewarePipeline([createErrorHandlingMiddleware()]);
@@ -3874,10 +3990,14 @@ class Application {
       port: finalPort,
       hostname: finalHostname,
       fetch: this.handleRequest.bind(this),
-      websocketRegistry: this.websocketRegistry
+      websocketRegistry: this.websocketRegistry,
+      gracefulShutdownTimeout: this.options.gracefulShutdownTimeout
     };
     this.server = new BunServer(serverOptions);
     this.server.start();
+    if (this.options.enableSignalHandlers !== false) {
+      this.installSignalHandlers();
+    }
     await this.registerServices(finalPort, finalHostname);
   }
   async initializeExtensions() {
@@ -3905,10 +4025,19 @@ class Application {
     }
   }
   async stop() {
+    this.removeSignalHandlers();
     await this.deregisterServices();
     await this.closeExtensions();
     this.server?.stop();
   }
+  async gracefulShutdown(timeout) {
+    this.removeSignalHandlers();
+    await this.deregisterServices();
+    await this.closeExtensions();
+    if (this.server) {
+      await this.server.gracefulShutdown(timeout);
+    }
+  }
   async closeExtensions() {
     const container = this.getContainer();
     for (let i = this.extensions.length - 1;i >= 0; i--) {
@@ -3995,6 +4124,33 @@ class Application {
   getContainer() {
     return ControllerRegistry.getInstance().getContainer();
   }
+  installSignalHandlers() {
+    if (this.signalHandlersInstalled) {
+      return;
+    }
+    const logger = LoggerManager8.getLogger();
+    const shutdownHandler = async (signal) => {
+      logger.info(`Received ${signal}, starting graceful shutdown...`);
+      try {
+        await this.gracefulShutdown();
+        process.exit(0);
+      } catch (error) {
+        logger.error(`Error during graceful shutdown:`, error);
+        process.exit(1);
+      }
+    };
+    process.on("SIGTERM", () => shutdownHandler("SIGTERM"));
+    process.on("SIGINT", () => shutdownHandler("SIGINT"));
+    this.signalHandlersInstalled = true;
+  }
+  removeSignalHandlers() {
+    if (!this.signalHandlersInstalled) {
+      return;
+    }
+    process.removeAllListeners("SIGTERM");
+    process.removeAllListeners("SIGINT");
+    this.signalHandlersInstalled = false;
+  }
 }
 
 // src/index.ts

package/dist/websocket/registry.d.ts

@@ -1,7 +1,10 @@
 import type { ServerWebSocket } from 'bun';
+import { Context } from '../core/context';
 import type { Constructor } from '@/core/types';
 export interface WebSocketConnectionData {
     path: string;
+    query?: URLSearchParams;
+    context?: Context;
 }
 export declare class WebSocketGatewayRegistry {
     private static instance;
@@ -13,10 +16,22 @@ export declare class WebSocketGatewayRegistry {
     hasGateway(path: string): boolean;
     clear(): void;
     private getGateway;
-    private getGatewayInstance;
+    /**
+     * 动态创建网关实例（每次连接创建新实例）
+     * @param definition - 网关定义
+     * @returns 网关实例
+     */
+    private createGatewayInstance;
+    /**
+     * 调用处理器，支持参数绑定
+     * @param ws - WebSocket 连接
+     * @param definition - 网关定义
+     * @param handlerName - 处理器方法名
+     * @param args - 原始参数（message, code, reason 等，不包括 ws）
+     */
     private invokeHandler;
-    handleOpen(ws: ServerWebSocket<WebSocketConnectionData>): void;
-    handleMessage(ws: ServerWebSocket<WebSocketConnectionData>, message: string | ArrayBuffer | ArrayBufferView): void;
-    handleClose(ws: ServerWebSocket<WebSocketConnectionData>, code: number, reason: string): void;
+    handleOpen(ws: ServerWebSocket<WebSocketConnectionData>): Promise<void>;
+    handleMessage(ws: ServerWebSocket<WebSocketConnectionData>, message: string | ArrayBuffer | ArrayBufferView): Promise<void>;
+    handleClose(ws: ServerWebSocket<WebSocketConnectionData>, code: number, reason: string): Promise<void>;
 }
 //# sourceMappingURL=registry.d.ts.map

package/dist/websocket/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/websocket/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,KAAK,CAAC;AAK3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAa/C,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,wBAAwB;IACnC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA2B;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwC;IAEjE,OAAO;WAIO,WAAW,IAAI,wBAAwB;IAO9C,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI;IAsBlD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC,KAAK,IAAI,IAAI;IAIpB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,aAAa;IAgBd,UAAU,CAAC,EAAE,EAAE,eAAe,CAAC,uBAAuB,CAAC,GAAG,IAAI;IAU9D,aAAa,CAClB,EAAE,EAAE,eAAe,CAAC,uBAAuB,CAAC,EAC5C,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,eAAe,GAC9C,IAAI;IAUA,WAAW,CAChB,EAAE,EAAE,eAAe,CAAC,uBAAuB,CAAC,EAC5C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,IAAI;CAQR"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/websocket/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,KAAK,CAAC;AAO3C,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAYhD,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,wBAAwB;IACnC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA2B;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwC;IAEjE,OAAO;WAIO,WAAW,IAAI,wBAAwB;IAO9C,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI;IAsBlD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC,KAAK,IAAI,IAAI;IAIpB,OAAO,CAAC,UAAU;IAIlB;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAI7B;;;;;;OAMG;YACW,aAAa;IAiGd,UAAU,CAAC,EAAE,EAAE,eAAe,CAAC,uBAAuB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAUvE,aAAa,CACxB,EAAE,EAAE,eAAe,CAAC,uBAAuB,CAAC,EAC5C,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,eAAe,GAC9C,OAAO,CAAC,IAAI,CAAC;IAUH,WAAW,CACtB,EAAE,EAAE,eAAe,CAAC,uBAAuB,CAAC,EAC5C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC;CAQjB"}

package/docs/zh/guide.md

@@ -6,7 +6,7 @@
 
 ```ts
 import "reflect-metadata";
-import { Application } from "../src";
+import { Application } from "@dangao/bun-server";
 
 const app = new Application({ port: 3000 });
 app.listen();
@@ -26,7 +26,7 @@ import {
   Injectable,
   Param,
   POST,
-} from "../src";
+} from "@dangao/bun-server";
 
 @Injectable()
 class UserService {
@@ -64,7 +64,7 @@ app.listen();
 ## 3. 使用中间件
 
 ```ts
-import { createCorsMiddleware, createLoggerMiddleware } from "../src";
+import { createCorsMiddleware, createLoggerMiddleware } from "@dangao/bun-server";
 
 const app = new Application();
 app.use(createLoggerMiddleware({ prefix: "[Example]" }));
@@ -74,7 +74,7 @@ app.use(createCorsMiddleware({ origin: "*" }));
 `@UseMiddleware()` 可作用于单个控制器或方法：
 
 ```ts
-import { UseMiddleware } from '../src';
+import { UseMiddleware } from "@dangao/bun-server";
 
 const auth = async (ctx, next) => {
   if (ctx.getHeader('authorization') !== 'token') {
@@ -92,7 +92,7 @@ class SecureController { ... }
 ## 4. 参数验证
 
 ```ts
-import { Validate, IsEmail, MinLength } from '../src';
+import { Validate, IsEmail, MinLength } from "@dangao/bun-server";
 
 @POST('/register')
 public register(
@@ -108,32 +108,37 @@ public register(
 ## 5. WebSocket 网关
 
 ```ts
-import { OnMessage, WebSocketGateway } from "../src";
+import { OnMessage, WebSocketGateway } from "@dangao/bun-server";
+import type { ServerWebSocket } from "bun";
 
-@WebSocketGateway("/ws/chat")
+@WebSocketGateway("/ws")
 class ChatGateway {
   @OnMessage
-  public onMessage(ws, message: string) {
-    ws.send(`echo: ${message}`);
+  public handleMessage(ws: ServerWebSocket, message: string) {
+    ws.send(`Echo: ${message}`);
   }
 }
 
+const app = new Application({ port: 3000 });
 app.registerWebSocketGateway(ChatGateway);
+app.listen();
 ```
 
 ## 6. 文件上传与静态资源
 
 ```ts
-import { createFileUploadMiddleware, createStaticFileMiddleware } from "../src";
+import {
+  createFileUploadMiddleware,
+  createStaticFileMiddleware,
+} from "@dangao/bun-server";
 
+const app = new Application({ port: 3000 });
+
+// File upload
 app.use(createFileUploadMiddleware({ maxSize: 5 * 1024 * 1024 }));
-app.use(
-  createStaticFileMiddleware({
-    root: "./public",
-    prefix: "/assets",
-    enableCache: true,
-  }),
-);
+
+// Static files
+app.use(createStaticFileMiddleware({ root: "./public", prefix: "/assets" }));
 ```
 
 上传后的文件可在 `context.body.files` 中读取；静态资源请求会自动设置
@@ -142,7 +147,7 @@ Content-Type 与缓存头。
 ## 7. 错误处理与自定义过滤器
 
 ```ts
-import { ExceptionFilterRegistry, HttpException } from "../src";
+import { ExceptionFilterRegistry, HttpException } from "@dangao/bun-server";
 
 ExceptionFilterRegistry.getInstance().register({
   catch(error, context) {

package/docs/zh/migration.md

@@ -63,9 +63,15 @@
 
 - 将原本在 `Bun.serve({ websocket })` 中手写的逻辑迁移到 `@WebSocketGateway`：
   ```ts
-  @WebSocketGateway('/ws/chat')
+  import { OnMessage, WebSocketGateway } from "@dangao/bun-server";
+  import type { ServerWebSocket } from "bun";
+
+  @WebSocketGateway('/ws')
   class ChatGateway {
-    @OnMessage onMessage(ws, msg) { ws.send(msg); }
+    @OnMessage
+    public handleMessage(ws: ServerWebSocket, message: string) {
+      ws.send(`Echo: ${message}`);
+    }
   }
   app.registerWebSocketGateway(ChatGateway);
   ```

package/package.json

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