@dangao/bun-server 1.8.3 → 1.10.0

package/docs/custom-decorators.md

@@ -27,11 +27,9 @@ Bun Server Framework provides a powerful interceptor mechanism that allows you t
 
 ### Basic Decorator Pattern
 
-A custom decorator is a function that returns a `MethodDecorator`. It uses `reflect-metadata` to store metadata on the method.
+A custom decorator is a function that returns a `MethodDecorator`. It uses the Reflect metadata API to store metadata on the method.
 
 ```typescript
-import 'reflect-metadata';
-
 // 1. Define a metadata key (use Symbol for uniqueness)
 export const MY_METADATA_KEY = Symbol('@my-app:my-decorator');
 
@@ -260,8 +258,6 @@ class MyInterceptor extends BaseInterceptor {
 ### Storing Metadata
 
 ```typescript
-import 'reflect-metadata';
-
 const METADATA_KEY = Symbol('my-metadata');
 
 // Store metadata
@@ -337,7 +333,6 @@ class MyInterceptor extends BaseInterceptor {
 ### Example 1: Simple Logging Interceptor
 
 ```typescript
-import 'reflect-metadata';
 import { BaseInterceptor } from '@dangao/bun-server';
 import type { Container } from '@dangao/bun-server';
 import type { Context } from '@dangao/bun-server';
@@ -375,7 +370,6 @@ export class LogInterceptor extends BaseInterceptor {
 ### Example 2: Rate Limiting Interceptor
 
 ```typescript
-import 'reflect-metadata';
 import { BaseInterceptor, HttpException } from '@dangao/bun-server';
 import type { Container } from '@dangao/bun-server';
 import type { Context } from '@dangao/bun-server';

package/docs/extensions.md

@@ -499,8 +499,6 @@ You can create custom decorators to extend controller and route functionality.
 ### Creating Decorators
 
 ```typescript
-import 'reflect-metadata';
-
 // Cache decorator
 export function Cache(ttl: number) {
   return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {

package/docs/guide.md

@@ -15,7 +15,6 @@ For detailed lifecycle documentation, see [Request Lifecycle](./request-lifecycl
 ## 1. Initialize Application
 
 ```ts
-import "reflect-metadata";
 import { Application } from "@dangao/bun-server";
 
 const app = new Application({ port: 3000 });

package/docs/zh/custom-decorators.md

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

package/docs/zh/extensions.md

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

package/docs/zh/guide.md

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

package/docs/zh/migration.md

@@ -12,11 +12,6 @@
     "emitDecoratorMetadata": true
   }
   ```
-- 在应用入口（如 `main.ts`）导入一次 `reflect-metadata`：
-  ```ts
-  import 'reflect-metadata';
-  ```
-
 ## 2. 路由与控制器
 
 - 将旧的函数式注册迁移到装饰器：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dangao/bun-server",
-  "version": "1.8.3",
+  "version": "1.10.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -25,7 +25,7 @@
   ],
   "files": [
     "dist",
-    "readme.md",
+    "README.md",
     "LICENSE",
     "src",
     "tests",
@@ -38,7 +38,7 @@
     "url": "https://github.com/dangaogit/bun-server/issues"
   },
   "engines": {
-    "bun": ">=1.3.3"
+    "bun": ">=1.3.10"
   },
   "scripts": {
     "dev": "bun --watch src/index.ts",
@@ -58,6 +58,6 @@
   "dependencies": {
     "reflect-metadata": "^0.2.2",
     "@dangao/logsmith": "0.1.1",
-    "@dangao/nacos-client": "0.1.0"
+    "@dangao/nacos-client": "0.1.1"
   }
 }

package/src/core/application.ts

@@ -18,6 +18,7 @@ import { ConfigService } from '../config/service';
 import { ConfigModule } from '../config/config-module';
 import { CacheModule, CACHE_POST_PROCESSOR_TOKEN } from '../cache';
 import { LoggerManager } from '@dangao/logsmith';
+import { EventModule } from '../events/event-module';
 
 /**
  * 应用配置选项
@@ -44,6 +45,14 @@ export interface ApplicationOptions {
    * 默认 true
    */
   enableSignalHandlers?: boolean;
+
+  /**
+   * 是否启用 SO_REUSEPORT
+   * 允许多进程绑定同一端口，用于多进程负载均衡
+   * 仅 Linux 有效，macOS/Windows 会忽略
+   * @default false
+   */
+  reusePort?: boolean;
 }
 
 /**
@@ -102,12 +111,16 @@ export class Application {
     // 初始化配置中心集成（在所有模块注册完成后）
     await this.initializeConfigCenter();
 
+    // 自动初始化事件监听器（如果 EventModule 已注册且启用了 autoScan）
+    this.initializeEventListeners();
+
     const finalPort = port ?? this.options.port ?? 3000;
     const finalHostname = hostname ?? this.options.hostname;
 
     const serverOptions: ServerOptions = {
       port: finalPort,
       hostname: finalHostname,
+      reusePort: this.options.reusePort,
       fetch: this.handleRequest.bind(this),
       websocketRegistry: this.websocketRegistry,
       gracefulShutdownTimeout: this.options.gracefulShutdownTimeout,
@@ -178,6 +191,31 @@ export class Application {
     }
   }
 
+  /**
+   * 初始化事件监听器
+   * 在所有模块注册完成后调用，自动扫描并注册使用 @OnEvent 装饰器的类
+   */
+  private initializeEventListeners(): void {
+    const container = this.getContainer();
+    
+    // 检查 EventModule 是否已注册
+    const registry = ModuleRegistry.getInstance();
+    const eventModuleRef = registry.getModuleRef(EventModule);
+    
+    if (!eventModuleRef) {
+      // EventModule 未注册，跳过
+      return;
+    }
+
+    // 调用自动初始化
+    const initialized = EventModule.autoInitialize(container);
+    
+    if (initialized) {
+      const logger = LoggerManager.getLogger();
+      logger.debug('[Application] Event listeners initialized automatically');
+    }
+  }
+
   /**
    * 停止应用（立即停止，不等待请求完成）
    */

package/src/core/server.ts

@@ -33,6 +33,14 @@ export interface ServerOptions {
    * 默认 30 秒
    */
   gracefulShutdownTimeout?: number;
+
+  /**
+   * 是否启用 SO_REUSEPORT
+   * 允许多进程绑定同一端口，用于多进程负载均衡
+   * 仅 Linux 有效，macOS/Windows 会忽略
+   * @default false
+   */
+  reusePort?: boolean;
 }
 
 /**
@@ -70,6 +78,7 @@ export class BunServer {
     this.server = Bun.serve({
       port: this.options.port ?? 3000,
       hostname: this.options.hostname,
+      reusePort: this.options.reusePort,
       fetch: (
         request: Request,
         server: Server<WebSocketConnectionData>,

package/src/events/event-module.ts

@@ -102,6 +102,11 @@ export class EventModule {
    */
   private static listenerClasses: Function[] = [];
 
+  /**
+   * 模块选项
+   */
+  private static options: EventModuleOptions & { autoScan?: boolean } = {};
+
   /**
    * 创建事件模块
    * @param options - 模块配置
@@ -121,6 +126,12 @@ export class EventModule {
    * ```
    */
   public static forRoot(options: EventModuleOptions = {}): typeof EventModule {
+    // 保存选项（默认启用自动扫描）
+    EventModule.options = {
+      ...options,
+      autoScan: options.autoScan ?? true,
+    };
+
     const providers: ModuleProvider[] = [];
 
     // 创建事件发射器服务
@@ -269,4 +280,101 @@ export class EventModule {
 
     return undefined;
   }
+
+  /**
+   * 自动初始化事件监听器
+   * 由框架在应用启动时自动调用，扫描所有模块中使用 @OnEvent 装饰器的类并注册
+   * 
+   * @param rootContainer - 根容器
+   * @returns 是否成功初始化
+   * 
+   * @internal 此方法由框架内部调用，用户通常不需要手动调用
+   */
+  public static autoInitialize(rootContainer: Container): boolean {
+    // 检查是否启用自动扫描
+    if (EventModule.options.autoScan === false) {
+      return false;
+    }
+
+    // 获取 EventEmitter
+    const registry = ModuleRegistry.getInstance();
+    const eventModuleRef = registry.getModuleRef(EventModule);
+
+    if (!eventModuleRef) {
+      return false;
+    }
+
+    let eventEmitter: EventEmitter | undefined;
+    try {
+      eventEmitter = eventModuleRef.container.resolve<EventEmitter>(EVENT_EMITTER_TOKEN);
+    } catch {
+      return false;
+    }
+
+    if (!eventEmitter) {
+      return false;
+    }
+
+    // 收集所有监听器类
+    const listenerClasses = new Set<Function>();
+
+    // 1. 添加通过 registerListeners 注册的类
+    for (const listenerClass of EventModule.listenerClasses) {
+      listenerClasses.add(listenerClass);
+    }
+
+    // 2. 添加通过选项配置的强制包含类
+    if (EventModule.options.includeListeners) {
+      for (const listenerClass of EventModule.options.includeListeners) {
+        listenerClasses.add(listenerClass);
+      }
+    }
+
+    // 3. 自动扫描所有模块的 providers，并从对应的模块容器中解析实例
+    const shouldAutoScan = EventModule.options.autoScan ?? true;
+    if (shouldAutoScan === true) {
+      const allModuleRefs = Array.from(registry['moduleRefs'].values());
+      
+      for (const moduleRef of allModuleRefs) {
+        for (const provider of moduleRef.metadata.providers) {
+          // 提取提供者类
+          let providerClass: Function | undefined;
+
+          if (typeof provider === 'function') {
+            providerClass = provider;
+          } else if ('useClass' in provider && provider.useClass) {
+            providerClass = provider.useClass;
+          }
+
+          // 检查是否是事件监听器类
+          if (providerClass && isEventListenerClass(providerClass)) {
+            // 检查是否被排除
+            const isExcluded = EventModule.options.excludeListeners?.includes(providerClass);
+            if (!isExcluded) {
+              // 使用模块容器创建 scanner 并注册监听器
+              // 这样可以确保解析的实例和控制器中注入的是同一个
+              const scanner = new EventListenerScanner(eventEmitter, moduleRef.container);
+              scanner.registerListenerClass(providerClass);
+            }
+          }
+        }
+      }
+    }
+
+    // 4. 注册通过选项配置的强制包含类（使用根容器）
+    if (EventModule.options.includeListeners) {
+      const scanner = new EventListenerScanner(eventEmitter, rootContainer);
+      for (const listenerClass of EventModule.options.includeListeners) {
+        scanner.registerListenerClass(listenerClass);
+      }
+    }
+
+    // 5. 注册通过 registerListeners 注册的类（使用根容器）
+    if (EventModule.listenerClasses.length > 0) {
+      const scanner = new EventListenerScanner(eventEmitter, rootContainer);
+      scanner.scanAndRegister(EventModule.listenerClasses);
+    }
+
+    return true;
+  }
 }

package/src/events/types.ts

@@ -173,6 +173,25 @@ export interface EventModuleOptions {
    * @param payload - 事件负载
    */
   onError?: (error: Error, event: string | symbol, payload: unknown) => void;
+
+  /**
+   * 是否自动扫描和注册事件监听器
+   * 当设置为 true 时，框架会在应用启动时自动扫描所有模块中使用 @OnEvent 装饰器的类
+   * @default true
+   */
+  autoScan?: boolean;
+
+  /**
+   * 需要排除的监听器类（不自动注册）
+   * 用于在自动扫描时排除某些类
+   */
+  excludeListeners?: Function[];
+
+  /**
+   * 额外的监听器类（强制注册）
+   * 即使 autoScan 为 false，这些类也会被注册
+   */
+  includeListeners?: Function[];
 }
 
 /**

package/tests/auth/auth-decorators.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import {
   Auth,

package/tests/auth/oauth2-service.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { OAuth2Service } from '../../src/auth/oauth2';
 import { JWTUtil } from '../../src/auth/jwt';

package/tests/cache/cache-decorators-extended.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import {
   Cacheable,

package/tests/cache/cache-decorators.test.ts

@@ -1,4 +1,3 @@
-import 'reflect-metadata';
 import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
 import { Application } from '../../src/core/application';
 import { Controller } from '../../src/controller/controller';

package/tests/cache/cache-interceptors.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import {
   CacheableInterceptor,

package/tests/cache/cache-module.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { MODULE_METADATA_KEY } from '../../src/di/module';
 import { Container } from '../../src/di/container';

package/tests/cache/cache-service-proxy.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import {
   CacheServiceProxy,

package/tests/config/config-center-integration.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { MODULE_METADATA_KEY } from '../../src/di/module';
 import {

package/tests/config/config-module-extended.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { ConfigModule } from '../../src/config/config-module';
 import { ConfigService } from '../../src/config/service';

package/tests/config/config-module.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { MODULE_METADATA_KEY } from '../../src/di/module';
 import { Container } from '../../src/di/container';

package/tests/controller/controller.test.ts

@@ -1,4 +1,3 @@
-import 'reflect-metadata';
 import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
 import { Application } from '../../src/core/application';
 import { Controller, ControllerRegistry } from '../../src/controller/controller';

package/tests/controller/param-binder.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { ParamBinder } from '../../src/controller/param-binder';
 import {

package/tests/controller/path-combination.test.ts

@@ -1,4 +1,3 @@
-import 'reflect-metadata';
 import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
 import { Application } from '../../src/core/application';
 import { Controller, ControllerRegistry } from '../../src/controller/controller';

package/tests/core/application.test.ts

@@ -53,5 +53,39 @@ describe('Application', () => {
     const data = await response.json();
     expect(data.error).toBe('Not Found');
   });
+
+  test('should accept reusePort option', async () => {
+    const port = getTestPort();
+    app = new Application({ port, reusePort: true });
+    await app.listen();
+
+    const server = app.getServer();
+    expect(server).toBeDefined();
+    expect(server?.isRunning()).toBe(true);
+
+    const response = await fetch(`http://localhost:${port}/api/ping`);
+    expect(response.status).toBe(404);
+  });
+
+  test('should allow two servers on same port with reusePort (Linux only)', async () => {
+    if (process.platform !== 'linux') {
+      console.log('Skipping reusePort dual-bind test: only works on Linux');
+      return;
+    }
+
+    const port = getTestPort();
+    app = new Application({ port, reusePort: true });
+    await app.listen();
+
+    const app2 = new Application({ port, reusePort: true });
+    await app2.listen();
+
+    try {
+      const response = await fetch(`http://localhost:${port}/api/test`);
+      expect(response.status).toBe(404);
+    } finally {
+      await app2.stop();
+    }
+  });
 });
 

package/tests/database/database-module.test.ts

@@ -3,7 +3,6 @@ import { DatabaseModule, DatabaseService, DATABASE_SERVICE_TOKEN } from '../../s
 import { Container } from '../../src/di/container';
 import { ModuleRegistry } from '../../src/di/module-registry';
 import { MODULE_METADATA_KEY } from '../../src/di/module';
-import 'reflect-metadata';
 
 describe('DatabaseModule', () => {
   let container: Container;

package/tests/database/orm.test.ts

@@ -11,7 +11,6 @@ import {
 } from '../../src/database/orm';
 import { DatabaseService, DATABASE_SERVICE_TOKEN } from '../../src/database';
 import { Container } from '../../src/di/container';
-import 'reflect-metadata';
 
 // 测试实体
 @Entity('test_users')

package/tests/database/postgres-mysql-integration.test.ts

@@ -7,7 +7,6 @@ import {
 import { Container } from '../../src/di/container';
 import { ModuleRegistry } from '../../src/di/module-registry';
 import { MODULE_METADATA_KEY } from '../../src/di/module';
-import 'reflect-metadata';
 
 /**
  * PostgreSQL/MySQL 集成测试

package/tests/database/transaction.test.ts

@@ -9,7 +9,6 @@ import {
 } from '../../src/database/orm';
 import { DatabaseService, DATABASE_SERVICE_TOKEN } from '../../src/database';
 import { Container } from '../../src/di/container';
-import 'reflect-metadata';
 
 describe('TransactionManager', () => {
   let container: Container;

package/tests/di/container.test.ts

@@ -1,4 +1,3 @@
-import 'reflect-metadata';
 import { describe, expect, test, beforeEach } from 'bun:test';
 import { Container } from '../../src/di/container';
 import { Lifecycle } from '../../src/di/types';

package/tests/error/error-handler.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { handleError } from '../../src/error/handler';
 import { HttpException, BadRequestException, UnauthorizedException, ForbiddenException, NotFoundException } from '../../src/error';

package/tests/events/event-decorators.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 import {
   OnEvent,
   getOnEventMetadata,

package/tests/events/event-listener-scanner.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { EventListenerScanner, EVENT_LISTENER_SCANNER_TOKEN } from '../../src/events/event-module';
 import { EventEmitterService } from '../../src/events/service';

package/tests/events/event-module.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { EventModule } from '../../src/events/event-module';
 import { EventEmitterService } from '../../src/events/service';

package/tests/extensions/logger-module.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { Container } from '../../src/di/container';
 import { MODULE_METADATA_KEY } from '../../src/di/module';

package/tests/health/health-module.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test } from 'bun:test';
-import 'reflect-metadata';
 
 import { MODULE_METADATA_KEY } from '../../src/di/module';
 import {

package/tests/integration/oauth2-e2e.test.ts

@@ -1,4 +1,3 @@
-import 'reflect-metadata';
 import { describe, expect, test, afterEach, beforeEach } from 'bun:test';
 import { Application } from '../../src/core/application';
 import { SecurityModule } from '../../src/security/security-module';

package/tests/integration/session-e2e.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
-import 'reflect-metadata';
 import {
   Application,
   SessionModule,

package/tests/interceptor/base-interceptor.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { BaseInterceptor } from '../../src/interceptor/base-interceptor';
 import { Container } from '../../src/di/container';

package/tests/interceptor/builtin/cache-interceptor.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
-import 'reflect-metadata';
 
 import {
   Cache,

package/tests/interceptor/builtin/log-interceptor.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach, mock } from 'bun:test';
-import 'reflect-metadata';
 
 import { Container } from '../../../src/di/container';
 import { Context } from '../../../src/core/context';