@dangao/bun-server 1.1.4 → 1.3.0

package/src/controller/param-binder.ts

@@ -1,8 +1,15 @@
 import type { Context } from '../core/context';
-import { getParamMetadata, ParamType, type ParamMetadata } from './decorators';
+import {
+  getParamMetadata,
+  ParamType,
+  type ParamMetadata,
+  type QueryMapOptions,
+  type HeaderMapOptions,
+} from './decorators';
 import { Container } from '../di/container';
 import { SessionService } from '../session/service';
 import { SESSION_SERVICE_TOKEN } from '../session/types';
+import { contextStore } from '../core/context-service';
 
 /**
  * 参数绑定器
@@ -102,6 +109,13 @@ export class ParamBinder {
           // SessionService 未注册，返回 undefined
         }
         return undefined;
+      case ParamType.CONTEXT:
+        // 从 AsyncLocalStorage 获取当前请求的 Context
+        return contextStore.getStore() ?? context;
+      case ParamType.QUERY_MAP:
+        return await this.getQueryMapValue(meta.options as QueryMapOptions, context);
+      case ParamType.HEADER_MAP:
+        return await this.getHeaderMapValue(meta.options as HeaderMapOptions, context);
       default:
         return undefined;
     }
@@ -153,5 +167,81 @@ export class ParamBinder {
   private static getHeaderValue(key: string, context: Context): string | null {
     return context.getHeader(key);
   }
+
+  /**
+   * 获取 QueryMap 值
+   * @param options - 装饰器选项
+   * @param context - 请求上下文
+   */
+  private static async getQueryMapValue(
+    options: QueryMapOptions | undefined,
+    context: Context,
+  ): Promise<unknown> {
+    const result: Record<string, string | string[]> = {};
+    const searchParams = context.query;
+    // 收集所有键，处理重复 key -> string[]
+    for (const key of searchParams.keys()) {
+      const values = searchParams.getAll(key);
+      if (values.length === 1) {
+        result[key] = values[0];
+      } else {
+        result[key] = values;
+      }
+    }
+
+    let output: unknown = result;
+    if (options?.transform) {
+      output = await options.transform(result);
+    }
+    if (options?.validate) {
+      await options.validate(output as never);
+    }
+    return output;
+  }
+
+  /**
+   * 获取 HeaderMap 值
+   * @param options - 装饰器选项
+   * @param context - 请求上下文
+   */
+  private static async getHeaderMapValue(
+    options: HeaderMapOptions | undefined,
+    context: Context,
+  ): Promise<unknown> {
+    const normalize = options?.normalize ?? true;
+    // Headers API 总是将 header 名称规范化为小写，所以 pick 数组也应该总是小写化
+    const pick = options?.pick?.map((key) => key.toLowerCase());
+    const headers = context.headers;
+    const result: Record<string, string | string[]> = {};
+
+    headers.forEach((value, rawKey) => {
+      // Headers API 总是返回小写的 key，所以 rawKey 已经是小写
+      // normalize 选项决定结果中的 key 格式（虽然实际上总是小写）
+      const key = normalize ? rawKey.toLowerCase() : rawKey;
+      if (pick && !pick.includes(key)) {
+        return;
+      }
+      // 处理可能的多值（逗号分隔），统一 trim
+      const parts = value
+        .split(',')
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+      if (parts.length <= 1) {
+        // 单值也保持 trim 后的形态
+        result[key] = parts[0] ?? '';
+      } else {
+        result[key] = parts;
+      }
+    });
+
+    let output: unknown = result;
+    if (options?.transform) {
+      output = await options.transform(result);
+    }
+    if (options?.validate) {
+      await options.validate(output as never);
+    }
+    return output;
+  }
 }
 

package/src/core/application.ts

@@ -1,5 +1,6 @@
 import { BunServer, type ServerOptions } from './server';
 import { Context } from './context';
+import { contextStore, ContextService, CONTEXT_SERVICE_TOKEN } from './context-service';
 import { RouteRegistry } from '../router/registry';
 import { ControllerRegistry } from '../controller/controller';
 import { MiddlewarePipeline } from '../middleware/pipeline';
@@ -54,6 +55,9 @@ export class Application {
     const interceptorRegistry = new InterceptorRegistry();
     container.registerInstance(INTERCEPTOR_REGISTRY_TOKEN, interceptorRegistry);
 
+    // 自动注册 ContextService
+    container.registerInstance(CONTEXT_SERVICE_TOKEN, new ContextService());
+
     // 默认注册 Logger（如果通过模块注册，会被覆盖）
     this.registerExtension(new LoggerExtension());
   }
@@ -148,29 +152,32 @@ export class Application {
    * @returns 响应对象
    */
   private async handleRequest(context: Context): Promise<Response> {
-    // 对于 POST、PUT、PATCH 请求，提前解析 body 并缓存
-    // 这样可以确保 Request.body 流只读取一次
-    if (['POST', 'PUT', 'PATCH'].includes(context.method)) {
-      await context.getBody();
-    }
+    // 使用 AsyncLocalStorage 包裹请求处理，确保所有中间件和控制器都在请求上下文中执行
+    return await contextStore.run(context, async () => {
+      // 对于 POST、PUT、PATCH 请求，提前解析 body 并缓存
+      // 这样可以确保 Request.body 流只读取一次
+      if (['POST', 'PUT', 'PATCH'].includes(context.method)) {
+        await context.getBody();
+      }
 
-    // 先通过路由解析出处理器信息，便于安全中间件等基于路由元数据做决策
-    const registry = RouteRegistry.getInstance();
-    const router = registry.getRouter();
+      // 先通过路由解析出处理器信息，便于安全中间件等基于路由元数据做决策
+      const registry = RouteRegistry.getInstance();
+      const router = registry.getRouter();
 
-    // 预解析路由，仅设置上下文信息，不执行处理器
-    await router.preHandle(context);
+      // 预解析路由，仅设置上下文信息，不执行处理器
+      await router.preHandle(context);
 
-    // 再进入中间件管道，由中间件（如安全过滤器）根据 routeHandler 和 Auth 元数据做校验，
-    // 最后再由路由真正执行控制器方法
-    return await this.middlewarePipeline.run(context, async () => {
-      const response = await router.handle(context);
-      if (response) {
-        return response;
-      }
+      // 再进入中间件管道，由中间件（如安全过滤器）根据 routeHandler 和 Auth 元数据做校验，
+      // 最后再由路由真正执行控制器方法
+      return await this.middlewarePipeline.run(context, async () => {
+        const response = await router.handle(context);
+        if (response) {
+          return response;
+        }
 
-      context.setStatus(404);
-      return context.createResponse({ error: 'Not Found' });
+        context.setStatus(404);
+        return context.createResponse({ error: 'Not Found' });
+      });
     });
   }
 

package/src/core/context-service.ts

@@ -0,0 +1,134 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import { Context } from './context';
+import { Injectable } from '../di/decorators';
+
+/**
+ * Context 存储（AsyncLocalStorage）
+ * 用于在请求级别存储和访问 Context
+ */
+export const contextStore = new AsyncLocalStorage<Context>();
+
+/**
+ * ContextService Token
+ */
+export const CONTEXT_SERVICE_TOKEN = Symbol('ContextService');
+
+/**
+ * 上下文服务
+ * 提供统一的上下文访问服务，通过依赖注入方式访问请求上下文
+ */
+@Injectable()
+export class ContextService {
+  /**
+   * 获取当前请求的 Context
+   * 使用 AsyncLocalStorage 实现请求级别隔离
+   * @returns 当前请求的 Context，如果不在请求上下文中则返回 undefined
+   */
+  public getContext(): Context | undefined {
+    return contextStore.getStore();
+  }
+
+  /**
+   * 获取请求头
+   * @param key - 请求头键名
+   * @returns 请求头值，如果不存在则返回 null
+   */
+  public getHeader(key: string): string | null {
+    const context = this.getContext();
+    return context?.getHeader(key) ?? null;
+  }
+
+  /**
+   * 获取查询参数
+   * @param key - 查询参数键名
+   * @returns 查询参数值，如果不存在则返回 null
+   */
+  public getQuery(key: string): string | null {
+    const context = this.getContext();
+    return context?.getQuery(key) ?? null;
+  }
+
+  /**
+   * 获取所有查询参数
+   * @returns 查询参数对象
+   */
+  public getQueryAll(): Record<string, string> {
+    const context = this.getContext();
+    return context?.getQueryAll() ?? {};
+  }
+
+  /**
+   * 获取路径参数
+   * @param key - 路径参数键名
+   * @returns 路径参数值，如果不存在则返回 undefined
+   */
+  public getParam(key: string): string | undefined {
+    const context = this.getContext();
+    return context?.getParam(key);
+  }
+
+  /**
+   * 获取请求体
+   * @returns 请求体（已解析的）
+   */
+  public getBody(): unknown {
+    const context = this.getContext();
+    return context?.body ?? null;
+  }
+
+  /**
+   * 获取请求方法
+   * @returns HTTP 方法
+   */
+  public getMethod(): string {
+    const context = this.getContext();
+    return context?.method ?? '';
+  }
+
+  /**
+   * 获取请求路径
+   * @returns 请求路径
+   */
+  public getPath(): string {
+    const context = this.getContext();
+    return context?.path ?? '';
+  }
+
+  /**
+   * 获取请求 URL
+   * @returns 请求 URL
+   */
+  public getUrl(): URL | undefined {
+    const context = this.getContext();
+    return context?.url;
+  }
+
+  /**
+   * 获取客户端 IP 地址
+   * @returns 客户端 IP 地址
+   */
+  public getClientIp(): string {
+    const context = this.getContext();
+    return context?.getClientIp() ?? 'unknown';
+  }
+
+  /**
+   * 设置响应头
+   * @param key - 响应头键名
+   * @param value - 响应头值
+   */
+  public setHeader(key: string, value: string): void {
+    const context = this.getContext();
+    context?.setHeader(key, value);
+  }
+
+  /**
+   * 设置状态码
+   * @param code - HTTP 状态码
+   */
+  public setStatus(code: number): void {
+    const context = this.getContext();
+    context?.setStatus(code);
+  }
+}
+

package/src/core/index.ts

@@ -1,4 +1,5 @@
 export { Application, type ApplicationOptions } from './application';
 export { BunServer, type ServerOptions } from './server';
 export { Context } from './context';
+export { ContextService, CONTEXT_SERVICE_TOKEN, contextStore } from './context-service';
 

package/src/di/container.ts

@@ -11,6 +11,7 @@ import {
 } from "./decorators";
 import { LoggerManager } from "@dangao/logsmith";
 import type { Constructor } from "@/core/types";
+import { contextStore } from "../core/context-service";
 
 /**
  * 依赖注入容器
@@ -36,6 +37,12 @@ export class Container {
    */
   private readonly singletons = new Map<string | symbol, unknown>();
 
+  /**
+   * 请求作用域实例缓存（使用 WeakMap 存储，key 为 Context）
+   * 每个请求都有独立的实例映射
+   */
+  private readonly scopedInstances = new WeakMap<object, Map<string | symbol, unknown>>();
+
   /**
    * 类型到 token 的映射（用于接口注入）
    */
@@ -144,6 +151,22 @@ export class Container {
       }
     }
 
+    // 检查请求作用域缓存
+    if (provider.lifecycle === Lifecycle.Scoped) {
+      const context = contextStore.getStore();
+      if (context) {
+        let scopedMap = this.scopedInstances.get(context);
+        if (!scopedMap) {
+          scopedMap = new Map();
+          this.scopedInstances.set(context, scopedMap);
+        }
+        const scopedInstance = scopedMap.get(tokenKey);
+        if (scopedInstance) {
+          return scopedInstance as T;
+        }
+      }
+    }
+
     // 使用工厂函数或实例化
     let instance: T;
     if (provider.factory) {
@@ -167,6 +190,19 @@ export class Container {
       this.singletons.set(tokenKey, instance);
     }
 
+    // 缓存请求作用域实例
+    if (provider.lifecycle === Lifecycle.Scoped) {
+      const context = contextStore.getStore();
+      if (context) {
+        let scopedMap = this.scopedInstances.get(context);
+        if (!scopedMap) {
+          scopedMap = new Map();
+          this.scopedInstances.set(context, scopedMap);
+        }
+        scopedMap.set(tokenKey, instance);
+      }
+    }
+
     return instance;
   }
 
@@ -213,30 +249,57 @@ export class Container {
         }
       }
 
-      // 使用工厂函数或实现类
-      if (provider.factory) {
-        const instance = provider.factory();
-        if (provider.lifecycle === Lifecycle.Singleton) {
-          this.singletons.set(token, instance);
+      // 检查请求作用域缓存
+      if (provider.lifecycle === Lifecycle.Scoped) {
+        const context = contextStore.getStore();
+        if (context) {
+          let scopedMap = this.scopedInstances.get(context);
+          if (!scopedMap) {
+            scopedMap = new Map();
+            this.scopedInstances.set(context, scopedMap);
+          }
+          const scopedInstance = scopedMap.get(token);
+          if (scopedInstance) {
+            return scopedInstance;
+          }
         }
-        return instance;
       }
 
-      if (
+      // 使用工厂函数或实现类
+      let instance: unknown;
+      if (provider.factory) {
+        instance = provider.factory();
+      } else if (
         provider.implementation && typeof provider.implementation === "function"
       ) {
-        const instance = this.instantiate(provider.implementation);
-        if (provider.lifecycle === Lifecycle.Singleton) {
-          this.singletons.set(token, instance);
+        instance = this.instantiate(provider.implementation);
+      } else {
+        throw new Error(
+          `Cannot instantiate token: ${
+            String(token)
+          }. Factory function required.`,
+        );
+      }
+
+      // 缓存单例
+      if (provider.lifecycle === Lifecycle.Singleton) {
+        this.singletons.set(token, instance);
+      }
+
+      // 缓存请求作用域实例
+      if (provider.lifecycle === Lifecycle.Scoped) {
+        const context = contextStore.getStore();
+        if (context) {
+          let scopedMap = this.scopedInstances.get(context);
+          if (!scopedMap) {
+            scopedMap = new Map();
+            this.scopedInstances.set(context, scopedMap);
+          }
+          scopedMap.set(token, instance);
         }
-        return instance;
       }
 
-      throw new Error(
-        `Cannot instantiate token: ${
-          String(token)
-        }. Factory function required.`,
-      );
+      return instance;
     }
 
     // 对于构造函数类型，使用公共 resolve 方法
@@ -286,12 +349,14 @@ export class Container {
 
   /**
    * 清除所有注册（主要用于测试）
+   * 注意：scopedInstances 使用 WeakMap，会自动清理，无需手动清除
    */
   public clear(): void {
     this.providers.clear();
     this.singletons.clear();
     this.typeToToken.clear();
     this.dependencyPlans.clear();
+    // scopedInstances 使用 WeakMap，当 Context 对象被 GC 时会自动清理
   }
 
   /**

package/src/index.ts

@@ -1,12 +1,29 @@
 export { Application, type ApplicationOptions } from './core/application';
 export { BunServer, type ServerOptions } from './core/server';
 export { Context } from './core/context';
+export { ContextService, CONTEXT_SERVICE_TOKEN, contextStore } from './core/context-service';
 export { Route, Router, RouteRegistry } from './router';
 export { GET, POST, PUT, DELETE, PATCH } from './router/decorators';
 export type { HttpMethod, RouteHandler, RouteMatch } from './router/types';
 export { BodyParser, RequestWrapper, ResponseBuilder } from './request';
-export { Body, Query, Param, Header, ParamBinder, Controller, ControllerRegistry } from './controller';
-export type { ParamMetadata, ControllerMetadata } from './controller';
+export {
+  Body,
+  Query,
+  QueryMap,
+  Param,
+  Header,
+  HeaderMap,
+  ParamBinder,
+  Controller,
+  ControllerRegistry,
+} from './controller';
+export { Context as ContextParam } from './controller';
+export type {
+  ParamMetadata,
+  QueryMapOptions,
+  HeaderMapOptions,
+  ControllerMetadata,
+} from './controller';
 export { Container } from './di/container';
 export { Injectable, Inject } from './di/decorators';
 export { Lifecycle, type ProviderConfig, type DependencyMetadata } from './di/types';

package/tests/controller/context-decorator.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
+import { Application } from '../../src/core/application';
+import { Controller, Context, Param } from '../../src/controller';
+import { GET } from '../../src/router';
+import { contextStore } from '../../src/core/context-service';
+import { Context as ContextType } from '../../src/core/context';
+import { getTestPort } from '../utils/test-port';
+
+describe('@Context() Decorator', () => {
+  let app: Application;
+  let port: number;
+
+  beforeEach(() => {
+    port = getTestPort();
+    app = new Application({ port });
+  });
+
+  afterEach(async () => {
+    if (app) {
+      await app.stop();
+    }
+  });
+
+  test('should inject Context into controller method', async () => {
+    @Controller('/api/test')
+    class TestController {
+      @GET('/context')
+      public async getContext(@Context() context: ContextType) {
+        expect(context).toBeDefined();
+        expect(context.path).toBe('/api/test/context');
+        return { path: context.path, method: context.method };
+      }
+    }
+
+    app.registerController(TestController);
+    await app.listen();
+
+    const response = await fetch(`http://localhost:${port}/api/test/context`);
+    expect(response.status).toBe(200);
+    const data = await response.json();
+    expect(data.path).toBe('/api/test/context');
+    expect(data.method).toBe('GET');
+  });
+
+  test('should inject Context with other parameters', async () => {
+    @Controller('/api/test')
+    class TestController {
+      @GET('/users/:id')
+      public async getUser(
+        @Context() context: ContextType,
+        @Param('id') id: string,
+      ) {
+        expect(context).toBeDefined();
+        expect(id).toBe('123');
+        return {
+          id,
+          path: context.path,
+          method: context.method,
+        };
+      }
+    }
+
+    app.registerController(TestController);
+    await app.listen();
+
+    const response = await fetch(`http://localhost:${port}/api/test/users/123`);
+    expect(response.status).toBe(200);
+    const data = await response.json();
+    expect(data.id).toBe('123');
+    expect(data.path).toBe('/api/test/users/123');
+  });
+
+  test('should access headers from injected Context', async () => {
+    @Controller('/api/test')
+    class TestController {
+      @GET('/headers')
+      public async getHeaders(@Context() context: ContextType) {
+        const authHeader = context.getHeader('Authorization');
+        return { authorization: authHeader };
+      }
+    }
+
+    app.registerController(TestController);
+    await app.listen();
+
+    const response = await fetch(`http://localhost:${port}/api/test/headers`, {
+      headers: { 'Authorization': 'Bearer token123' },
+    });
+    expect(response.status).toBe(200);
+    const data = await response.json();
+    expect(data.authorization).toBe('Bearer token123');
+  });
+
+  test('should access query params from injected Context', async () => {
+    @Controller('/api/test')
+    class TestController {
+      @GET('/query')
+      public async getQuery(@Context() context: ContextType) {
+        const name = context.getQuery('name');
+        const age = context.getQuery('age');
+        return { name, age };
+      }
+    }
+
+    app.registerController(TestController);
+    await app.listen();
+
+    const response = await fetch(`http://localhost:${port}/api/test/query?name=John&age=30`);
+    expect(response.status).toBe(200);
+    const data = await response.json();
+    expect(data.name).toBe('John');
+    expect(data.age).toBe('30');
+  });
+
+  test('should access path params from injected Context', async () => {
+    @Controller('/api/test')
+    class TestController {
+      @GET('/users/:id/posts/:postId')
+      public async getPost(@Context() context: ContextType) {
+        const userId = context.getParam('id');
+        const postId = context.getParam('postId');
+        return { userId, postId };
+      }
+    }
+
+    app.registerController(TestController);
+    await app.listen();
+
+    const response = await fetch(`http://localhost:${port}/api/test/users/123/posts/456`);
+    expect(response.status).toBe(200);
+    const data = await response.json();
+    expect(data.userId).toBe('123');
+    expect(data.postId).toBe('456');
+  });
+
+  test('should set response headers via injected Context', async () => {
+    @Controller('/api/test')
+    class TestController {
+      @GET('/custom-header')
+      public async setHeader(@Context() context: ContextType) {
+        context.setHeader('X-Custom-Header', 'custom-value');
+        return { message: 'ok' };
+      }
+    }
+
+    app.registerController(TestController);
+    await app.listen();
+
+    const response = await fetch(`http://localhost:${port}/api/test/custom-header`);
+    expect(response.status).toBe(200);
+    expect(response.headers.get('X-Custom-Header')).toBe('custom-value');
+  });
+
+  test('should handle Context injection in service layer', async () => {
+    // 这个测试验证 ContextService 可以在服务层使用
+    const { ContextService, CONTEXT_SERVICE_TOKEN } = await import('../../src/core/context-service');
+    const container = app.getContainer();
+    const contextService = container.resolve<ContextService>(CONTEXT_SERVICE_TOKEN);
+
+    @Controller('/api/test')
+    class TestController {
+      @GET('/service-context')
+      public async getServiceContext() {
+        // 在控制器中，ContextService 应该能够访问当前请求的 Context
+        const context = contextService.getContext();
+        if (!context) {
+          return { error: 'No context' };
+        }
+        return { path: context.path, method: context.method };
+      }
+    }
+
+    app.registerController(TestController);
+    await app.listen();
+
+    const response = await fetch(`http://localhost:${port}/api/test/service-context`);
+    expect(response.status).toBe(200);
+    const data = await response.json();
+    expect(data.path).toBe('/api/test/service-context');
+    expect(data.method).toBe('GET');
+  });
+});
+