multi-lane-manager/src/types.ts

Nacos 泳道管理与请求路由组件

import type { H3Event } from "h3";
import type { LogObject } from "consola";
import type { Consola } from "consola";

/**
 * 服务实例信息
 * 定义了服务实例的基本信息，包括 IP、端口、服务名等
 */
export interface ServiceInstanceInfo {
  ip: string;                      // 实例 IP 地址
  port: number;                    // 实例端口
  serviceName: string;             // 服务名称
  clusterName: string;             // 集群名称，通常是泳道 ID
  ephemeral: boolean;              // 是否为临时实例
  metadata: Record<string, any>;   // 实例元数据，包含泳道 ID 等信息
  status: "UP" | "DOWN" | "UNKNOWN"; // 实例状态
  lastHeartbeat: number | string;  // 最后心跳时间
  healthy?: boolean;               // 是否健康
  version?: string;                // 实例版本
}

/**
 * 泳道信息
 * 定义了泳道的基本信息，包括泳道 ID 和实例列表
 */
export interface LaneInfo {
  id: string;                      // 泳道 ID
  instances: ServiceInstanceInfo[]; // 泳道中的实例列表
}

/**
 * 请求规则
 * 定义了请求路由规则，用于将请求路由到指定泳道
 */
export interface RequestRule {
  path: string;                    // 请求路径
  method?: string;                 // 请求方法，如 GET、POST 等
  targetLane: string;              // 目标泳道 ID
}

/**
 * 请求日志
 * 定义了请求日志的结构，用于记录请求处理情况
 */
export interface RequestLog {
  traceId: string;                 // 请求跟踪 ID
  laneId: string;                  // 泳道 ID
  path: string;                    // 请求路径
  method: string;                  // 请求方法
  statusCode: number;              // 响应状态码
  instance: ServiceInstanceInfo;   // 处理请求的实例
  error?: Error;                   // 错误信息（如果有）
  timestamp: number | string;      // 请求时间戳
}

/**
 * 泳道管理器配置
 * 定义了泳道管理器的配置选项
 */
export interface LaneManagerOptions {
  serverAddr: string;              // Nacos 服务器地址
  serverPort: number;              // Nacos 服务器端口
  namespace: string;               // Nacos 命名空间
  serviceName?: string;            // 服务名称
  hostname?: string;               // 主机名
  port?: string | number;          // 服务端口
  logger?: any;                    // 日志记录器
  heartbeatInterval?: number;      // 心跳间隔（毫秒）
  heartbeatTimeout?: number;       // 心跳超时（毫秒）
  retryTimes?: number;             // 重试次数
  version?: string;                // 版本
  enabled?: boolean;               // 是否启用
}

/**
 * 泳道管理器事件
 * 定义了泳道管理器的事件回调函数
 */
export interface LaneManagerEvents {
  onRegistered?: (instance: ServiceInstanceInfo) => void;  // 注册成功回调
  onDeregistered?: (instance: ServiceInstanceInfo) => void; // 注销成功回调
  onHeartbeat?: (instance: ServiceInstanceInfo) => void;   // 心跳成功回调
  onError?: (error: Error) => void;                        // 错误回调
  onRequest?: (log: RequestLog) => void;                   // 请求处理回调
}

/**
 * 泳道管理器
 * 定义了泳道管理器的接口，包括注册、注销、获取实例等方法
 */
export interface LaneManager {
  register(instance: ServiceInstanceInfo): Promise<boolean>;  // 注册服务实例
  deregister(): Promise<boolean>;                            // 注销服务实例
  close(): Promise<void>;                                    // 关闭管理器
  isRegistered(): boolean;                                   // 检查是否已注册
  getClient(): any;                                          // 获取 Nacos 客户端
  getCurrentInstance(): ServiceInstanceInfo | null;          // 获取当前实例
  getServiceInstance(laneId: string): Promise<ServiceInstanceInfo | null>; // 获取指定泳道的实例
  getAllLanes(): Promise<LaneInfo[]>;                        // 获取所有泳道信息
  getNacosStatus(): Promise<any>;                            // 获取 Nacos 状态
  logRequest(log: RequestLog): void;                         // 记录请求日志
  logError(log: RequestLog): void;                           // 记录错误日志
}

/**
 * 模块选项
 * 定义了模块的配置选项
 */
export interface ModuleOptions {
  enabled: boolean;                // 是否启用
  autoRegister: boolean;           // 是否自动注册
  rules: RequestRule[];            // 请求路由规则
  serverAddr: string;              // Nacos 服务器地址
  serverPort: number;              // Nacos 服务器端口
  namespace: string;               // Nacos 命名空间
  heartbeatInterval: number;       // 心跳间隔（毫秒）
  heartbeatTimeout: number;        // 心跳超时（毫秒）
  retryTimes: number;              // 重试次数
}

/**
 * 扩展 Nuxt 类型
 * 将模块选项添加到 Nuxt 配置中
 */
declare module "nuxt" {
  interface NuxtConfig {
    multiLaneManager?: Partial<ModuleOptions>;
  }
}

/**
 * 扩展 H3Event 上下文
 * 添加泳道管理器相关的上下文信息
 */
declare module "h3" {
  interface H3EventContext {
    laneManager?: LaneManager;     // 泳道管理器实例
    traceId?: string;              // 请求跟踪 ID
    laneInfo?: {                   // 泳道信息
      id: string;                  // 泳道 ID
      traceId: string;             // 请求跟踪 ID
      timestamp: string | number;  // 时间戳
    };
    runtimeConfig?: {              // 运行时配置
      public?: {
        multiLaneManager?: {
          enabled: boolean;        // 是否启用
          rules: RequestRule[];    // 请求路由规则
        };
      };
    };
    // 泳道管理器处理标记
    _laneManagerHandled?: boolean;    // 是否已被泳道管理器处理
    _laneManagerProcessing?: boolean; // 是否正在被泳道管理器处理
  }
}

/**
 * 扩展 Nuxt Schema
 * 将模块选项添加到 Nuxt 配置和选项中
 */
declare module "@nuxt/schema" {
  interface NuxtConfig {
    multiLaneManager?: Partial<ModuleOptions>;
  }
  interface NuxtOptions {
    multiLaneManager?: Partial<ModuleOptions>;
  }
}

/**
 * 扩展 Nitropack
 * 将模块选项添加到 Nitro 运行时配置中
 */
declare module "nitropack" {
  interface NitroRuntimeConfig {
    multiLaneManager?: Partial<ModuleOptions>;
  }
}

// 导出其他模块的类型
export type * from "h3";
export * from "@nuxt/schema";
export * from "nitropack";