@dangao/bun-server 1.0.0 → 1.0.3

package/src/di/module-registry.ts

@@ -0,0 +1,188 @@
+import { ControllerRegistry } from '../controller/controller';
+import { Container } from './container';
+import { Lifecycle } from './types';
+import { getModuleMetadata, type ModuleClass, type ModuleProvider, type ProviderToken } from './module';
+import type { Constructor } from '@/core/types';
+import type { ApplicationExtension } from '../extensions/types';
+import type { Middleware } from '../middleware';
+
+interface ModuleRef {
+  moduleClass: ModuleClass;
+  metadata: ReturnType<typeof getModuleMetadata>;
+  container: Container;
+  controllersRegistered: boolean;
+  attachedParents: Set<Container>;
+  extensions: ApplicationExtension[];
+  middlewares: Middleware[];
+}
+
+export class ModuleRegistry {
+  private static instance: ModuleRegistry;
+  private readonly moduleRefs = new Map<ModuleClass, ModuleRef>();
+  private readonly processing = new Set<ModuleClass>();
+  private rootContainer?: Container;
+
+  public static getInstance(): ModuleRegistry {
+    if (!ModuleRegistry.instance) {
+      ModuleRegistry.instance = new ModuleRegistry();
+    }
+    return ModuleRegistry.instance;
+  }
+
+  public register(moduleClass: ModuleClass, parentContainer: Container): ModuleRef {
+    if (!this.rootContainer) {
+      this.rootContainer = parentContainer;
+    }
+    return this.processModule(moduleClass, parentContainer);
+  }
+
+  public getModuleRef(moduleClass: ModuleClass): ModuleRef | undefined {
+    return this.moduleRefs.get(moduleClass);
+  }
+
+  public clear(): void {
+    this.moduleRefs.clear();
+    this.processing.clear();
+    this.rootContainer = undefined;
+  }
+
+  private processModule(moduleClass: ModuleClass, parentContainer: Container): ModuleRef {
+    if (this.processing.has(moduleClass)) {
+      throw new Error(`Circular module dependency detected for ${moduleClass.name}`);
+    }
+    const moduleRef = this.getOrCreateModuleRef(moduleClass);
+    this.processing.add(moduleClass);
+    for (const imported of moduleRef.metadata.imports) {
+      this.processModule(imported, moduleRef.container);
+    }
+    this.processing.delete(moduleClass);
+    this.attachModuleToParent(moduleRef, parentContainer);
+    return moduleRef;
+  }
+
+  private getOrCreateModuleRef(moduleClass: ModuleClass): ModuleRef {
+    let ref = this.moduleRefs.get(moduleClass);
+    if (ref) {
+      return ref;
+    }
+    if (!this.rootContainer) {
+      throw new Error('ModuleRegistry is not initialized with a root container');
+    }
+    const metadata = getModuleMetadata(moduleClass);
+    const container = new Container({ parent: this.rootContainer });
+    this.registerProviders(container, metadata.providers);
+    ref = {
+      moduleClass,
+      metadata,
+      container,
+      controllersRegistered: false,
+      attachedParents: new Set<Container>(),
+      extensions: metadata.extensions ?? [],
+      middlewares: metadata.middlewares ?? [],
+    };
+    this.registerControllers(ref);
+    this.moduleRefs.set(moduleClass, ref);
+    return ref;
+  }
+
+  private registerProviders(container: Container, providers: ModuleProvider[]): void {
+    for (const provider of providers) {
+      if (typeof provider === 'function') {
+        if (!container.isRegistered(provider)) {
+          container.register(provider);
+        }
+        continue;
+      }
+
+      if ('useValue' in provider) {
+        container.registerInstance(provider.provide, provider.useValue);
+        continue;
+      }
+
+      if ('useFactory' in provider) {
+        container.register(provider.provide, {
+          lifecycle: provider.lifecycle ?? Lifecycle.Singleton,
+          factory: () => provider.useFactory(container),
+        });
+        continue;
+      }
+
+      if ('useClass' in provider) {
+        const token = provider.provide ?? provider.useClass;
+        container.register(token, {
+          lifecycle: provider.lifecycle ?? Lifecycle.Singleton,
+          implementation: provider.useClass,
+        });
+      }
+    }
+  }
+
+  private registerControllers(moduleRef: ModuleRef): void {
+    if (moduleRef.controllersRegistered) {
+      return;
+    }
+    const controllerRegistry = ControllerRegistry.getInstance();
+    for (const controller of moduleRef.metadata.controllers) {
+      controllerRegistry.register(controller, moduleRef.container);
+    }
+    moduleRef.controllersRegistered = true;
+  }
+
+  private attachModuleToParent(moduleRef: ModuleRef, parentContainer: Container): void {
+    if (moduleRef.attachedParents.has(parentContainer)) {
+      return;
+    }
+    moduleRef.attachedParents.add(parentContainer);
+    for (const exportedToken of moduleRef.metadata.exports) {
+      this.registerExport(parentContainer, moduleRef, exportedToken);
+    }
+    // 收集导入模块的扩展和中间件
+    for (const imported of moduleRef.metadata.imports) {
+      const importedRef = this.moduleRefs.get(imported);
+      if (importedRef) {
+        moduleRef.extensions.push(...importedRef.extensions);
+        moduleRef.middlewares.push(...importedRef.middlewares);
+      }
+    }
+  }
+
+  /**
+   * 获取模块的所有扩展（包括导入模块的扩展）
+   */
+  public getModuleExtensions(moduleClass: ModuleClass): ApplicationExtension[] {
+    const moduleRef = this.moduleRefs.get(moduleClass);
+    if (!moduleRef) {
+      return [];
+    }
+    return moduleRef.extensions;
+  }
+
+  /**
+   * 获取模块的所有中间件（包括导入模块的中间件）
+   */
+  public getModuleMiddlewares(moduleClass: ModuleClass): Middleware[] {
+    const moduleRef = this.moduleRefs.get(moduleClass);
+    if (!moduleRef) {
+      return [];
+    }
+    return moduleRef.middlewares;
+  }
+
+  private registerExport(parentContainer: Container, moduleRef: ModuleRef, token: ProviderToken): void {
+    if (!moduleRef.container.isRegistered(token)) {
+      throw new Error(
+        `Module ${moduleRef.moduleClass.name} cannot export ${
+          typeof token === 'function' ? token.name : String(token)
+        } because it is not registered`,
+      );
+    }
+    if (parentContainer.isRegistered(token)) {
+      return;
+    }
+    parentContainer.register(token as Constructor<unknown>, {
+      lifecycle: Lifecycle.Singleton,
+      factory: () => moduleRef.container.resolve(token as any),
+    });
+  }
+}
+

package/src/di/module.ts

@@ -0,0 +1,65 @@
+import 'reflect-metadata';
+
+import type { Constructor } from '@/core/types';
+import type { Container } from './container';
+import type { Lifecycle } from './types';
+import type { ApplicationExtension } from '../extensions/types';
+import type { Middleware } from '../middleware';
+
+export type ModuleClass<T = unknown> = Constructor<T>;
+export type ProviderToken = Constructor<unknown> | string | symbol;
+
+export interface ClassProvider {
+  provide?: ProviderToken;
+  useClass: Constructor<unknown>;
+  lifecycle?: Lifecycle;
+}
+
+export interface ValueProvider {
+  provide: ProviderToken;
+  useValue: unknown;
+}
+
+export interface FactoryProvider {
+  provide: ProviderToken;
+  useFactory: (container: Container) => unknown;
+  lifecycle?: Lifecycle;
+}
+
+export type ModuleProvider = Constructor<unknown> | ClassProvider | ValueProvider | FactoryProvider;
+
+export interface ModuleMetadata {
+  imports?: ModuleClass[];
+  controllers?: Constructor<unknown>[];
+  providers?: ModuleProvider[];
+  exports?: ProviderToken[];
+  /**
+   * 应用扩展列表
+   */
+  extensions?: ApplicationExtension[];
+  /**
+   * 中间件列表
+   */
+  middlewares?: Middleware[];
+}
+
+export const MODULE_METADATA_KEY = Symbol('@dangao/bun-server:module');
+
+export function Module(metadata: ModuleMetadata): ClassDecorator {
+  return (target) => {
+    Reflect.defineMetadata(MODULE_METADATA_KEY, metadata, target);
+  };
+}
+
+export function getModuleMetadata(moduleClass: ModuleClass): Required<Omit<ModuleMetadata, 'extensions' | 'middlewares'>> & Pick<ModuleMetadata, 'extensions' | 'middlewares'> {
+  const metadata = (Reflect.getMetadata(MODULE_METADATA_KEY, moduleClass) as ModuleMetadata | undefined) ?? {};
+  return {
+    imports: metadata.imports ?? [],
+    controllers: metadata.controllers ?? [],
+    providers: metadata.providers ?? [],
+    exports: metadata.exports ?? [],
+    extensions: metadata.extensions ?? [],
+    middlewares: metadata.middlewares ?? [],
+  };
+}
+

package/src/di/types.ts

@@ -0,0 +1,67 @@
+import type { Constructor } from '@/core/types'
+
+/**
+ * 依赖生命周期类型
+ */
+export enum Lifecycle {
+  /**
+   * 单例：整个应用生命周期中只有一个实例
+   */
+  Singleton = 'singleton',
+
+  /**
+   * 瞬态：每次请求都创建新实例
+   */
+  Transient = 'transient',
+
+  /**
+   * 作用域：在特定作用域内共享实例（未来扩展）
+   */
+  Scoped = 'scoped',
+}
+
+/**
+ * 提供者配置
+ */
+export interface ProviderConfig {
+  /**
+   * 生命周期
+   */
+  lifecycle?: Lifecycle;
+
+  /**
+   * 自定义工厂函数
+   */
+  factory?: () => unknown;
+
+  /**
+   * 提供者标识符（用于接口注入）
+   */
+  token?: string | symbol;
+
+  /**
+   * 实际实现类（当 token 为 string/symbol 时用于实例化）
+   */
+  implementation?: new (...args: unknown[]) => unknown;
+}
+
+/**
+ * 依赖元数据
+ */
+export interface DependencyMetadata {
+  /**
+   * 参数索引
+   */
+  index: number;
+
+  /**
+   * 依赖类型（构造函数）
+   */
+  type: Constructor<unknown> | string;
+
+  /**
+   * 可选的 token（用于接口注入）
+   */
+  token?: string | symbol;
+}
+

package/src/error/error-codes.ts

@@ -0,0 +1,222 @@
+/**
+ * 错误码定义
+ *
+ * 错误码命名规范：
+ * - 格式：模块_错误类型_具体错误
+ * - 使用大写字母和下划线
+ * - 模块前缀：AUTH（认证）、VALIDATION（验证）、DATABASE（数据库）、FILE（文件）、MIDDLEWARE（中间件）、OAUTH2（OAuth2）
+ * - 示例：AUTH_INVALID_TOKEN, VALIDATION_REQUIRED_FIELD, DATABASE_CONNECTION_FAILED
+ *
+ * 错误码分类：
+ * - 1000-1999: 通用错误
+ * - 2000-2999: 认证和授权错误
+ * - 3000-3999: 验证错误
+ * - 4000-4999: OAuth2 错误
+ * - 5000-5999: 数据库错误
+ * - 6000-6999: 文件操作错误
+ * - 7000-7999: 中间件错误
+ * - 8000-8999: 配置错误
+ */
+export enum ErrorCode {
+  // ========== 通用错误 (1000-1999) ==========
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+  INVALID_REQUEST = 'INVALID_REQUEST',
+  RESOURCE_NOT_FOUND = 'RESOURCE_NOT_FOUND',
+  METHOD_NOT_ALLOWED = 'METHOD_NOT_ALLOWED',
+  RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED',
+  SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE',
+  TIMEOUT = 'TIMEOUT',
+
+  // ========== 认证和授权错误 (2000-2999) ==========
+  AUTH_REQUIRED = 'AUTH_REQUIRED',
+  AUTH_INVALID_TOKEN = 'AUTH_INVALID_TOKEN',
+  AUTH_TOKEN_EXPIRED = 'AUTH_TOKEN_EXPIRED',
+  AUTH_INSUFFICIENT_PERMISSIONS = 'AUTH_INSUFFICIENT_PERMISSIONS',
+  AUTH_INVALID_CREDENTIALS = 'AUTH_INVALID_CREDENTIALS',
+  AUTH_ACCOUNT_LOCKED = 'AUTH_ACCOUNT_LOCKED',
+  AUTH_ACCOUNT_DISABLED = 'AUTH_ACCOUNT_DISABLED',
+
+  // ========== 验证错误 (3000-3999) ==========
+  VALIDATION_FAILED = 'VALIDATION_FAILED',
+  VALIDATION_REQUIRED_FIELD = 'VALIDATION_REQUIRED_FIELD',
+  VALIDATION_INVALID_FORMAT = 'VALIDATION_INVALID_FORMAT',
+  VALIDATION_OUT_OF_RANGE = 'VALIDATION_OUT_OF_RANGE',
+  VALIDATION_TYPE_MISMATCH = 'VALIDATION_TYPE_MISMATCH',
+  VALIDATION_CONSTRAINT_VIOLATION = 'VALIDATION_CONSTRAINT_VIOLATION',
+
+  // ========== OAuth2 错误 (4000-4999) ==========
+  OAUTH2_INVALID_CLIENT = 'OAUTH2_INVALID_CLIENT',
+  OAUTH2_INVALID_GRANT = 'OAUTH2_INVALID_GRANT',
+  OAUTH2_INVALID_SCOPE = 'OAUTH2_INVALID_SCOPE',
+  OAUTH2_INVALID_REDIRECT_URI = 'OAUTH2_INVALID_REDIRECT_URI',
+  OAUTH2_UNSUPPORTED_GRANT_TYPE = 'OAUTH2_UNSUPPORTED_GRANT_TYPE',
+  OAUTH2_ACCESS_DENIED = 'OAUTH2_ACCESS_DENIED',
+  OAUTH2_SERVER_ERROR = 'OAUTH2_SERVER_ERROR',
+
+  // ========== 数据库错误 (5000-5999) ==========
+  DATABASE_CONNECTION_FAILED = 'DATABASE_CONNECTION_FAILED',
+  DATABASE_QUERY_FAILED = 'DATABASE_QUERY_FAILED',
+  DATABASE_TRANSACTION_FAILED = 'DATABASE_TRANSACTION_FAILED',
+  DATABASE_CONSTRAINT_VIOLATION = 'DATABASE_CONSTRAINT_VIOLATION',
+  DATABASE_TIMEOUT = 'DATABASE_TIMEOUT',
+  DATABASE_POOL_EXHAUSTED = 'DATABASE_POOL_EXHAUSTED',
+  DATABASE_MIGRATION_FAILED = 'DATABASE_MIGRATION_FAILED',
+
+  // ========== 文件操作错误 (6000-6999) ==========
+  FILE_NOT_FOUND = 'FILE_NOT_FOUND',
+  FILE_UPLOAD_FAILED = 'FILE_UPLOAD_FAILED',
+  FILE_DOWNLOAD_FAILED = 'FILE_DOWNLOAD_FAILED',
+  FILE_SIZE_EXCEEDED = 'FILE_SIZE_EXCEEDED',
+  FILE_TYPE_NOT_ALLOWED = 'FILE_TYPE_NOT_ALLOWED',
+  FILE_ACCESS_DENIED = 'FILE_ACCESS_DENIED',
+  FILE_PATH_TRAVERSAL = 'FILE_PATH_TRAVERSAL',
+
+  // ========== 中间件错误 (7000-7999) ==========
+  MIDDLEWARE_EXECUTION_FAILED = 'MIDDLEWARE_EXECUTION_FAILED',
+  MIDDLEWARE_TIMEOUT = 'MIDDLEWARE_TIMEOUT',
+  CORS_NOT_ALLOWED = 'CORS_NOT_ALLOWED',
+
+  // ========== 配置错误 (8000-8999) ==========
+  CONFIG_INVALID = 'CONFIG_INVALID',
+  CONFIG_MISSING = 'CONFIG_MISSING',
+  CONFIG_VALIDATION_FAILED = 'CONFIG_VALIDATION_FAILED',
+}
+
+/**
+ * 错误码到 HTTP 状态码的映射
+ */
+export const ERROR_CODE_TO_STATUS: Record<ErrorCode, number> = {
+  // 通用错误
+  [ErrorCode.INTERNAL_ERROR]: 500,
+  [ErrorCode.INVALID_REQUEST]: 400,
+  [ErrorCode.RESOURCE_NOT_FOUND]: 404,
+  [ErrorCode.METHOD_NOT_ALLOWED]: 405,
+  [ErrorCode.RATE_LIMIT_EXCEEDED]: 429,
+  [ErrorCode.SERVICE_UNAVAILABLE]: 503,
+  [ErrorCode.TIMEOUT]: 408,
+
+  // 认证和授权错误
+  [ErrorCode.AUTH_REQUIRED]: 401,
+  [ErrorCode.AUTH_INVALID_TOKEN]: 401,
+  [ErrorCode.AUTH_TOKEN_EXPIRED]: 401,
+  [ErrorCode.AUTH_INSUFFICIENT_PERMISSIONS]: 403,
+  [ErrorCode.AUTH_INVALID_CREDENTIALS]: 401,
+  [ErrorCode.AUTH_ACCOUNT_LOCKED]: 423,
+  [ErrorCode.AUTH_ACCOUNT_DISABLED]: 403,
+
+  // 验证错误
+  [ErrorCode.VALIDATION_FAILED]: 400,
+  [ErrorCode.VALIDATION_REQUIRED_FIELD]: 400,
+  [ErrorCode.VALIDATION_INVALID_FORMAT]: 400,
+  [ErrorCode.VALIDATION_OUT_OF_RANGE]: 400,
+  [ErrorCode.VALIDATION_TYPE_MISMATCH]: 400,
+  [ErrorCode.VALIDATION_CONSTRAINT_VIOLATION]: 400,
+
+  // OAuth2 错误
+  [ErrorCode.OAUTH2_INVALID_CLIENT]: 400,
+  [ErrorCode.OAUTH2_INVALID_GRANT]: 400,
+  [ErrorCode.OAUTH2_INVALID_SCOPE]: 400,
+  [ErrorCode.OAUTH2_INVALID_REDIRECT_URI]: 400,
+  [ErrorCode.OAUTH2_UNSUPPORTED_GRANT_TYPE]: 400,
+  [ErrorCode.OAUTH2_ACCESS_DENIED]: 403,
+  [ErrorCode.OAUTH2_SERVER_ERROR]: 500,
+
+  // 数据库错误
+  [ErrorCode.DATABASE_CONNECTION_FAILED]: 503,
+  [ErrorCode.DATABASE_QUERY_FAILED]: 500,
+  [ErrorCode.DATABASE_TRANSACTION_FAILED]: 500,
+  [ErrorCode.DATABASE_CONSTRAINT_VIOLATION]: 409,
+  [ErrorCode.DATABASE_TIMEOUT]: 504,
+  [ErrorCode.DATABASE_POOL_EXHAUSTED]: 503,
+  [ErrorCode.DATABASE_MIGRATION_FAILED]: 500,
+
+  // 文件操作错误
+  [ErrorCode.FILE_NOT_FOUND]: 404,
+  [ErrorCode.FILE_UPLOAD_FAILED]: 500,
+  [ErrorCode.FILE_DOWNLOAD_FAILED]: 500,
+  [ErrorCode.FILE_SIZE_EXCEEDED]: 413,
+  [ErrorCode.FILE_TYPE_NOT_ALLOWED]: 415,
+  [ErrorCode.FILE_ACCESS_DENIED]: 403,
+  [ErrorCode.FILE_PATH_TRAVERSAL]: 400,
+
+  // 中间件错误
+  [ErrorCode.MIDDLEWARE_EXECUTION_FAILED]: 500,
+  [ErrorCode.MIDDLEWARE_TIMEOUT]: 504,
+  [ErrorCode.CORS_NOT_ALLOWED]: 403,
+
+  // 配置错误
+  [ErrorCode.CONFIG_INVALID]: 500,
+  [ErrorCode.CONFIG_MISSING]: 500,
+  [ErrorCode.CONFIG_VALIDATION_FAILED]: 500,
+};
+
+/**
+ * 错误码的默认消息（英文）
+ * 支持消息模板，使用 {key} 作为占位符
+ * 例如：'Resource {resource} not found'，可以通过参数替换 {resource}
+ */
+export const ERROR_CODE_MESSAGES: Record<ErrorCode, string> = {
+  // 通用错误
+  [ErrorCode.INTERNAL_ERROR]: 'Internal Server Error',
+  [ErrorCode.INVALID_REQUEST]: 'Invalid Request',
+  [ErrorCode.RESOURCE_NOT_FOUND]: 'Resource Not Found',
+  [ErrorCode.METHOD_NOT_ALLOWED]: 'Method Not Allowed',
+  [ErrorCode.RATE_LIMIT_EXCEEDED]: 'Rate Limit Exceeded',
+  [ErrorCode.SERVICE_UNAVAILABLE]: 'Service Unavailable',
+  [ErrorCode.TIMEOUT]: 'Request Timeout',
+
+  // 认证和授权错误
+  [ErrorCode.AUTH_REQUIRED]: 'Authentication Required',
+  [ErrorCode.AUTH_INVALID_TOKEN]: 'Invalid Authentication Token',
+  [ErrorCode.AUTH_TOKEN_EXPIRED]: 'Authentication Token Expired',
+  [ErrorCode.AUTH_INSUFFICIENT_PERMISSIONS]: 'Insufficient Permissions',
+  [ErrorCode.AUTH_INVALID_CREDENTIALS]: 'Invalid Credentials',
+  [ErrorCode.AUTH_ACCOUNT_LOCKED]: 'Account Locked',
+  [ErrorCode.AUTH_ACCOUNT_DISABLED]: 'Account Disabled',
+
+  // 验证错误
+  [ErrorCode.VALIDATION_FAILED]: 'Validation Failed',
+  [ErrorCode.VALIDATION_REQUIRED_FIELD]: 'Required Field Missing',
+  [ErrorCode.VALIDATION_INVALID_FORMAT]: 'Invalid Format',
+  [ErrorCode.VALIDATION_OUT_OF_RANGE]: 'Value Out of Range',
+  [ErrorCode.VALIDATION_TYPE_MISMATCH]: 'Type Mismatch',
+  [ErrorCode.VALIDATION_CONSTRAINT_VIOLATION]: 'Constraint Violation',
+
+  // OAuth2 错误
+  [ErrorCode.OAUTH2_INVALID_CLIENT]: 'Invalid Client',
+  [ErrorCode.OAUTH2_INVALID_GRANT]: 'Invalid Grant',
+  [ErrorCode.OAUTH2_INVALID_SCOPE]: 'Invalid Scope',
+  [ErrorCode.OAUTH2_INVALID_REDIRECT_URI]: 'Invalid Redirect URI',
+  [ErrorCode.OAUTH2_UNSUPPORTED_GRANT_TYPE]: 'Unsupported Grant Type',
+  [ErrorCode.OAUTH2_ACCESS_DENIED]: 'Access Denied',
+  [ErrorCode.OAUTH2_SERVER_ERROR]: 'OAuth2 Server Error',
+
+  // 数据库错误
+  [ErrorCode.DATABASE_CONNECTION_FAILED]: 'Database Connection Failed',
+  [ErrorCode.DATABASE_QUERY_FAILED]: 'Database Query Failed',
+  [ErrorCode.DATABASE_TRANSACTION_FAILED]: 'Database Transaction Failed',
+  [ErrorCode.DATABASE_CONSTRAINT_VIOLATION]: 'Database Constraint Violation',
+  [ErrorCode.DATABASE_TIMEOUT]: 'Database Timeout',
+  [ErrorCode.DATABASE_POOL_EXHAUSTED]: 'Database Connection Pool Exhausted',
+  [ErrorCode.DATABASE_MIGRATION_FAILED]: 'Database Migration Failed',
+
+  // 文件操作错误
+  [ErrorCode.FILE_NOT_FOUND]: 'File Not Found',
+  [ErrorCode.FILE_UPLOAD_FAILED]: 'File Upload Failed',
+  [ErrorCode.FILE_DOWNLOAD_FAILED]: 'File Download Failed',
+  [ErrorCode.FILE_SIZE_EXCEEDED]: 'File Size Exceeded',
+  [ErrorCode.FILE_TYPE_NOT_ALLOWED]: 'File Type Not Allowed',
+  [ErrorCode.FILE_ACCESS_DENIED]: 'File Access Denied',
+  [ErrorCode.FILE_PATH_TRAVERSAL]: 'Path Traversal Detected',
+
+  // 中间件错误
+  [ErrorCode.MIDDLEWARE_EXECUTION_FAILED]: 'Middleware Execution Failed',
+  [ErrorCode.MIDDLEWARE_TIMEOUT]: 'Middleware Timeout',
+  [ErrorCode.CORS_NOT_ALLOWED]: 'CORS Not Allowed',
+
+  // 配置错误
+  [ErrorCode.CONFIG_INVALID]: 'Invalid Configuration',
+  [ErrorCode.CONFIG_MISSING]: 'Missing Configuration',
+  [ErrorCode.CONFIG_VALIDATION_FAILED]: 'Configuration Validation Failed',
+};
+

package/src/error/filter.ts

@@ -0,0 +1,43 @@
+import type { Context } from '../core/context';
+
+export interface ExceptionFilter {
+  /**
+   * 捕获异常并返回 Response
+   * 如果返回 undefined，则继续交给下一个过滤器
+   */
+  catch(error: unknown, context: Context): Response | Promise<Response> | undefined;
+}
+
+export class ExceptionFilterRegistry {
+  private static instance: ExceptionFilterRegistry;
+  private readonly filters: ExceptionFilter[] = [];
+
+  private constructor() {}
+
+  public static getInstance(): ExceptionFilterRegistry {
+    if (!ExceptionFilterRegistry.instance) {
+      ExceptionFilterRegistry.instance = new ExceptionFilterRegistry();
+    }
+    return ExceptionFilterRegistry.instance;
+  }
+
+  public register(filter: ExceptionFilter): void {
+    this.filters.push(filter);
+  }
+
+  public clear(): void {
+    this.filters.length = 0;
+  }
+
+  public async execute(error: unknown, context: Context): Promise<Response | undefined> {
+    for (const filter of this.filters) {
+      const result = await filter.catch(error, context);
+      if (result) {
+        return result;
+      }
+    }
+    return undefined;
+  }
+}
+
+

package/src/error/handler.ts

@@ -0,0 +1,66 @@
+import type { Context } from '../core/context';
+import { HttpException } from './http-exception';
+import { ExceptionFilterRegistry } from './filter';
+import { ValidationError } from '../validation';
+import { ErrorMessageI18n } from './i18n';
+
+/**
+ * 全局错误处理
+ */
+export async function handleError(error: unknown, context: Context): Promise<Response> {
+  const registry = ExceptionFilterRegistry.getInstance();
+  const filterResponse = await registry.execute(error, context);
+  if (filterResponse) {
+    return filterResponse;
+  }
+
+  if (error instanceof HttpException) {
+    context.setStatus(error.status);
+
+    // 如果异常有错误码，尝试国际化消息
+    let errorMessage = error.message;
+    if (error.code) {
+      const acceptLanguage = context.getHeader('accept-language');
+      const language = ErrorMessageI18n.parseLanguageFromHeader(acceptLanguage);
+      // 如果提供了消息模板参数，使用参数替换占位符
+      errorMessage = ErrorMessageI18n.getMessage(
+        error.code,
+        language,
+        error.messageParams,
+      );
+    }
+
+    const responseBody: Record<string, unknown> = {
+      error: errorMessage,
+    };
+
+    // 只有当错误码存在时才添加 code 字段
+    if (error.code) {
+      responseBody.code = error.code;
+    }
+
+    if (error.details !== undefined) {
+      responseBody.details = error.details;
+    }
+
+    return context.createResponse(responseBody);
+  }
+
+  if (error instanceof ValidationError) {
+    context.setStatus(400);
+    return context.createResponse({
+      error: error.message,
+      code: 'VALIDATION_FAILED',
+      issues: error.issues,
+    });
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+  context.setStatus(500);
+  return context.createResponse({
+    error: 'Internal Server Error',
+    details: process.env.NODE_ENV === 'production' ? undefined : message,
+  });
+}
+
+