@dangao/bun-server 1.3.0 → 1.5.0

package/docs/zh/troubleshooting.md

@@ -93,6 +93,47 @@ const { SomeService } = await import("./some-service");
 
 ## 依赖注入
 
+### ⚠️ 重要：注入的依赖为 undefined
+
+**错误**：注入的服务在运行时为 `undefined`，或通过 `bun app.ts` 运行正常，但在 VSCode 调试器中失败。
+
+**原因**：`tsconfig.json` 中缺少 TypeScript 装饰器元数据配置。
+
+**解决方案**：**这非常重要！** 确保你的 `tsconfig.json` 包含以下两个选项：
+
+```json
+{
+  "compilerOptions": {
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true
+  }
+}
+```
+
+**为什么重要**：
+- `emitDecoratorMetadata`：使 TypeScript 能够为装饰器发出元数据，这是依赖注入正常工作所必需的
+- `experimentalDecorators`：启用装饰器语法支持
+- 没有这些配置，DI 容器无法确定参数类型，将注入 `undefined`
+
+**检查所有 tsconfig.json 文件**：
+- 根目录的 `tsconfig.json`
+- `examples/tsconfig.json`
+- 任何项目特定的 `tsconfig.json` 文件
+
+**示例**：
+```json
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "./",
+    "emitDecoratorMetadata": true,  // ⚠️ 必需
+    "experimentalDecorators": true   // ⚠️ 必需
+  },
+  "include": ["**/*.ts"]
+}
+```
+
 ### 服务不可注入
 
 **错误**：`Cannot resolve dependency` 或找不到服务。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dangao/bun-server",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -45,10 +45,10 @@
     "test": "bun test",
     "type-check": "tsc --noEmit",
     "clean": "rm -rf dist",
-    "bundle": "bun build src/index.ts --target=bun --format=esm --outfile=dist/index.js --external reflect-metadata --external @dangao/logsmith",
+    "bundle": "bun build src/index.ts --target=bun --format=esm --outfile=dist/index.js --external reflect-metadata --external @dangao/logsmith --external @dangao/nacos-client",
     "dts": "tsc -p tsconfig.build.json",
     "build": "bun run clean && bun run bundle && bun run dts",
-    "prepare": "bun run build",
+    "prepublishOnly": "bun run build",
     "publish:package": "cp -r ../../README.md ../../LICENSE ../../docs . && bun publish --access public && rm -rf ./README.md ./LICENSE ./docs"
   },
   "devDependencies": {
@@ -57,6 +57,7 @@
   },
   "dependencies": {
     "reflect-metadata": "^0.2.2",
-    "@dangao/logsmith": "0.1.1"
+    "@dangao/logsmith": "0.1.1",
+    "@dangao/nacos-client": "0.1.0"
   }
 }

package/src/config/config-module.ts

@@ -1,4 +1,7 @@
 import { Module, MODULE_METADATA_KEY, type ModuleProvider } from '../di/module';
+import { CONFIG_CENTER_TOKEN } from '../microservice/config-center/types';
+import type { ConfigCenter } from '../microservice/config-center/types';
+import { ControllerRegistry } from '../controller/controller';
 
 import { ConfigService } from './service';
 import { CONFIG_SERVICE_TOKEN, type ConfigModuleOptions } from './types';
@@ -32,6 +35,13 @@ export class ConfigModule {
 
     const service = new ConfigService(mergedConfig, options.namespace);
 
+    // 如果启用配置中心集成，延迟初始化（等待 ConfigCenterModule 注册）
+    // 初始化将在 Application.listen() 时执行，确保所有模块都已注册
+    if (options.configCenter?.enabled) {
+      // 保存配置中心选项，稍后在应用启动时初始化
+      (service as any)._configCenterOptions = options.configCenter;
+    }
+
     if (options.validate) {
       options.validate(mergedConfig);
     }
@@ -71,6 +81,206 @@ export class ConfigModule {
     }
     return env;
   }
+
+  /**
+   * 初始化配置中心集成（延迟初始化，在应用启动时调用）
+   */
+  public static async initializeConfigCenter(
+    service: ConfigService,
+    configCenterOptions: NonNullable<ConfigModuleOptions['configCenter']>,
+  ): Promise<void> {
+    // 加载配置中心配置
+    const configCenterConfig = await ConfigModule.loadConfigCenterConfig(
+      configCenterOptions,
+    );
+    if (configCenterConfig) {
+      // 根据优先级合并配置
+      const currentConfig = service.getAll();
+      let updatedConfig: Record<string, unknown>;
+      if (configCenterOptions.configCenterPriority !== false) {
+        // 配置中心配置 > 环境变量 > 默认配置
+        updatedConfig = {
+          ...currentConfig,
+          ...configCenterConfig,
+        };
+      } else {
+        // 默认配置 > 环境变量 > 配置中心配置（配置中心配置不覆盖现有配置）
+        updatedConfig = {
+          ...configCenterConfig,
+          ...currentConfig,
+        };
+      }
+      service.updateConfig(updatedConfig as any);
+    }
+
+    // 设置配置变更监听
+    if (configCenterOptions.configs) {
+      ConfigModule.setupConfigCenterWatcher(service, configCenterOptions);
+    }
+  }
+
+  /**
+   * 从配置中心加载配置
+   */
+  private static async loadConfigCenterConfig(
+    configCenterOptions: NonNullable<ConfigModuleOptions['configCenter']>,
+    retries: number = 5,
+    delay: number = 200,
+  ): Promise<Record<string, unknown> | null> {
+    const container = ControllerRegistry.getInstance().getContainer();
+    
+    // 重试机制：等待 ConfigCenterModule 注册完成
+    let configCenter: ConfigCenter | undefined;
+    for (let i = 0; i < retries; i++) {
+      configCenter = container.resolve<ConfigCenter>(CONFIG_CENTER_TOKEN);
+      if (configCenter) {
+        break;
+      }
+      if (i < retries - 1) {
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+
+    if (!configCenter) {
+      console.warn(
+        '[ConfigModule] ConfigCenter not found after retries, skipping config center integration. ' +
+        'Make sure ConfigCenterModule is registered before ConfigModule.',
+      );
+      return null;
+    }
+
+    try {
+
+      if (!configCenterOptions.configs || configCenterOptions.configs.size === 0) {
+        return null;
+      }
+
+      const configMap: Record<string, unknown> = {};
+
+      // 并行加载所有配置
+      const loadPromises: Promise<void>[] = [];
+      for (const [configPath, configInfo] of configCenterOptions.configs.entries()) {
+        loadPromises.push(
+          configCenter
+            .getConfig(
+              configInfo.dataId,
+              configInfo.groupName,
+              configInfo.namespaceId,
+            )
+            .then((result) => {
+              // 解析配置内容（支持 JSON）
+              try {
+                const parsed = JSON.parse(result.content);
+                ConfigModule.setValueByPath(configMap, configPath, parsed);
+              } catch {
+                // 如果不是 JSON，直接使用字符串值
+                ConfigModule.setValueByPath(configMap, configPath, result.content);
+              }
+            })
+            .catch((error) => {
+              console.error(
+                `[ConfigModule] Failed to load config ${configInfo.dataId}:`,
+                error,
+              );
+            }),
+        );
+      }
+
+      await Promise.all(loadPromises);
+
+      return configMap;
+    } catch (error) {
+      console.error('[ConfigModule] Failed to load config center config:', error);
+      return null;
+    }
+  }
+
+  /**
+   * 设置配置中心监听器
+   */
+  private static setupConfigCenterWatcher(
+    service: ConfigService,
+    configCenterOptions: NonNullable<ConfigModuleOptions['configCenter']>,
+  ): void {
+    try {
+      const container = ControllerRegistry.getInstance().getContainer();
+      const configCenter = container.resolve<ConfigCenter>(CONFIG_CENTER_TOKEN);
+
+      if (!configCenter || !configCenterOptions.configs) {
+        return;
+      }
+
+      // 为每个配置设置监听器
+      for (const [configPath, configInfo] of configCenterOptions.configs.entries()) {
+        configCenter.watchConfig(
+          configInfo.dataId,
+          configInfo.groupName,
+          (result) => {
+            try {
+              // 解析配置内容
+              let parsedValue: unknown;
+              try {
+                parsedValue = JSON.parse(result.content);
+              } catch {
+                parsedValue = result.content;
+              }
+
+              // 更新配置服务
+              const currentConfig = service.getAll();
+              const updatedConfig = {
+                ...currentConfig,
+              };
+              ConfigModule.setValueByPath(updatedConfig, configPath, parsedValue);
+              service.updateConfig(updatedConfig as any);
+
+              console.log(
+                `[ConfigModule] Config updated: ${configPath} from ${configInfo.dataId}`,
+              );
+            } catch (error) {
+              console.error(
+                `[ConfigModule] Failed to update config ${configPath}:`,
+                error,
+              );
+            }
+          },
+          configInfo.namespaceId,
+        );
+      }
+    } catch (error) {
+      console.error(
+        '[ConfigModule] Failed to setup config center watcher:',
+        error,
+      );
+    }
+  }
+
+  /**
+   * 根据路径设置对象值（支持点号路径）
+   */
+  private static setValueByPath(
+    obj: Record<string, unknown>,
+    path: string,
+    value: unknown,
+  ): void {
+    const segments = path.split('.');
+    let current: Record<string, unknown> = obj;
+
+    for (let i = 0; i < segments.length - 1; i++) {
+      const segment = segments[i]!;
+      // 检查是否需要创建嵌套对象
+      // 注意：typeof null === 'object'，所以需要明确排除 null
+      if (
+        !(segment in current) ||
+        current[segment] == null ||
+        typeof current[segment] !== 'object'
+      ) {
+        current[segment] = {};
+      }
+      current = current[segment] as Record<string, unknown>;
+    }
+
+    current[segments[segments.length - 1]!] = value;
+  }
 }
 
 

package/src/config/service.ts

@@ -3,14 +3,65 @@
  * 提供类型安全的配置访问能力
  */
 export class ConfigService<TConfig extends Record<string, unknown> = Record<string, unknown>> {
-  private readonly config: TConfig;
+  private config: TConfig;
   private readonly namespace?: string;
+  private configUpdateListeners: Array<(config: TConfig) => void> = [];
 
   public constructor(config: TConfig, namespace?: string) {
     this.config = config;
     this.namespace = namespace;
   }
 
+  /**
+   * 更新配置（用于配置中心动态刷新）
+   * @param newConfig - 新配置对象
+   */
+  public updateConfig(newConfig: TConfig): void {
+    this.config = newConfig;
+    // 通知所有监听器
+    for (const listener of this.configUpdateListeners) {
+      try {
+        listener(newConfig);
+      } catch (error) {
+        console.error('[ConfigService] Error in config update listener:', error);
+      }
+    }
+  }
+
+  /**
+   * 合并配置（用于配置中心增量更新）
+   * @param partialConfig - 部分配置对象
+   */
+  public mergeConfig(partialConfig: Partial<TConfig>): void {
+    this.config = {
+      ...this.config,
+      ...partialConfig,
+    } as TConfig;
+    // 通知所有监听器
+    for (const listener of this.configUpdateListeners) {
+      try {
+        listener(this.config);
+      } catch (error) {
+        console.error('[ConfigService] Error in config update listener:', error);
+      }
+    }
+  }
+
+  /**
+   * 添加配置更新监听器
+   * @param listener - 监听器函数
+   * @returns 取消监听的函数
+   */
+  public onConfigUpdate(listener: (config: TConfig) => void): () => void {
+    this.configUpdateListeners.push(listener);
+    return () => {
+      const index = this.configUpdateListeners.indexOf(listener);
+      if (index > -1) {
+        this.configUpdateListeners.splice(index, 1);
+      }
+    };
+  }
+
   /**
    * 获取完整配置对象
    */

package/src/config/types.ts

@@ -20,6 +20,37 @@ export interface ConfigModuleOptions<TConfig extends Record<string, unknown> = R
    * 命名空间前缀，用于逻辑分组（可选）
    */
   namespace?: string;
+
+  /**
+   * 配置中心集成选项（可选）
+   */
+  configCenter?: {
+    /**
+     * 是否启用配置中心集成
+     */
+    enabled?: boolean;
+
+    /**
+     * 配置中心配置映射
+     * key: 配置路径（如 "app.name"）
+     * value: { dataId: string, groupName: string, namespaceId?: string }
+     */
+    configs?: Map<
+      string,
+      {
+        dataId: string;
+        groupName: string;
+        namespaceId?: string;
+      }
+    >;
+
+    /**
+     * 配置优先级
+     * 配置中心配置 > 环境变量 > 默认配置
+     * @default true
+     */
+    configCenterPriority?: boolean;
+  };
 }
 
 export const CONFIG_SERVICE_TOKEN = Symbol('@dangao/bun-server:config:service');

package/src/controller/controller.ts

@@ -258,6 +258,14 @@ export class ControllerRegistry {
     return this.container;
   }
 
+  /**
+   * 获取所有已注册的控制器类
+   * @returns 控制器类数组
+   */
+  public getAllControllers(): Constructor<unknown>[] {
+    return Array.from(this.controllerContainers.keys());
+  }
+
   /**
    * 获取所有已注册的控制器类
    * @returns 控制器类数组

package/src/core/application.ts

@@ -13,6 +13,10 @@ import { ModuleRegistry } from '../di/module-registry';
 import type { ModuleClass } from '../di/module';
 import type { Constructor } from './types';
 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';
 
 /**
  * 应用配置选项
@@ -27,6 +31,18 @@ export interface ApplicationOptions {
    * 主机名
    */
   hostname?: string;
+
+  /**
+   * 优雅停机超时时间（毫秒）
+   * 默认 30 秒
+   */
+  gracefulShutdownTimeout?: number;
+
+  /**
+   * 是否启用信号监听（SIGTERM、SIGINT）
+   * 默认 true
+   */
+  enableSignalHandlers?: boolean;
 }
 
 /**
@@ -39,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;
@@ -81,15 +98,30 @@ export class Application {
     // 初始化所有扩展（包括数据库连接等）
     await this.initializeExtensions();
 
+    // 初始化配置中心集成（在所有模块注册完成后）
+    await this.initializeConfigCenter();
+
+    const finalPort = port ?? this.options.port ?? 3000;
+    const finalHostname = hostname ?? this.options.hostname;
+
     const serverOptions: ServerOptions = {
-      port: port ?? this.options.port ?? 3000,
-      hostname: hostname ?? this.options.hostname,
+      port: finalPort,
+      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);
   }
 
   /**
@@ -117,14 +149,71 @@ export class Application {
   }
 
   /**
-   * 停止应用
+   * 初始化配置中心集成
+   * 在所有模块注册完成后调用，确保 ConfigCenterModule 已注册
+   */
+  private async initializeConfigCenter(): Promise<void> {
+    const container = this.getContainer();
+    // ConfigModule 可能未注册（很多测试/应用不使用配置模块），此时不要抛错
+    if (!container.isRegistered(CONFIG_SERVICE_TOKEN)) {
+      return;
+    }
+
+    const configService = container.resolve<ConfigService>(CONFIG_SERVICE_TOKEN);
+
+    // 检查是否有待初始化的配置中心选项
+    const configCenterOptions = (configService as any)._configCenterOptions;
+    if (configCenterOptions) {
+      try {
+        await ConfigModule.initializeConfigCenter(configService, configCenterOptions);
+        // 清除临时选项
+        delete (configService as any)._configCenterOptions;
+      } catch (error) {
+        console.error(
+          '[Application] Failed to initialize config center:',
+          error,
+        );
+      }
+    }
+  }
+
+  /**
+   * 停止应用（立即停止，不等待请求完成）
    */
   public async stop(): Promise<void> {
+    // 移除信号处理器
+    this.removeSignalHandlers();
+
+    // 自动注销服务（如果使用了 @ServiceRegistry 装饰器）
+    await this.deregisterServices();
+
     // 关闭所有扩展（包括数据库连接等）
     await this.closeExtensions();
     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);
+    }
+  }
+
   /**
    * 关闭所有扩展
    */
@@ -235,6 +324,60 @@ export class Application {
     return this.server;
   }
 
+  /**
+   * 自动注册服务到注册中心
+   * 扫描所有使用 @ServiceRegistry 装饰器的控制器，自动注册服务
+   */
+  private async registerServices(port: number, hostname?: string): Promise<void> {
+    try {
+      // 动态导入服务注册装饰器（避免循环依赖）
+      const { registerServiceInstance } = await import(
+        '../microservice/service-registry/decorators'
+      );
+
+      const registry = ControllerRegistry.getInstance();
+      const controllers = registry.getRegisteredControllers();
+
+      for (const controllerClass of controllers) {
+        await registerServiceInstance(controllerClass, port, hostname);
+      }
+    } catch (error) {
+      // 如果服务注册失败，不影响应用启动（可能是没有配置 ServiceRegistryModule）
+      // 只在调试模式下输出警告
+      if (process.env.NODE_ENV === 'development') {
+        console.warn('[Application] Failed to register services:', error);
+      }
+    }
+  }
+
+  /**
+   * 自动注销服务
+   * 注销所有使用 @ServiceRegistry 装饰器的服务
+   */
+  private async deregisterServices(): Promise<void> {
+    try {
+      // 动态导入服务注册装饰器（避免循环依赖）
+      const { deregisterServiceInstance } = await import(
+        '../microservice/service-registry/decorators'
+      );
+
+      const registry = ControllerRegistry.getInstance();
+      const controllers = registry.getRegisteredControllers();
+
+      const port = this.server?.getPort() ?? this.options.port ?? 3000;
+      const hostname = this.server?.getHostname() ?? this.options.hostname;
+
+      for (const controllerClass of controllers) {
+        await deregisterServiceInstance(controllerClass, port, hostname);
+      }
+    } catch (error) {
+      // 如果服务注销失败，不影响应用关闭
+      if (process.env.NODE_ENV === 'development') {
+        console.warn('[Application] Failed to deregister services:', error);
+      }
+    }
+  }
+
   /**
    * 获取 DI 容器（用于注册服务）
    * @returns DI 容器
@@ -242,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/context.ts

@@ -1,6 +1,7 @@
 import { BodyParser } from '../request/body-parser';
 import type { UploadedFileInfo } from '../files';
 import type { BodyInit } from 'bun'
+import { type URLSearchParams, URL } from 'url';
 
 /**
  * 请求上下文