@dangao/bun-server 1.9.0 → 1.10.0

package/README.md

@@ -433,22 +433,71 @@ learning paths, difficulty ratings, and usage scenarios.
 
 ## Benchmark Suite
 
-Benchmarks live in `benchmark/` and rely on `PerformanceHarness` &
-`StressTester`.
+### Internal Micro-benchmarks
+
+`PerformanceHarness` & `StressTester` based benchmarks:
 
 | Script            | Description                                                           |
 | ----------------- | --------------------------------------------------------------------- |
 | `router.bench.ts` | static/dynamic route hits, `router.handle` and stress runs            |
 | `di.bench.ts`     | singleton vs factory resolves, nested dependencies, concurrent stress |
 
-Run directly:
-
 ```bash
 bun benchmark/router.bench.ts
 bun benchmark/di.bench.ts
 ```
 
-Or use `bun run bench*` scripts for convenience.
+### Framework Comparison (bun-server vs Express vs NestJS)
+
+Real HTTP load testing with [wrk](https://github.com/wg/wrk), comparing
+bun-server against Express 5 and NestJS 11. All frameworks run on the same Bun
+runtime to isolate framework overhead.
+
+**Prerequisites:** wrk (`brew install wrk` / `apt install wrk`). The script
+automatically raises `ulimit -n` to 10240 for child processes.
+
+```bash
+bun benchmark/run-wrk-compare.ts        # full comparison (3 tiers)
+TIER=0 bun benchmark/run-wrk-compare.ts  # Light tier only
+bun benchmark/run-wrk.ts                 # bun-server only (3 tiers)
+```
+
+> **Environment:** Apple M2 Pro (8P + 4E cores) / darwin arm64 / Bun 1.3.10
+
+#### Req/Sec (Light: -t2 -c50 -d10s)
+
+| Endpoint              | bun-server   | Express  | NestJS   |
+|-----------------------|--------------|----------|----------|
+| GET /ping             | **31.41k**   | 30.01k   | 26.52k   |
+| GET /json             | **28.22k**   | 25.99k   | 23.64k   |
+| GET /users/:id        | **30.88k**   | 29.91k   | 25.62k   |
+| GET /search?q=        | **29.96k**   | 28.70k   | 25.17k   |
+| POST /users           | **27.65k**   | 21.37k   | 19.38k   |
+| POST /users/validated | **26.60k**   | 21.28k   | 18.93k   |
+| GET /middleware        | **29.52k**   | 28.57k   | 24.69k   |
+| GET /headers          | **30.98k**   | 29.57k   | 26.43k   |
+| GET /io               | **21.37k**   | 19.46k   | 18.49k   |
+
+Zero errors across all frameworks and tiers. See the full report for Medium and
+Heavy tier results.
+
+> 📊 Full comparison report (3 tiers, latency breakdown, per-framework
+> details): [`benchmark/REPORT_COMPARE.md`](./benchmark/REPORT_COMPARE.md)
+>
+> 📋 Single-framework detailed report:
+> [`benchmark/REPORT.md`](./benchmark/REPORT.md)
+
+### Multi-process Benchmark (reusePort, Linux only)
+
+```bash
+bun benchmark/run-wrk-cluster.ts          # default: 1 worker per CPU core
+WORKERS=4 bun benchmark/run-wrk-cluster.ts
+```
+
+Spawns N workers sharing the same port via `SO_REUSEPORT`. The kernel
+distributes connections across processes. Report saved to
+`benchmark/REPORT_CLUSTER.md`. Note: `reusePort` only works on **Linux**;
+macOS/Windows silently ignore it.
 
 ## Docs & Localization
 
@@ -525,6 +574,6 @@ Released under the [MIT License](./LICENSE).
 
 ## Other Languages
 
-- [中文 README](./readme_zh.md)
+- [中文 README](./README_ZH.md)
 
 Enjoy building on Bun Server!

package/dist/core/application.d.ts

@@ -25,6 +25,13 @@ export interface ApplicationOptions {
      * 默认 true
      */
     enableSignalHandlers?: boolean;
+    /**
+     * 是否启用 SO_REUSEPORT
+     * 允许多进程绑定同一端口，用于多进程负载均衡
+     * 仅 Linux 有效，macOS/Windows 会忽略
+     * @default false
+     */
+    reusePort?: boolean;
 }
 /**
  * 应用主类

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;AAS3C;;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;IAqCpE;;OAEG;YACW,oBAAoB;IAqBlC;;;OAGG;YACW,sBAAsB;IAyBpC;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAqBhC;;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;IAyC3B;;;OAGG;IACI,kBAAkB,CAAC,eAAe,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI;IAKtE;;;OAGG;IACI,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAqBrD;;;OAGG;IACH,OAAO,CAAC,kCAAkC;IAc1C;;;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"}
+{"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;AAS3C;;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;IAE/B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;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;IAsCpE;;OAEG;YACW,oBAAoB;IAqBlC;;;OAGG;YACW,sBAAsB;IAyBpC;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAqBhC;;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;IAyC3B;;;OAGG;IACI,kBAAkB,CAAC,eAAe,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI;IAKtE;;;OAGG;IACI,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAqBrD;;;OAGG;IACH,OAAO,CAAC,kCAAkC;IAc1C;;;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

@@ -27,6 +27,13 @@ export interface ServerOptions {
      * 默认 30 秒
      */
     gracefulShutdownTimeout?: number;
+    /**
+     * 是否启用 SO_REUSEPORT
+     * 允许多进程绑定同一端口，用于多进程负载均衡
+     * 仅 Linux 有效，macOS/Windows 会忽略
+     * @default false
+     */
+    reusePort?: boolean;
 }
 /**
  * 服务器封装类

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;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;IAoGpB;;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"}
+{"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;IAEjC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;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;IAqGpB;;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

@@ -1,42 +1,39 @@
 // @bun
-var __create = Object.create;
-var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __toESM = (mod, isNodeMode, target) => {
-  target = mod != null ? __create(__getProtoOf(mod)) : {};
-  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
-  for (let key of __getOwnPropNames(mod))
-    if (!__hasOwnProp.call(to, key))
-      __defProp(to, key, {
-        get: () => mod[key],
-        enumerable: true
-      });
-  return to;
-};
-var __moduleCache = /* @__PURE__ */ new WeakMap;
+function __accessProp(key) {
+  return this[key];
+}
 var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
   if (entry)
     return entry;
   entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
   __moduleCache.set(from, entry);
   return entry;
 };
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __legacyDecorateClassTS = function(decorators, target, key, desc) {
@@ -4006,6 +4003,7 @@ class BunServer {
     this.server = Bun.serve({
       port: this.options.port ?? 3000,
       hostname: this.options.hostname,
+      reusePort: this.options.reusePort,
       fetch: (request, server) => {
         if (this.isShuttingDown) {
           return new Response("Server is shutting down", { status: 503 });
@@ -5860,6 +5858,7 @@ class Application {
     const serverOptions = {
       port: finalPort,
       hostname: finalHostname,
+      reusePort: this.options.reusePort,
       fetch: this.handleRequest.bind(this),
       websocketRegistry: this.websocketRegistry,
       gracefulShutdownTimeout: this.options.gracefulShutdownTimeout

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.9.0",
+  "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

@@ -45,6 +45,14 @@ export interface ApplicationOptions {
    * 默认 true
    */
   enableSignalHandlers?: boolean;
+
+  /**
+   * 是否启用 SO_REUSEPORT
+   * 允许多进程绑定同一端口，用于多进程负载均衡
+   * 仅 Linux 有效，macOS/Windows 会忽略
+   * @default false
+   */
+  reusePort?: boolean;
 }
 
 /**
@@ -112,6 +120,7 @@ export class Application {
     const serverOptions: ServerOptions = {
       port: finalPort,
       hostname: finalHostname,
+      reusePort: this.options.reusePort,
       fetch: this.handleRequest.bind(this),
       websocketRegistry: this.websocketRegistry,
       gracefulShutdownTimeout: this.options.gracefulShutdownTimeout,

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/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';

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

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

package/tests/interceptor/interceptor-advanced-integration.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/interceptor/interceptor-chain.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { InterceptorChain } from '../../src/interceptor/interceptor-chain';
 import type { Interceptor } from '../../src/interceptor/types';

package/tests/interceptor/interceptor-integration.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/interceptor/interceptor-metadata.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { scanInterceptorMetadata } from '../../src/interceptor/metadata';
 import { InterceptorRegistry } from '../../src/interceptor/interceptor-registry';

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

@@ -1,4 +1,3 @@
-import 'reflect-metadata';
 import { describe, expect, test, beforeEach } from 'bun:test';
 import { InterceptorRegistry, INTERCEPTOR_REGISTRY_TOKEN } from '../../src/interceptor';
 import type { Interceptor } from '../../src/interceptor';

package/tests/interceptor/perf/interceptor-performance.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test } from 'bun:test';
-import 'reflect-metadata';
 
 import { PerformanceHarness } from '../../../src/testing/harness';
 import { InterceptorRegistry } from '../../../src/interceptor/interceptor-registry';

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

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { Application } from '../../src/core/application';
 import { MetricsModule, MetricsCollector, createHttpMetricsMiddleware, type CustomMetric } from '../../src/metrics';

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

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 import { ConfigCenterModule, CONFIG_CENTER_TOKEN, type ConfigCenter } from '../../src/microservice/config-center';
 import { Container } from '../../src/di/container';
 import { ModuleRegistry } from '../../src/di/module-registry';

package/tests/microservice/service-client-decorators.test.ts

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

package/tests/microservice/service-registry-decorators.test.ts

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

package/tests/microservice/service-registry.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 import { ServiceRegistryModule, SERVICE_REGISTRY_TOKEN, type ServiceRegistry } from '../../src/microservice/service-registry';
 import { MODULE_METADATA_KEY } from '../../src/di/module';
 import { ControllerRegistry } from '../../src/controller/controller';

package/tests/middleware/builtin/middleware-builtin-extended.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { createCorsMiddleware } from '../../../src/middleware/builtin/cors';
 import { createLoggerMiddleware } from '../../../src/middleware/builtin/logger';

package/tests/middleware/builtin/rate-limit.test.ts

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

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

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

package/tests/middleware/middleware-pipeline.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { MiddlewarePipeline, runMiddlewares } from '../../src/middleware/pipeline';
 import { Context } from '../../src/core/context';

package/tests/middleware/middleware.test.ts

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

package/tests/perf/optimization.test.ts

@@ -5,7 +5,6 @@ import { MiddlewarePipeline } from '../../src/middleware/pipeline';
 import { Container } from '../../src/di/container';
 import { Injectable, Inject } from '../../src/di/decorators';
 import { PerformanceHarness } from '../../src/testing/harness';
-import 'reflect-metadata';
 
 /**
  * 性能优化验证测试

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

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

package/tests/queue/queue-module.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 { Container } from '../../src/di/container';

package/tests/queue/queue-service.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { QueueService } from '../../src/queue/service';
 import type { QueueStore, Job, JobData, QueueModuleOptions } from '../../src/queue/types';

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

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

package/tests/router/router-extended.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { Router } from '../../src/router/router';
 import { RouteRegistry } from '../../src/router/registry';

package/tests/security/guards/guards-integration.test.ts

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

package/tests/security/guards/guards.test.ts

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

package/tests/security/guards/reflector.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { Reflector, REFLECTOR_TOKEN } from '../../../src/security/guards/reflector';
 

package/tests/security/security-filter.test.ts

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

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

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

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

@@ -3,7 +3,6 @@ import { SecurityModule } from '../../src/security/security-module';
 import { MODULE_METADATA_KEY } from '../../src/di/module';
 import { JWT_UTIL_TOKEN, OAUTH2_SERVICE_TOKEN } from '../../src/auth/controller';
 import { AuthenticationManager } from '../../src/security/authentication-manager';
-import 'reflect-metadata';
 
 describe('SecurityModule', () => {
   beforeEach(() => {

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

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { Session, getSessionFromContext } from '../../src/session/decorators';
 import { SessionService } from '../../src/session/service';

package/tests/session/session-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/swagger/decorators.test.ts

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

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

@@ -1,7 +1,6 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
 import { SwaggerModule } from '../../src/swagger/swagger-module';
 import { MODULE_METADATA_KEY } from '../../src/di/module';
-import 'reflect-metadata';
 
 describe('SwaggerModule', () => {
   beforeEach(() => {

package/tests/swagger/ui.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test, beforeEach } from 'bun:test';
-import 'reflect-metadata';
 
 import { createSwaggerUIMiddleware } from '../../src/swagger/ui';
 import { SwaggerExtension } from '../../src/swagger/swagger-extension';

package/tests/validation/class-validator.test.ts

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

package/tests/validation/controller-validation.test.ts

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