@dangao/bun-server 1.4.0 → 1.5.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;IA2FpB;;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,10 +3247,17 @@ 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);
@@ -3261,8 +3272,23 @@ class BunServer {
           }
           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) => {
@@ -3285,9 +3311,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;
   }
@@ -3840,12 +3902,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 +3939,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 +3974,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 +4073,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/package.json

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

package/src/core/application.ts

@@ -16,6 +16,7 @@ import { InterceptorRegistry, INTERCEPTOR_REGISTRY_TOKEN } from '../interceptor'
 import { CONFIG_SERVICE_TOKEN } from '../config/types';
 import { ConfigService } from '../config/service';
 import { ConfigModule } from '../config/config-module';
+import { LoggerManager } from '@dangao/logsmith';
 
 /**
  * 应用配置选项
@@ -30,6 +31,18 @@ export interface ApplicationOptions {
    * 主机名
    */
   hostname?: string;
+
+  /**
+   * 优雅停机超时时间（毫秒）
+   * 默认 30 秒
+   */
+  gracefulShutdownTimeout?: number;
+
+  /**
+   * 是否启用信号监听（SIGTERM、SIGINT）
+   * 默认 true
+   */
+  enableSignalHandlers?: boolean;
 }
 
 /**
@@ -42,6 +55,7 @@ export class Application {
   private readonly middlewarePipeline: MiddlewarePipeline;
   private readonly websocketRegistry: WebSocketGatewayRegistry;
   private readonly extensions: ApplicationExtension[] = [];
+  private signalHandlersInstalled: boolean = false;
 
   public constructor(options: ApplicationOptions = {}) {
     this.options = options;
@@ -95,11 +109,17 @@ export class Application {
       hostname: finalHostname,
       fetch: this.handleRequest.bind(this),
       websocketRegistry: this.websocketRegistry,
+      gracefulShutdownTimeout: this.options.gracefulShutdownTimeout,
     };
 
     this.server = new BunServer(serverOptions);
     this.server.start();
 
+    // 安装信号处理器（如果启用）
+    if (this.options.enableSignalHandlers !== false) {
+      this.installSignalHandlers();
+    }
+
     // 自动注册服务到注册中心（如果使用了 @ServiceRegistry 装饰器）
     await this.registerServices(finalPort, finalHostname);
   }
@@ -158,9 +178,12 @@ export class Application {
   }
 
   /**
-   * 停止应用
+   * 停止应用（立即停止，不等待请求完成）
    */
   public async stop(): Promise<void> {
+    // 移除信号处理器
+    this.removeSignalHandlers();
+
     // 自动注销服务（如果使用了 @ServiceRegistry 装饰器）
     await this.deregisterServices();
 
@@ -169,6 +192,28 @@ export class Application {
     this.server?.stop();
   }
 
+  /**
+   * 优雅停机
+   * 停止接受新请求，等待正在处理的请求完成，然后关闭应用
+   * @param timeout - 超时时间（毫秒），默认使用配置的 gracefulShutdownTimeout 或 30000
+   * @returns Promise，在停机完成时 resolve
+   */
+  public async gracefulShutdown(timeout?: number): Promise<void> {
+    // 移除信号处理器
+    this.removeSignalHandlers();
+
+    // 自动注销服务（如果使用了 @ServiceRegistry 装饰器）
+    await this.deregisterServices();
+
+    // 关闭所有扩展（包括数据库连接等）
+    await this.closeExtensions();
+
+    // 优雅关闭服务器
+    if (this.server) {
+      await this.server.gracefulShutdown(timeout);
+    }
+  }
+
   /**
    * 关闭所有扩展
    */
@@ -340,5 +385,48 @@ export class Application {
   public getContainer() {
     return ControllerRegistry.getInstance().getContainer();
   }
+
+  /**
+   * 安装信号处理器（SIGTERM、SIGINT）
+   */
+  private installSignalHandlers(): void {
+    if (this.signalHandlersInstalled) {
+      return;
+    }
+
+    const logger = LoggerManager.getLogger();
+
+    const shutdownHandler = async (signal: string) => {
+      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);
+      }
+    };
+
+    // 监听 SIGTERM（通常由进程管理器发送）
+    process.on('SIGTERM', () => shutdownHandler('SIGTERM'));
+
+    // 监听 SIGINT（通常由 Ctrl+C 触发）
+    process.on('SIGINT', () => shutdownHandler('SIGINT'));
+
+    this.signalHandlersInstalled = true;
+  }
+
+  /**
+   * 移除信号处理器
+   */
+  private removeSignalHandlers(): void {
+    if (!this.signalHandlersInstalled) {
+      return;
+    }
+
+    process.removeAllListeners('SIGTERM');
+    process.removeAllListeners('SIGINT');
+    this.signalHandlersInstalled = false;
+  }
 }
 

package/src/core/server.ts

@@ -27,6 +27,12 @@ export interface ServerOptions {
    * WebSocket 网关注册表
    */
   websocketRegistry?: WebSocketGatewayRegistry;
+
+  /**
+   * 优雅停机超时时间（毫秒）
+   * 默认 30 秒
+   */
+  gracefulShutdownTimeout?: number;
 }
 
 /**
@@ -36,6 +42,10 @@ export interface ServerOptions {
 export class BunServer {
   private server?: Server<WebSocketConnectionData>;
   private readonly options: ServerOptions;
+  private activeRequests: number = 0;
+  private isShuttingDown: boolean = false;
+  private shutdownPromise?: Promise<void>;
+  private shutdownResolve?: () => void;
 
   public constructor(options: ServerOptions) {
     this.options = options;
@@ -51,6 +61,12 @@ export class BunServer {
 
     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,
@@ -58,6 +74,11 @@ export class BunServer {
         request: Request,
         server: Server<WebSocketConnectionData>,
       ): Response | Promise<Response> | undefined => {
+        // 如果正在关闭，拒绝新请求
+        if (this.isShuttingDown) {
+          return new Response("Server is shutting down", { status: 503 });
+        }
+
         const upgradeHeader = request.headers.get("upgrade");
         if (
           this.options.websocketRegistry &&
@@ -77,8 +98,34 @@ export class BunServer {
           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) => {
@@ -99,17 +146,82 @@ export class BunServer {
   }
 
   /**
-   * 停止服务器
+   * 停止服务器（立即停止，不等待请求完成）
    */
   public stop(): void {
     if (this.server) {
       const logger = LoggerManager.getLogger();
       this.server.stop();
       this.server = undefined;
+      this.isShuttingDown = false;
+      this.activeRequests = 0;
       logger.info("Server stopped");
     }
   }
 
+  /**
+   * 优雅停机
+   * 停止接受新请求，等待正在处理的请求完成
+   * @param timeout - 超时时间（毫秒），默认使用配置的 gracefulShutdownTimeout 或 30000
+   * @returns Promise，在停机完成时 resolve
+   */
+  public async gracefulShutdown(timeout?: number): Promise<void> {
+    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;
+    }
+
+    // 创建关闭 Promise
+    if (!this.shutdownPromise) {
+      this.shutdownPromise = new Promise<void>((resolve) => {
+        this.shutdownResolve = resolve;
+      });
+    }
+
+    // 设置超时
+    const timeoutPromise = new Promise<void>((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})`);
+  }
+
+  /**
+   * 获取当前活跃请求数
+   */
+  public getActiveRequests(): number {
+    return this.activeRequests;
+  }
+
+  /**
+   * 检查是否正在关闭
+   */
+  public isShuttingDownState(): boolean {
+    return this.isShuttingDown;
+  }
+
   /**
    * 获取服务器实例
    * @returns Bun Server 实例

package/tests/core/graceful-shutdown.test.ts

@@ -0,0 +1,321 @@
+import { describe, expect, test, afterEach, beforeEach } from 'bun:test';
+import { Application } from '../../src/core/application';
+import { Controller, ControllerRegistry } from '../../src/controller/controller';
+import { GET } from '../../src/router/decorators';
+import { Param } from '../../src/controller/decorators';
+import { getTestPort } from '../utils/test-port';
+import { RouteRegistry } from '../../src/router/registry';
+
+describe('Graceful Shutdown', () => {
+  let app: Application;
+  let port: number;
+
+  beforeEach((done) => {
+    port = getTestPort();
+    done();
+  });
+
+  afterEach(async (done) => {
+    if (app) {
+      // 确保清理，使用 stop 而不是 gracefulShutdown 以避免测试间干扰
+      try {
+        const server = app.getServer();
+        if (server?.isRunning()) {
+          await app.stop();
+          // 等待一小段时间确保端口释放
+          await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+      } catch (error) {
+        // 忽略错误，确保清理完成
+      }
+      app = undefined as any;
+    }
+    RouteRegistry.getInstance().clear();
+    ControllerRegistry.getInstance().clear();
+    done();
+  });
+
+  test('should reject new requests during shutdown', async () => {
+    @Controller('/api')
+    class TestController {
+      @GET('/test')
+      public test() {
+        return { message: 'ok' };
+      }
+
+      @GET('/slow')
+      public async slow() {
+        // 模拟慢请求，确保在停机过程中有活跃请求
+        await new Promise((resolve) => setTimeout(resolve, 200));
+        return { message: 'completed' };
+      }
+    }
+
+    app = new Application({ port, enableSignalHandlers: false });
+    app.registerController(TestController);
+    await app.listen();
+
+    const server = app.getServer();
+    expect(server).toBeDefined();
+
+    // 先发送一个慢请求，确保在停机过程中有活跃请求
+    const slowRequestPromise = fetch(`http://localhost:${port}/api/slow`);
+
+    // 等待请求开始处理
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // 开始优雅停机（此时有活跃请求，服务器不会立即关闭）
+    const shutdownPromise = app.gracefulShutdown(5000);
+
+    // 等待一小段时间确保 shutdown 状态已设置
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // 尝试发送新请求，应该被拒绝
+    const response = await fetch(`http://localhost:${port}/api/test`);
+    expect(response.status).toBe(503);
+    expect(await response.text()).toBe('Server is shutting down');
+
+    // 等待慢请求完成
+    await slowRequestPromise;
+
+    // 等待停机完成
+    await shutdownPromise;
+  });
+
+  test('should wait for active requests to complete', async () => {
+    let requestCompleted = false;
+
+    @Controller('/api')
+    class TestController {
+      @GET('/slow')
+      public async slow() {
+        // 模拟慢请求
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        requestCompleted = true;
+        return { message: 'completed' };
+      }
+    }
+
+    app = new Application({ port, enableSignalHandlers: false });
+    app.registerController(TestController);
+    await app.listen();
+
+    // 发送一个慢请求
+    const requestPromise = fetch(`http://localhost:${port}/api/slow`);
+
+    // 等待请求开始处理
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // 开始优雅停机
+    const shutdownPromise = app.gracefulShutdown(5000);
+
+    // 等待请求完成
+    const response = await requestPromise;
+    expect(response.status).toBe(200);
+    const data = (await response.json()) as { message: string };
+    expect(data.message).toBe('completed');
+    expect(requestCompleted).toBe(true);
+
+    // 等待停机完成
+    await shutdownPromise;
+
+    const server = app.getServer();
+    expect(server?.isRunning()).toBe(false);
+  });
+
+  test('should force shutdown after timeout', async () => {
+    @Controller('/api')
+    class TestController {
+      @GET('/very-slow')
+      public async verySlow() {
+        // 模拟非常慢的请求（超过超时时间）
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        return { message: 'completed' };
+      }
+    }
+
+    app = new Application({ port, enableSignalHandlers: false });
+    app.registerController(TestController);
+    await app.listen();
+
+    // 发送一个非常慢的请求
+    const requestPromise = fetch(`http://localhost:${port}/api/very-slow`);
+
+    // 等待请求开始处理
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // 开始优雅停机，设置较短的超时时间
+    const startTime = Date.now();
+    await app.gracefulShutdown(500);
+    const shutdownDuration = Date.now() - startTime;
+
+    // 应该在大约 500ms 后强制关闭（允许一些误差）
+    expect(shutdownDuration).toBeGreaterThanOrEqual(450);
+    expect(shutdownDuration).toBeLessThan(1000);
+
+    const server = app.getServer();
+    expect(server?.isRunning()).toBe(false);
+
+    // 请求可能仍在进行，但不应该影响服务器状态
+    try {
+      await requestPromise;
+    } catch (error) {
+      // 请求可能失败，这是预期的
+    }
+  });
+
+  test('should handle multiple concurrent requests during shutdown', async () => {
+    const completedRequests: number[] = [];
+
+    @Controller('/api')
+    class TestController {
+      @GET('/concurrent/:id')
+      public async concurrent(@Param('id') id: string) {
+        // 模拟异步处理
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        completedRequests.push(Number.parseInt(id));
+        return { id, message: 'completed' };
+      }
+    }
+
+    app = new Application({ port, enableSignalHandlers: false });
+    app.registerController(TestController);
+    await app.listen();
+
+    // 发送多个并发请求
+    const requests = Promise.all([
+      fetch(`http://localhost:${port}/api/concurrent/1`),
+      fetch(`http://localhost:${port}/api/concurrent/2`),
+      fetch(`http://localhost:${port}/api/concurrent/3`),
+    ]);
+
+    // 等待请求开始处理
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // 开始优雅停机
+    const shutdownPromise = app.gracefulShutdown(5000);
+
+    // 等待所有请求完成
+    const responses = await requests;
+    expect(responses.length).toBe(3);
+
+    for (const response of responses) {
+      expect(response.status).toBe(200);
+      const data = (await response.json()) as { message: string };
+      expect(data.message).toBe('completed');
+    }
+
+    // 所有请求应该都完成了
+    expect(completedRequests.sort()).toEqual([1, 2, 3]);
+
+    // 等待停机完成
+    await shutdownPromise;
+  });
+
+  test('should handle graceful shutdown with no active requests', async () => {
+    @Controller('/api')
+    class TestController {
+      @GET('/test')
+      public test() {
+        return { message: 'ok' };
+      }
+    }
+
+    app = new Application({ port, enableSignalHandlers: false });
+    app.registerController(TestController);
+    await app.listen();
+
+    const server = app.getServer();
+    expect(server?.isRunning()).toBe(true);
+
+    // 没有活跃请求时，应该立即关闭
+    const startTime = Date.now();
+    await app.gracefulShutdown(5000);
+    const shutdownDuration = Date.now() - startTime;
+
+    // 应该几乎立即关闭（允许一些处理时间）
+    expect(shutdownDuration).toBeLessThan(100);
+
+    expect(server?.isRunning()).toBe(false);
+  });
+
+  test('should track active requests correctly', async () => {
+    @Controller('/api')
+    class TestController {
+      @GET('/slow')
+      public async slow() {
+        // 使用慢请求确保在检查时请求仍在处理中
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        return { message: 'ok' };
+      }
+    }
+
+    app = new Application({ port, enableSignalHandlers: false });
+    app.registerController(TestController);
+    await app.listen();
+
+    const server = app.getServer();
+    expect(server).toBeDefined();
+
+    // 发送慢请求
+    const requestPromise = fetch(`http://localhost:${port}/api/slow`);
+
+    // 等待请求开始处理（但不要等到完成）
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    // 检查活跃请求数（应该大于 0，因为请求还在处理中）
+    const activeRequests = server?.getActiveRequests() ?? 0;
+    expect(activeRequests).toBeGreaterThan(0);
+
+    // 等待请求完成
+    await requestPromise;
+
+    // 等待一小段时间确保计数更新
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    // 活跃请求数应该回到 0
+    const finalActiveRequests = server?.getActiveRequests() ?? 0;
+    expect(finalActiveRequests).toBe(0);
+  });
+
+  test('should use custom graceful shutdown timeout', async () => {
+    @Controller('/api')
+    class TestController {
+      @GET('/slow')
+      public async slow() {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        return { message: 'completed' };
+      }
+    }
+
+    app = new Application({
+      port,
+      enableSignalHandlers: false,
+      gracefulShutdownTimeout: 2000,
+    });
+    app.registerController(TestController);
+    await app.listen();
+
+    // 发送请求
+    const requestPromise = fetch(`http://localhost:${port}/api/slow`);
+
+    // 等待请求开始处理
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // 使用自定义超时时间（比配置的短）
+    const startTime = Date.now();
+    await app.gracefulShutdown(100);
+    const shutdownDuration = Date.now() - startTime;
+
+    // 应该在大约 100ms 后强制关闭
+    expect(shutdownDuration).toBeGreaterThanOrEqual(80);
+    expect(shutdownDuration).toBeLessThan(200);
+
+    // 等待请求完成（可能失败）
+    try {
+      await requestPromise;
+    } catch (error) {
+      // 请求可能失败，这是预期的
+    }
+  });
+});