@dangao/bun-server 1.9.0 → 1.12.0

package/docs/zh/lifecycle.md

@@ -0,0 +1,87 @@
+# 生命周期钩子
+
+Bun Server 提供四个生命周期接口，用于在模块和应用启动、关闭时执行初始化或清理逻辑。
+
+## 接口定义
+
+- **OnModuleInit**：`onModuleInit()`，在模块所有 providers 注册完成后调用
+- **OnModuleDestroy**：`onModuleDestroy()`，在应用关闭时调用（反向顺序）
+- **OnApplicationBootstrap**：`onApplicationBootstrap()`，在所有模块初始化完成后、服务器开始监听前调用
+- **OnApplicationShutdown**：`onApplicationShutdown(signal?)`，在优雅停机开始时调用
+
+## 执行顺序
+
+**启动阶段**：`onModuleInit` → `onApplicationBootstrap`
+
+**关闭阶段**：`onApplicationShutdown` → `onModuleDestroy`（均为反向顺序，即后注册的先执行）
+
+## 示例：DatabaseService 的初始化和销毁
+
+```ts
+import {
+  Application,
+  Injectable,
+  Controller,
+  GET,
+  Module,
+} from '@dangao/bun-server';
+import type {
+  OnModuleInit,
+  OnModuleDestroy,
+  OnApplicationBootstrap,
+  OnApplicationShutdown,
+} from '@dangao/bun-server';
+
+@Injectable()
+class DatabaseService implements OnModuleInit, OnModuleDestroy {
+  private connected = false;
+
+  public async onModuleInit(): Promise<void> {
+    console.log('[DatabaseService] 正在连接数据库...');
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    this.connected = true;
+    console.log('[DatabaseService] 已连接');
+  }
+
+  public async onModuleDestroy(): Promise<void> {
+    console.log('[DatabaseService] 正在关闭数据库连接...');
+    this.connected = false;
+    console.log('[DatabaseService] 已断开');
+  }
+
+  public isConnected(): boolean {
+    return this.connected;
+  }
+}
+
+@Injectable()
+class AppService implements OnApplicationBootstrap, OnApplicationShutdown {
+  public onApplicationBootstrap(): void {
+    console.log('[AppService] 应用已启动');
+  }
+
+  public onApplicationShutdown(signal?: string): void {
+    console.log(`[AppService] 应用正在关闭 (signal: ${signal ?? 'none'})`);
+  }
+}
+
+@Controller('/api')
+class AppController {
+  @GET('/status')
+  public status(): object {
+    return { status: 'running', timestamp: Date.now() };
+  }
+}
+
+@Module({
+  controllers: [AppController],
+  providers: [DatabaseService, AppService],
+})
+class AppModule {}
+
+const app = new Application({ port: 3000 });
+app.registerModule(AppModule);
+await app.listen();
+```
+
+按 Ctrl+C 触发关闭时，将依次执行 `onApplicationShutdown` 和 `onModuleDestroy`。

package/docs/zh/migration.md

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

package/docs/zh/testing.md

@@ -0,0 +1,119 @@
+# 测试模块
+
+Bun Server 提供 `TestingModule` 用于单元测试和集成测试，支持 provider 覆盖和 HTTP 客户端模拟。
+
+## Test.createTestingModule()
+
+使用 `Test.createTestingModule()` 创建测试模块，传入与 `@Module()` 相同的元数据：
+
+```ts
+import { Test, Controller, GET } from '@dangao/bun-server';
+
+const module = await Test.createTestingModule({
+  controllers: [UserController],
+  providers: [UserService],
+  imports: [ConfigModule.forRoot({ defaultConfig: {} })],
+}).compile();
+```
+
+## Provider 覆盖
+
+通过 `overrideProvider()` 链式调用覆盖依赖，支持三种方式：
+
+- **useValue(value)**：使用固定值覆盖
+- **useClass(cls)**：使用替代类覆盖
+- **useFactory(factory)**：使用工厂函数覆盖
+
+```ts
+const mockService = { find: () => ({ id: '1', name: 'Mock' }) };
+
+const module = await Test.createTestingModule({
+  controllers: [UserController],
+  providers: [UserService],
+})
+  .overrideProvider(UserService)
+  .useValue(mockService)
+  .compile();
+```
+
+## TestingModule 方法
+
+- **get(token)**：从 DI 容器获取 provider 实例
+- **createApplication(options?)**：创建 `Application` 实例并注册所有 providers、controllers
+- **createHttpClient(options?)**：创建 HTTP 测试客户端，自动启动应用并返回 `TestHttpClient`
+
+```ts
+const service = module.get(UserService);
+const app = module.createApplication();
+const client = await module.createHttpClient();
+```
+
+## TestHttpClient
+
+`createHttpClient()` 返回的客户端提供以下方法：
+
+- **get(path, options?)**：GET 请求
+- **post(path, options?)**：POST 请求
+- **put(path, options?)**：PUT 请求
+- **delete(path, options?)**：DELETE 请求
+- **patch(path, options?)**：PATCH 请求
+- **close()**：关闭测试服务器
+
+`options` 支持 `headers`、`body`、`query`。响应对象包含 `status`、`headers`、`body`、`text`、`ok`。
+
+## 配合 bun:test 使用
+
+```ts
+import { describe, test, expect } from 'bun:test';
+import { Test, Controller, GET, Injectable } from '@dangao/bun-server';
+
+@Injectable()
+class Greeter {
+  public greet(name: string): string {
+    return `Hello, ${name}!`;
+  }
+}
+
+@Controller('/api')
+class GreetController {
+  public constructor(private readonly greeter: Greeter) {}
+
+  @GET('/greet')
+  public greet(): object {
+    return { message: this.greeter.greet('World') };
+  }
+}
+
+describe('GreetController', () => {
+  test('应返回问候消息', async () => {
+    const module = await Test.createTestingModule({
+      controllers: [GreetController],
+      providers: [Greeter],
+    }).compile();
+
+    const client = await module.createHttpClient();
+    const res = await client.get('/api/greet');
+    await client.close();
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ message: 'Hello, World!' });
+  });
+
+  test('可使用 mock 覆盖 provider', async () => {
+    const mockGreeter = { greet: (n: string) => `Mock: ${n}` };
+    const module = await Test.createTestingModule({
+      controllers: [GreetController],
+      providers: [Greeter],
+    })
+      .overrideProvider(Greeter)
+      .useValue(mockGreeter)
+      .compile();
+
+    const client = await module.createHttpClient();
+    const res = await client.get('/api/greet');
+    await client.close();
+
+    expect(res.body).toEqual({ message: 'Mock: World' });
+  });
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dangao/bun-server",
-  "version": "1.9.0",
+  "version": "1.12.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/cache/cache-module.ts

@@ -1,4 +1,5 @@
 import { Module, MODULE_METADATA_KEY, type ModuleProvider } from '../di/module';
+import { type AsyncModuleOptions, registerAsyncProviders } from '../di/async-module';
 
 import { CacheService } from './service';
 import {
@@ -86,6 +87,30 @@ export class CacheModule {
     return CacheModule;
   }
 
+  /**
+   * 异步创建缓存模块
+   * @param asyncOptions - 异步配置选项
+   */
+  public static forRootAsync(
+    asyncOptions: AsyncModuleOptions<CacheModuleOptions>,
+  ): typeof CacheModule {
+    const tokenMap = new Map<symbol, (config: CacheModuleOptions) => unknown>();
+    tokenMap.set(CACHE_SERVICE_TOKEN, (config) => {
+      const resolvedConfig: CacheModuleOptions = {
+        ...config,
+        store: config.store ?? new MemoryCacheStore({ cleanupInterval: 60000 }),
+      };
+      return new CacheService(resolvedConfig);
+    });
+    tokenMap.set(CACHE_OPTIONS_TOKEN, (config) => config);
+
+    return registerAsyncProviders(
+      CacheModule,
+      asyncOptions,
+      tokenMap,
+    ) as typeof CacheModule;
+  }
+
   /**
    * 获取缓存后处理器
    * 用于在应用启动时注册到 DI 容器

package/src/client/generator.ts

@@ -0,0 +1,36 @@
+import { RouteRegistry } from '../router/registry';
+import type { RouteManifest, RouteManifestEntry } from './types';
+
+/**
+ * 客户端清单生成器
+ * 从 RouteRegistry 提取路由元数据，生成路由清单
+ */
+export class ClientGenerator {
+  /**
+   * 从当前 RouteRegistry 生成路由清单
+   */
+  public static generate(): RouteManifest {
+    const registry = RouteRegistry.getInstance();
+    const router = registry.getRouter();
+    const routes = router.getRoutes();
+    const entries: RouteManifestEntry[] = [];
+
+    for (const route of routes) {
+      entries.push({
+        method: route.method,
+        path: route.path,
+        controllerName: route.controllerClass?.name ?? 'unknown',
+        methodName: route.methodName ?? 'unknown',
+      });
+    }
+
+    return { routes: entries };
+  }
+
+  /**
+   * 生成清单的 JSON 字符串
+   */
+  public static generateJSON(): string {
+    return JSON.stringify(ClientGenerator.generate(), null, 2);
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,8 @@
+export { ClientGenerator } from './generator';
+export { createClient } from './runtime';
+export type {
+  RouteManifest,
+  RouteManifestEntry,
+  ClientConfig,
+  ClientRequestOptions,
+} from './types';

package/src/client/runtime.ts

@@ -0,0 +1,101 @@
+import type { ClientConfig, ClientRequestOptions, RouteManifest } from './types';
+
+/**
+ * 将路径中的 :param 占位符替换为实际值
+ */
+function buildUrl(
+  baseUrl: string,
+  path: string,
+  options?: ClientRequestOptions,
+): string {
+  let resolvedPath = path;
+
+  if (options?.params) {
+    for (const [key, value] of Object.entries(options.params)) {
+      resolvedPath = resolvedPath.replace(`:${key}`, encodeURIComponent(value));
+    }
+  }
+
+  let url = `${baseUrl}${resolvedPath}`;
+
+  if (options?.query) {
+    const params = new URLSearchParams(options.query);
+    url += `?${params.toString()}`;
+  }
+
+  return url;
+}
+
+/**
+ * 从路由清单创建类型安全的 API 客户端
+ *
+ * 客户端结构按控制器名称（去除 Controller 后缀，转小写）分组，
+ * 每个方法名直接映射为函数调用。
+ *
+ * 示例：
+ * ```
+ * const client = createClient(manifest, { baseUrl: 'http://localhost:3000' });
+ * const result = await client.user.getUser({ params: { id: '1' } });
+ * ```
+ */
+export function createClient(
+  manifest: RouteManifest,
+  config: ClientConfig,
+): Record<string, Record<string, (options?: ClientRequestOptions) => Promise<unknown>>> {
+  const fetchFn = config.fetch ?? globalThis.fetch;
+  const groups = new Map<string, Map<string, { method: string; path: string }>>();
+
+  for (const route of manifest.routes) {
+    const groupName = route.controllerName
+      .replace(/Controller$/i, '')
+      .replace(/^./, (c) => c.toLowerCase());
+
+    if (!groups.has(groupName)) {
+      groups.set(groupName, new Map());
+    }
+    groups.get(groupName)!.set(route.methodName, {
+      method: route.method,
+      path: route.path,
+    });
+  }
+
+  const client: Record<string, Record<string, (options?: ClientRequestOptions) => Promise<unknown>>> = {};
+
+  for (const [groupName, methods] of groups) {
+    const group: Record<string, (options?: ClientRequestOptions) => Promise<unknown>> = {};
+
+    for (const [methodName, routeInfo] of methods) {
+      group[methodName] = async (options?: ClientRequestOptions) => {
+        const url = buildUrl(config.baseUrl, routeInfo.path, options);
+
+        const fetchOptions: RequestInit = {
+          method: routeInfo.method,
+          headers: {
+            'Content-Type': 'application/json',
+            ...(config.headers || {}),
+            ...(options?.headers || {}),
+          },
+        };
+
+        if (options?.body && routeInfo.method !== 'GET') {
+          fetchOptions.body = typeof options.body === 'string'
+            ? options.body
+            : JSON.stringify(options.body);
+        }
+
+        const response = await fetchFn(url, fetchOptions);
+        const text = await response.text();
+
+        try {
+          return JSON.parse(text);
+        } catch {
+          return text;
+        }
+      };
+    }
+
+    client[groupName] = group;
+  }
+
+  return client;
+}

package/src/client/types.ts

@@ -0,0 +1,38 @@
+/**
+ * 路由清单中的单个端点描述
+ */
+export interface RouteManifestEntry {
+  method: string;
+  path: string;
+  controllerName: string;
+  methodName: string;
+}
+
+/**
+ * 完整的路由清单
+ */
+export interface RouteManifest {
+  routes: RouteManifestEntry[];
+}
+
+/**
+ * 客户端请求选项
+ */
+export interface ClientRequestOptions {
+  params?: Record<string, string>;
+  query?: Record<string, string>;
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+
+/**
+ * 客户端配置
+ */
+export interface ClientConfig {
+  baseUrl: string;
+  headers?: Record<string, string>;
+  /**
+   * 自定义 fetch 实现（可选，用于测试）
+   */
+  fetch?: typeof fetch;
+}

package/src/config/config-module.ts

@@ -2,6 +2,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 { type AsyncModuleOptions, registerAsyncProviders } from '../di/async-module';
 
 import { ConfigService } from './service';
 import { CONFIG_SERVICE_TOKEN, type ConfigModuleOptions } from './types';
@@ -70,6 +71,47 @@ export class ConfigModule {
     return ConfigModule;
   }
 
+  /**
+   * 异步创建配置模块
+   * 支持 configFiles 选项从 .json / .jsonc / .json5 文件异步加载配置
+   * @param asyncOptions - 异步配置选项
+   */
+  public static forRootAsync(
+    asyncOptions: AsyncModuleOptions<ConfigModuleOptions>,
+  ): typeof ConfigModule {
+    const tokenMap = new Map<symbol, (config: ConfigModuleOptions) => unknown | Promise<unknown>>();
+    tokenMap.set(CONFIG_SERVICE_TOKEN, async (options) => {
+      const env = ConfigModule.snapshotEnv();
+      const defaultConfig = (options.defaultConfig ?? {}) as Record<string, unknown>;
+
+      // 从配置文件加载（按数组顺序，后者覆盖前者）
+      let fileConfig: Record<string, unknown> = {};
+      if (options.configFiles?.length) {
+        const fileConfigs = await Promise.all(
+          options.configFiles.map((f) => ConfigService.loadConfigFile(f)),
+        );
+        for (const fc of fileConfigs) {
+          fileConfig = { ...fileConfig, ...fc };
+        }
+      }
+
+      const loadedConfig = (options.load ? options.load(env) : {}) as Record<string, unknown>;
+
+      // 优先级：env load > configFiles > defaultConfig
+      const mergedConfig = { ...defaultConfig, ...fileConfig, ...loadedConfig };
+      if (options.validate) {
+        options.validate(mergedConfig);
+      }
+      return new ConfigService(mergedConfig, options.namespace);
+    });
+
+    return registerAsyncProviders(
+      ConfigModule,
+      asyncOptions,
+      tokenMap,
+    ) as typeof ConfigModule;
+  }
+
   /**
    * 获取环境变量快照
    * 方便测试和未来扩展（如 .env 文件解析）
@@ -168,12 +210,10 @@ export class ConfigModule {
               configInfo.namespaceId,
             )
             .then((result) => {
-              // 解析配置内容（支持 JSON）
               try {
-                const parsed = JSON.parse(result.content);
+                const parsed = ConfigService.parseConfigContent(result.content);
                 ConfigModule.setValueByPath(configMap, configPath, parsed);
               } catch {
-                // 如果不是 JSON，直接使用字符串值
                 ConfigModule.setValueByPath(configMap, configPath, result.content);
               }
             })
@@ -220,7 +260,7 @@ export class ConfigModule {
               // 解析配置内容
               let parsedValue: unknown;
               try {
-                parsedValue = JSON.parse(result.content);
+                parsedValue = ConfigService.parseConfigContent(result.content);
               } catch {
                 parsedValue = result.content;
               }

package/src/config/index.ts

@@ -3,6 +3,7 @@ export { ConfigService } from './service';
 export {
   CONFIG_SERVICE_TOKEN,
   type ConfigModuleOptions,
+  type ConfigFileFormat,
 } from './types';
 
 

package/src/config/service.ts

@@ -1,8 +1,58 @@
+import type { ConfigFileFormat } from './types';
+
 /**
  * 配置服务
  * 提供类型安全的配置访问能力
  */
 export class ConfigService<TConfig extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * 解析配置内容，按 JSON -> JSONC -> JSON5 顺序自动尝试
+   * 利用 Bun 1.3.6+ 的 Bun.JSONC 和 Bun 1.3.7+ 的 Bun.JSON5
+   * @param content - 配置文本内容
+   * @param format - 强制指定格式（可选），省略则自动检测
+   */
+  public static parseConfigContent(content: string, format?: ConfigFileFormat): unknown {
+    if (format === 'jsonc') {
+      return Bun.JSONC.parse(content);
+    }
+    if (format === 'json5') {
+      return Bun.JSON5.parse(content);
+    }
+    if (format === 'json') {
+      return JSON.parse(content);
+    }
+
+    try {
+      return JSON.parse(content);
+    } catch {
+      try {
+        return Bun.JSONC.parse(content);
+      } catch {
+        return Bun.JSON5.parse(content);
+      }
+    }
+  }
+
+  /**
+   * 从文件加载配置，根据扩展名自动选择解析器
+   * @param filePath - 配置文件路径（.json / .jsonc / .json5）
+   */
+  public static async loadConfigFile(filePath: string): Promise<Record<string, unknown>> {
+    const file = Bun.file(filePath);
+    const content = await file.text();
+
+    let format: ConfigFileFormat | undefined;
+    if (filePath.endsWith('.json5')) {
+      format = 'json5';
+    } else if (filePath.endsWith('.jsonc')) {
+      format = 'jsonc';
+    } else if (filePath.endsWith('.json')) {
+      format = 'json';
+    }
+
+    return ConfigService.parseConfigContent(content, format) as Record<string, unknown>;
+  }
+
   private config: TConfig;
   private readonly namespace?: string;
   private configUpdateListeners: Array<(config: TConfig) => void> = [];

package/src/config/types.ts

@@ -1,3 +1,8 @@
+/**
+ * 配置文件解析格式
+ */
+export type ConfigFileFormat = 'json' | 'jsonc' | 'json5';
+
 export interface ConfigModuleOptions<TConfig extends Record<string, unknown> = Record<string, unknown>> {
   /**
    * 默认配置对象（最低优先级）
@@ -10,6 +15,13 @@ export interface ConfigModuleOptions<TConfig extends Record<string, unknown> = R
    */
   load?: (env: Record<string, string | undefined>) => Partial<TConfig>;
 
+  /**
+   * 配置文件路径列表（支持 .json / .jsonc / .json5 格式）
+   * 优先级：configFiles > defaultConfig，按数组顺序后者覆盖前者
+   * 仅在 forRootAsync 中生效（文件读取为异步操作）
+   */
+  configFiles?: string[];
+
   /**
    * 配置验证函数（可抛出错误）
    * 可用于集成 class-validator 风格的校验逻辑