wwjcloud/src/common/exception/exception.interface.ts

/**
 * 异常接口定义
 * 基于 NestJS 官方示例实现
 * 参考: https://docs.nestjs.cn/fundamentals/exception-filters
 * 对应 Java: 异常抽象
 */
export interface ExceptionInterface {
  /**
   * 处理异常
   * @param exception 异常对象
   * @param context 上下文
   * @returns 处理结果
   */
  handle(exception: any, context?: any): Promise<ExceptionResult>;

  /**
   * 记录异常
   * @param exception 异常对象
   * @param context 上下文
   */
  log(exception: any, context?: any): Promise<void>;

  /**
   * 格式化异常响应
   * @param exception 异常对象
   * @param context 上下文
   * @returns 格式化后的响应
   */
  format(exception: any, context?: any): ExceptionResponse;

  /**
   * 判断异常类型
   * @param exception 异常对象
   * @returns 异常类型
   */
  getType(exception: any): ExceptionType;

  /**
   * 获取异常严重程度
   * @param exception 异常对象
   * @returns 严重程度
   */
  getSeverity(exception: any): ExceptionSeverity;

  /**
   * 判断是否应该记录
   * @param exception 异常对象
   * @returns 是否应该记录
   */
  shouldLog(exception: any): boolean;

  /**
   * 判断是否应该上报
   * @param exception 异常对象
   * @returns 是否应该上报
   */
  shouldReport(exception: any): boolean;
}

/**
 * 异常处理结果
 */
export interface ExceptionResult {
  success: boolean;
  response: ExceptionResponse;
  logged: boolean;
  reported: boolean;
  handled: boolean;
}

/**
 * 异常响应
 */
export interface ExceptionResponse {
  statusCode: number;
  message: string;
  error: string;
  timestamp: string;
  path?: string;
  method?: string;
  traceId?: string;
  spanId?: string;
  correlationId?: string;
  details?: any;
  code?: string;
  type?: ExceptionType;
  severity?: ExceptionSeverity;
}

/**
 * 异常类型
 */
export enum ExceptionType {
  VALIDATION = 'validation',
  AUTHENTICATION = 'authentication',
  AUTHORIZATION = 'authorization',
  NOT_FOUND = 'not_found',
  CONFLICT = 'conflict',
  BAD_REQUEST = 'bad_request',
  INTERNAL_SERVER_ERROR = 'internal_server_error',
  SERVICE_UNAVAILABLE = 'service_unavailable',
  TIMEOUT = 'timeout',
  RATE_LIMIT = 'rate_limit',
  BUSINESS = 'business',
  SYSTEM = 'system',
  NETWORK = 'network',
  DATABASE = 'database',
  CACHE = 'cache',
  EXTERNAL_API = 'external_api',
  UNKNOWN = 'unknown',
}

/**
 * 异常严重程度
 */
export enum ExceptionSeverity {
  LOW = 'low',
  MEDIUM = 'medium',
  HIGH = 'high',
  CRITICAL = 'critical',
}

/**
 * 异常上下文
 */
export interface ExceptionContext {
  request?: {
    method: string;
    url: string;
    headers: Record<string, string>;
    body?: any;
    query?: Record<string, any>;
    params?: Record<string, any>;
    ip?: string;
    userAgent?: string;
    userId?: string;
    sessionId?: string;
  };
  response?: {
    statusCode: number;
    headers: Record<string, string>;
    body?: any;
  };
  user?: {
    id: string;
    username?: string;
    email?: string;
    role?: string;
    permissions?: string[];
  };
  environment?: {
    nodeEnv: string;
    version: string;
    hostname: string;
    pid: number;
  };
  trace?: {
    traceId: string;
    spanId: string;
    correlationId: string;
  };
  meta?: Record<string, any>;
}

/**
 * 异常配置
 */
export interface ExceptionConfig {
  enabled: boolean;
  logLevel: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
  reportLevel: 'error' | 'fatal';
  includeStackTrace: boolean;
  includeRequest: boolean;
  includeResponse: boolean;
  includeUser: boolean;
  includeEnvironment: boolean;
  sanitizeData: boolean;
  maxMessageLength: number;
  maxStackTraceLength: number;
  rateLimit: {
    enabled: boolean;
    maxRequests: number;
    windowMs: number;
  };
  reporting: {
    enabled: boolean;
    providers: string[];
    filters: string[];
  };
}

/**
 * 异常装饰器选项
 */
export interface ExceptionOptions {
  /**
   * 异常类型
   */
  type?: ExceptionType;

  /**
   * 严重程度
   */
  severity?: ExceptionSeverity;

  /**
   * 是否记录
   */
  log?: boolean;

  /**
   * 是否上报
   */
  report?: boolean;

  /**
   * 自定义消息
   */
  message?: string;

  /**
   * 状态码
   */
  statusCode?: number;

  /**
   * 错误码
   */
  code?: string;

  /**
   * 是否包含堆栈跟踪
   */
  includeStackTrace?: boolean;

  /**
   * 是否包含请求信息
   */
  includeRequest?: boolean;

  /**
   * 是否包含响应信息
   */
  includeResponse?: boolean;

  /**
   * 是否包含用户信息
   */
  includeUser?: boolean;

  /**
   * 是否包含环境信息
   */
  includeEnvironment?: boolean;

  /**
   * 是否清理敏感数据
   */
  sanitizeData?: boolean;

  /**
   * 元数据
   */
  meta?: Record<string, any>;
}

/**
 * 异常过滤器接口
 */
export interface ExceptionFilterInterface {
  /**
   * 判断是否应该处理该异常
   * @param exception 异常对象
   * @returns 是否应该处理
   */
  shouldHandle(exception: any): boolean;

  /**
   * 处理异常
   * @param exception 异常对象
   * @param context 上下文
   * @returns 处理结果
   */
  handle(exception: any, context?: any): Promise<ExceptionResult>;
}

/**
 * 异常上报接口
 */
export interface ExceptionReporterInterface {
  /**
   * 上报异常
   * @param exception 异常对象
   * @param context 上下文
   * @returns 上报结果
   */
  report(exception: any, context?: any): Promise<boolean>;

  /**
   * 批量上报异常
   * @param exceptions 异常数组
   * @param context 上下文
   * @returns 上报结果
   */
  reportBatch(
    exceptions: Array<{ exception: any; context?: any }>,
  ): Promise<boolean[]>;

  /**
   * 检查是否应该上报
   * @param exception 异常对象
   * @returns 是否应该上报
   */
  shouldReport(exception: any): boolean;
}

/**
 * 异常统计接口
 */
export interface ExceptionStatsInterface {
  /**
   * 记录异常统计
   * @param exception 异常对象
   * @param context 上下文
   */
  record(exception: any, context?: any): void;

  /**
   * 获取异常统计
   * @param timeRange 时间范围
   * @returns 统计信息
   */
  getStats(timeRange?: { start: Date; end: Date }): ExceptionStats;

  /**
   * 重置统计
   */
  reset(): void;
}

/**
 * 异常统计信息
 */
export interface ExceptionStats {
  total: number;
  byType: Record<ExceptionType, number>;
  bySeverity: Record<ExceptionSeverity, number>;
  byTime: Array<{ time: Date; count: number }>;
  topExceptions: Array<{ message: string; count: number; lastOccurred: Date }>;
  rate: number; // 异常率
  trend: 'increasing' | 'decreasing' | 'stable';
}