@dangao/bun-server 1.0.0 → 1.0.3

package/src/controller/controller.ts

@@ -0,0 +1,251 @@
+import 'reflect-metadata';
+import { Container } from '../di/container';
+import { RouteRegistry } from '../router/registry';
+import type { Context } from '../core/context';
+import { ParamBinder } from './param-binder';
+import { getControllerMetadata, getRouteMetadata } from './metadata';
+import { getClassMiddlewares, getMethodMiddlewares } from '../middleware';
+import type { Middleware } from '../middleware';
+import { getValidationMetadata, validateParameters, ValidationError } from '../validation';
+import { HttpException } from '../error';
+import type { Constructor } from '@/core/types'
+
+/**
+ * 控制器元数据键
+ */
+export const CONTROLLER_METADATA_KEY = Symbol('controller');
+
+/**
+ * 控制器元数据
+ */
+export interface ControllerMetadata {
+  /**
+   * 基础路径
+   */
+  path: string;
+
+  /**
+   * 控制器类
+   */
+  target: new (...args: unknown[]) => unknown;
+}
+
+/**
+ * Controller 装饰器
+ * 标记类为控制器，并指定基础路径
+ * @param path - 控制器基础路径
+ */
+export function Controller(path: string = '') {
+  return function (target: Constructor<unknown>) {
+    // 保存控制器元数据
+    Reflect.defineMetadata(CONTROLLER_METADATA_KEY, { path, target }, target);
+  };
+}
+
+/**
+ * 控制器注册表
+ * 管理所有控制器及其路由
+ */
+export class ControllerRegistry {
+  private static instance: ControllerRegistry;
+  private readonly container: Container;
+  private readonly controllers = new Map<new (...args: unknown[]) => unknown, unknown>();
+  private readonly controllerContainers = new Map<Constructor<unknown>, Container>();
+
+  private constructor() {
+    this.container = new Container();
+  }
+
+  /**
+   * 获取单例实例
+   */
+  public static getInstance(): ControllerRegistry {
+    if (!ControllerRegistry.instance) {
+      ControllerRegistry.instance = new ControllerRegistry();
+    }
+    return ControllerRegistry.instance;
+  }
+
+  /**
+   * 注册控制器
+   * @param controllerClass - 控制器类
+   */
+  public register(controllerClass: Constructor<unknown>, container?: Container): void {
+    const targetContainer = container ?? this.container;
+    this.controllerContainers.set(controllerClass, targetContainer);
+    if (!targetContainer.isRegistered(controllerClass)) {
+      targetContainer.register(controllerClass);
+    }
+
+    // 获取控制器元数据
+    const metadata = getControllerMetadata(controllerClass);
+    if (!metadata) {
+      throw new Error(`Controller ${controllerClass.name} must be decorated with @Controller()`);
+    }
+
+    // 获取路由元数据（从原型获取）
+    const prototype = controllerClass.prototype;
+    const routes = getRouteMetadata(prototype);
+    
+    if (!routes || routes.length === 0) {
+      // 没有路由，跳过（可能是装饰器还没有执行）
+      return;
+    }
+
+    const classMiddlewares = getClassMiddlewares(controllerClass);
+
+    // 注册所有路由
+    const basePath = metadata.path;
+    const registry = RouteRegistry.getInstance();
+
+    for (const route of routes) {
+      // 组合基础路径和方法路径
+      const fullPath = this.combinePaths(basePath, route.path);
+
+      // 获取方法名：优先使用 propertyKey，否则通过函数引用查找
+      let propertyKey = route.propertyKey;
+      if (!propertyKey) {
+        // 通过函数引用查找方法名
+        const prototype = controllerClass.prototype;
+        const propertyNames = Object.getOwnPropertyNames(prototype);
+        for (const key of propertyNames) {
+          if (key === 'constructor') continue;
+          const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
+          if (descriptor && descriptor.value === route.handler) {
+            propertyKey = key;
+            break;
+          }
+        }
+      }
+
+      if (!propertyKey) {
+        // 如果仍然找不到方法名，跳过这个路由
+        continue;
+      }
+
+      // 创建路由处理器，支持控制器方法调用
+      const handler = async (context: Context): Promise<Response> => {
+        try {
+          // 从容器解析控制器实例
+          const controllerContainer = this.controllerContainers.get(controllerClass) ?? this.container;
+          const controllerInstance = controllerContainer.resolve(controllerClass);
+
+          // 绑定参数（从原型获取元数据，因为装饰器元数据保存在原型上）
+          const prototype = controllerClass.prototype;
+          const params = await ParamBinder.bind(prototype, propertyKey!, context, controllerContainer);
+
+          // 执行参数验证
+          const validationMetadata = getValidationMetadata(prototype, propertyKey!);
+          if (validationMetadata.length > 0) {
+            validateParameters(params, validationMetadata);
+          }
+
+          // 调用控制器方法
+          // 优先从实例获取，如果不存在则从原型获取
+          let method = (controllerInstance as Record<string, (...args: unknown[]) => unknown>)[propertyKey!];
+          if (!method || typeof method !== 'function') {
+            // 从构造函数原型获取方法
+            const prototype = controllerClass.prototype;
+            method = prototype[propertyKey!];
+          }
+          if (!method || typeof method !== 'function') {
+            throw new Error(`Method ${propertyKey} not found on controller ${controllerClass.name}`);
+          }
+
+          // 检查是否有事务装饰器
+          let result: unknown;
+          try {
+            const { TransactionInterceptor } = await import('../database/orm/transaction-interceptor');
+            const { getTransactionMetadata } = await import('../database/orm/transaction-decorator');
+            const hasTransaction = getTransactionMetadata(prototype, propertyKey!);
+            if (hasTransaction) {
+              result = TransactionInterceptor.executeWithTransaction(
+                prototype,
+                propertyKey!,
+                method,
+                params,
+                controllerContainer,
+              );
+            } else {
+              result = method.apply(controllerInstance, params);
+            }
+          } catch (error) {
+            // 如果导入失败或执行失败，回退到直接调用
+            result = method.apply(controllerInstance, params);
+          }
+
+          // 处理异步结果
+          const responseData = await Promise.resolve(result);
+
+          // 如果已经是 Response 对象，直接返回
+          if (responseData instanceof Response) {
+            return responseData;
+          }
+
+          // 创建响应
+          return context.createResponse(responseData);
+        } catch (error) {
+          // 使用全局错误处理器，确保错误码和国际化正确应用
+          const { handleError } = await import('../error/handler');
+          return await handleError(error, context);
+        }
+      };
+
+      // 组合中间件：类级 + 方法级
+      const middlewares: Middleware[] = [...classMiddlewares];
+      if (propertyKey) {
+        middlewares.push(...getMethodMiddlewares(prototype, propertyKey));
+      }
+
+      // 注册路由，传递控制器和方法信息
+      registry.register(route.method, fullPath, handler, middlewares, controllerClass, propertyKey);
+    }
+  }
+
+  /**
+   * 组合路径
+   * @param basePath - 基础路径
+   * @param methodPath - 方法路径
+   * @returns 组合后的路径
+   */
+  private combinePaths(basePath: string, methodPath: string): string {
+    // 规范化路径：确保 basePath 以 / 开头，不以 / 结尾
+    const base = basePath.replace(/\/$/, '').replace(/^\/?/, '/');
+    // methodPath 移除前导斜杠
+    const method = methodPath.replace(/^\//, '');
+
+    if (!method) {
+      // 如果方法路径为空，返回基础路径
+      return base === '/' ? '/' : base;
+    }
+    
+    // 组合路径
+    return base + '/' + method;
+  }
+
+  /**
+   * 获取 DI 容器
+   * @returns DI 容器
+   */
+  public getContainer(): Container {
+    return this.container;
+  }
+
+  /**
+   * 获取所有已注册的控制器类
+   * @returns 控制器类数组
+   */
+  public getRegisteredControllers(): Constructor<unknown>[] {
+    return Array.from(this.controllerContainers.keys());
+  }
+
+  /**
+   * 清除所有控制器注册和容器状态（主要用于测试）
+   */
+  public clear(): void {
+    this.controllers.clear();
+    this.container.clear();
+    this.controllerContainers.clear();
+  }
+}
+

package/src/controller/decorators.ts

@@ -0,0 +1,84 @@
+import 'reflect-metadata';
+
+/**
+ * 参数元数据键
+ */
+const PARAM_METADATA_KEY = Symbol('param');
+
+/**
+ * 参数类型枚举
+ */
+export enum ParamType {
+  BODY = 'body',
+  QUERY = 'query',
+  PARAM = 'param',
+  HEADER = 'header',
+  SESSION = 'session',
+}
+
+/**
+ * 参数元数据
+ */
+export interface ParamMetadata {
+  type: ParamType;
+  key?: string;
+  index: number;
+}
+
+/**
+ * 参数装饰器工厂
+ * @param type - 参数类型
+ * @param key - 参数键（可选）
+ * @returns 参数装饰器
+ */
+export function createParamDecorator(type: ParamType, key?: string) {
+  return function (target: any, propertyKey: string | symbol | undefined, parameterIndex: number) {
+    const existingParams: ParamMetadata[] =
+      Reflect.getMetadata(PARAM_METADATA_KEY, target, propertyKey as string) || [];
+    existingParams.push({ type, key, index: parameterIndex });
+    Reflect.defineMetadata(PARAM_METADATA_KEY, existingParams, target, propertyKey as string);
+  };
+}
+
+/**
+ * Body 参数装饰器
+ * @param key - 参数键（可选，用于提取对象中的特定字段）
+ */
+export function Body(key?: string) {
+  return createParamDecorator(ParamType.BODY, key);
+}
+
+/**
+ * Query 参数装饰器
+ * @param key - 查询参数键
+ */
+export function Query(key: string) {
+  return createParamDecorator(ParamType.QUERY, key);
+}
+
+/**
+ * Param 参数装饰器（路径参数）
+ * @param key - 路径参数键
+ */
+export function Param(key: string) {
+  return createParamDecorator(ParamType.PARAM, key);
+}
+
+/**
+ * Header 参数装饰器
+ * @param key - 请求头键
+ */
+export function Header(key: string) {
+  return createParamDecorator(ParamType.HEADER, key);
+}
+
+/**
+ * 获取参数元数据
+ * @param target - 目标对象
+ * @param propertyKey - 属性键
+ * @returns 参数元数据列表
+ */
+export function getParamMetadata(target: any, propertyKey: string): ParamMetadata[] {
+  return Reflect.getMetadata(PARAM_METADATA_KEY, target, propertyKey) || [];
+}
+

package/src/controller/index.ts

@@ -0,0 +1,7 @@
+export { Body, Query, Param, Header, getParamMetadata, ParamType } from './decorators';
+export type { ParamMetadata } from './decorators';
+export { ParamBinder } from './param-binder';
+export { Controller, ControllerRegistry } from './controller';
+export type { ControllerMetadata } from './controller';
+export { getControllerMetadata, getRouteMetadata } from './metadata';
+

package/src/controller/metadata.ts

@@ -0,0 +1,27 @@
+import 'reflect-metadata';
+import type { ControllerMetadata } from './controller';
+import { CONTROLLER_METADATA_KEY } from './controller';
+import type { RouteMetadata } from '../router/decorators';
+import { ROUTE_METADATA_KEY } from '../router/decorators';
+import type { Constructor } from '@/core/types'
+
+/**
+ * 获取控制器元数据
+ * @param target - 控制器类
+ * @returns 控制器元数据
+ */
+export function getControllerMetadata(
+  target: Constructor<unknown>,
+): ControllerMetadata | undefined {
+  return Reflect.getMetadata(CONTROLLER_METADATA_KEY, target);
+}
+
+/**
+ * 获取路由元数据
+ * @param target - 控制器原型
+ * @returns 路由元数据列表
+ */
+export function getRouteMetadata(target: unknown): RouteMetadata[] {
+  return Reflect.getMetadata(ROUTE_METADATA_KEY, target as Object) || [];
+}
+

package/src/controller/param-binder.ts

@@ -0,0 +1,157 @@
+import type { Context } from '../core/context';
+import { getParamMetadata, ParamType, type ParamMetadata } from './decorators';
+import { Container } from '../di/container';
+import { SessionService } from '../session/service';
+import { SESSION_SERVICE_TOKEN } from '../session/types';
+
+/**
+ * 参数绑定器
+ * 根据装饰器元数据绑定参数
+ */
+export class ParamBinder {
+  /**
+   * 绑定参数
+   * @param target - 目标对象
+   * @param propertyKey - 属性键
+   * @param context - 请求上下文
+   * @param container - DI 容器（用于解析 Session）
+   * @returns 参数数组
+   */
+  public static async bind(
+    target: any,
+    propertyKey: string,
+    context: Context,
+    container?: Container,
+  ): Promise<unknown[]> {
+    const metadata = getParamMetadata(target, propertyKey);
+    const params: unknown[] = [];
+
+    // 按索引排序
+    metadata.sort((a, b) => a.index - b.index);
+
+    // 绑定参数
+    for (const meta of metadata) {
+      const value = await this.getValue(meta, context, container);
+      params[meta.index] = value;
+    }
+
+    // 确保参数数组是连续的（填充 undefined）
+    // 例如：如果只有 index 1 的参数，params 应该是 [undefined, value]
+    const maxIndex = metadata.length > 0 ? Math.max(...metadata.map((m) => m.index)) : -1;
+    for (let i = 0; i <= maxIndex; i++) {
+      if (!(i in params)) {
+        params[i] = undefined;
+      }
+    }
+
+    return params;
+  }
+
+  /**
+   * 获取参数值
+   * @param meta - 参数元数据
+   * @param context - 请求上下文
+   * @param container - DI 容器（用于解析 Session）
+   * @returns 参数值
+   */
+  private static async getValue(meta: ParamMetadata, context: Context, container?: Container): Promise<unknown> {
+    switch (meta.type) {
+      case ParamType.BODY:
+        return await this.getBodyValue(meta.key, context);
+      case ParamType.QUERY:
+        // Query 装饰器要求提供 key
+        if (!meta.key) {
+          throw new Error('@Query() decorator requires a key parameter');
+        }
+        return this.getQueryValue(meta.key, context);
+      case ParamType.PARAM:
+        // Param 装饰器要求提供 key
+        if (!meta.key) {
+          throw new Error('@Param() decorator requires a key parameter');
+        }
+        return this.getParamValue(meta.key, context);
+      case ParamType.HEADER:
+        // Header 装饰器要求提供 key
+        if (!meta.key) {
+          throw new Error('@Header() decorator requires a key parameter');
+        }
+        return this.getHeaderValue(meta.key, context);
+      case ParamType.SESSION:
+        // Session 装饰器需要 container
+        if (!container) {
+          throw new Error('@Session() decorator requires a Container instance');
+        }
+        // 从 Context 中获取 Session（由中间件设置）
+        const session = (context as unknown as { session?: unknown }).session;
+        if (session) {
+          return session;
+        }
+        // 如果没有 Session，尝试创建新 Session
+        try {
+          const sessionService = container.resolve<SessionService>(
+            SESSION_SERVICE_TOKEN,
+          );
+          if (sessionService) {
+            const newSession = await sessionService.create();
+            (context as unknown as { session: typeof newSession }).session =
+              newSession;
+            (context as unknown as { sessionId: string }).sessionId = newSession.id;
+            return newSession;
+          }
+        } catch {
+          // SessionService 未注册，返回 undefined
+        }
+        return undefined;
+      default:
+        return undefined;
+    }
+  }
+
+  /**
+   * 获取 Body 值
+   * @param key - 键（可选）
+   * @param context - 请求上下文
+   * @returns Body 值
+   */
+  private static async getBodyValue(key: string | undefined, context: Context): Promise<unknown> {
+    const body = await context.getBody();
+    if (!key) {
+      return body;
+    }
+    if (typeof body === 'object' && body !== null) {
+      return (body as Record<string, unknown>)[key];
+    }
+    return undefined;
+  }
+
+  /**
+   * 获取 Query 值
+   * @param key - 键
+   * @param context - 请求上下文
+   * @returns Query 值
+   */
+  private static getQueryValue(key: string, context: Context): string | null {
+    return context.getQuery(key);
+  }
+
+  /**
+   * 获取 Param 值
+   * @param key - 键
+   * @param context - 请求上下文
+   * @returns Param 值
+   */
+  private static getParamValue(key: string, context: Context): string | undefined {
+    return context.getParam(key);
+  }
+
+  /**
+   * 获取 Header 值
+   * @param key - 键
+   * @param context - 请求上下文
+   * @returns Header 值
+   */
+  private static getHeaderValue(key: string, context: Context): string | null {
+    return context.getHeader(key);
+  }
+}
+