@nest-omni/core 4.1.3-2 → 4.1.3-20

package/http-client/services/circuit-breaker.service.js

@@ -5,6 +5,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -18,32 +21,96 @@ var HttpCircuitBreakerService_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpCircuitBreakerService = void 0;
 const common_1 = require("@nestjs/common");
+/**
+ * 熔断器状态
+ */
 var CircuitBreakerState;
 (function (CircuitBreakerState) {
     CircuitBreakerState["CLOSED"] = "CLOSED";
     CircuitBreakerState["OPEN"] = "OPEN";
     CircuitBreakerState["HALF_OPEN"] = "HALF_OPEN";
 })(CircuitBreakerState || (CircuitBreakerState = {}));
+/**
+ * 熔断器服务
+ * 基于Spring Cloud CircuitBreaker的设计理念
+ */
 let HttpCircuitBreakerService = HttpCircuitBreakerService_1 = class HttpCircuitBreakerService {
     constructor() {
         this.logger = new common_1.Logger(HttpCircuitBreakerService_1.name);
         this.circuitBreakers = new Map();
+        /** 默认清理配置 */
+        this.cleanupConfig = {
+            maxIdleTimeMs: 30 * 60 * 1000, // 30分钟
+            cleanupIntervalMs: 5 * 60 * 1000, // 5分钟
+            maxSize: 1000, // 最多1000个circuit breaker
+        };
+        // 启动定期清理任务
+        this.startCleanupTask();
     }
+    onModuleDestroy() {
+        // 清理定时器
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+        }
+    }
+    /**
+     * 获取或创建熔断器
+     */
     getCircuitBreaker(key, config) {
-        if (!this.circuitBreakers.has(key)) {
-            this.circuitBreakers.set(key, new CircuitBreaker(key, config, this.logger));
+        let circuitBreaker = this.circuitBreakers.get(key);
+        if (!circuitBreaker) {
+            this.logger.debug(`Creating new circuit breaker with key: ${key}`);
+            circuitBreaker = new CircuitBreaker(key, config, this.logger);
+            this.circuitBreakers.set(key, circuitBreaker);
+            // 检查是否超过最大数量，如果是则触发LRU清理
+            if (this.circuitBreakers.size > this.cleanupConfig.maxSize) {
+                this.cleanupLRU();
+            }
         }
-        return this.circuitBreakers.get(key);
+        else {
+            this.logger.debug(`Reusing existing circuit breaker with key: ${key}`);
+            // 更新最后访问时间
+            circuitBreaker.updateLastAccessTime();
+        }
+        return circuitBreaker;
     }
-    executeWithCircuitBreaker(key, requestFn, config) {
+    /**
+     * 执行带熔断保护的请求
+     */
+    executeWithCircuitBreaker(key, requestFn, config, onStateChange) {
         return __awaiter(this, void 0, void 0, function* () {
             const circuitBreaker = this.getCircuitBreaker(key, config);
-            return circuitBreaker.execute(requestFn);
+            return circuitBreaker.execute(requestFn, onStateChange);
         });
     }
+    /**
+     * 获取熔断器当前状态
+     */
+    getCircuitBreakerState(key) {
+        // Log all current circuit breaker keys for debugging
+        this.logger.debug(`Looking for circuit breaker key: ${key}. Available keys: [${Array.from(this.circuitBreakers.keys()).join(', ')}]`);
+        const circuitBreaker = this.circuitBreakers.get(key);
+        if (!circuitBreaker) {
+            this.logger.debug(`Circuit breaker not found for key: ${key}`);
+            return undefined;
+        }
+        const state = circuitBreaker.getState();
+        if (!state) {
+            this.logger.debug(`Circuit breaker getState() returned undefined for key: ${key}`);
+            return undefined;
+        }
+        this.logger.debug(`Circuit breaker state for ${key}: ${state.state}`);
+        return state.state;
+    }
+    /**
+     * 重置所有熔断器
+     */
     resetAll() {
         this.circuitBreakers.forEach((cb) => cb.reset());
     }
+    /**
+     * 获取所有熔断器状态
+     */
     getAllStates() {
         const states = {};
         this.circuitBreakers.forEach((cb, key) => {
@@ -51,11 +118,115 @@ let HttpCircuitBreakerService = HttpCircuitBreakerService_1 = class HttpCircuitB
         });
         return states;
     }
+    /**
+     * 获取Circuit Breaker统计信息
+     */
+    getStats() {
+        const stats = {
+            total: this.circuitBreakers.size,
+            byState: {
+                CLOSED: 0,
+                OPEN: 0,
+                HALF_OPEN: 0,
+            },
+        };
+        this.circuitBreakers.forEach((cb) => {
+            const state = cb.getState();
+            if (state && state.state) {
+                stats.byState[state.state]++;
+            }
+        });
+        return stats;
+    }
+    /**
+     * 清理空闲的Circuit Breaker
+     * 清理超过最大空闲时间的Circuit Breaker
+     */
+    cleanupIdle() {
+        const now = Date.now();
+        const keysToDelete = [];
+        this.circuitBreakers.forEach((cb, key) => {
+            const lastAccess = cb.getLastAccessTime();
+            if (now - lastAccess > this.cleanupConfig.maxIdleTimeMs) {
+                keysToDelete.push(key);
+            }
+        });
+        keysToDelete.forEach((key) => {
+            this.circuitBreakers.delete(key);
+            this.logger.debug(`Removed idle circuit breaker: ${key}`);
+        });
+        if (keysToDelete.length > 0) {
+            this.logger.log(`Cleaned up ${keysToDelete.length} idle circuit breaker(s)`);
+        }
+        return keysToDelete.length;
+    }
+    /**
+     * 基于LRU策略清理Circuit Breaker
+     * 删除最久未访问的Circuit Breaker直到数量降到maxSize以下
+     */
+    cleanupLRU() {
+        const entries = Array.from(this.circuitBreakers.entries());
+        // 按最后访问时间排序（最老的在前）
+        entries.sort((a, b) => {
+            return a[1].getLastAccessTime() - b[1].getLastAccessTime();
+        });
+        // 计算需要删除的数量
+        const toDelete = entries.slice(0, entries.length - this.cleanupConfig.maxSize);
+        toDelete.forEach(([key]) => {
+            this.circuitBreakers.delete(key);
+            this.logger.debug(`Removed LRU circuit breaker: ${key}`);
+        });
+        if (toDelete.length > 0) {
+            this.logger.warn(`LRU cleanup: removed ${toDelete.length} circuit breaker(s) to maintain max size of ${this.cleanupConfig.maxSize}`);
+        }
+    }
+    /**
+     * 启动定期清理任务
+     */
+    startCleanupTask() {
+        this.cleanupTimer = setInterval(() => {
+            try {
+                this.cleanupIdle();
+            }
+            catch (error) {
+                this.logger.error('Error during circuit breaker cleanup', error);
+            }
+        }, this.cleanupConfig.cleanupIntervalMs);
+        this.logger.log(`Circuit breaker cleanup task started (interval: ${this.cleanupConfig.cleanupIntervalMs}ms, maxIdleTime: ${this.cleanupConfig.maxIdleTimeMs}ms)`);
+    }
+    /**
+     * 手动触发清理（用于测试）
+     */
+    manualCleanup() {
+        return this.cleanupIdle();
+    }
+    /**
+     * 设置清理配置
+     */
+    setCleanupConfig(config) {
+        Object.assign(this.cleanupConfig, config);
+        // 重启清理任务
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+        }
+        this.startCleanupTask();
+        this.logger.log(`Circuit breaker cleanup config updated: ${JSON.stringify(this.cleanupConfig)}`);
+    }
+    /**
+     * 获取清理配置
+     */
+    getCleanupConfig() {
+        return Object.assign({}, this.cleanupConfig);
+    }
 };
 exports.HttpCircuitBreakerService = HttpCircuitBreakerService;
 exports.HttpCircuitBreakerService = HttpCircuitBreakerService = HttpCircuitBreakerService_1 = __decorate([
-    (0, common_1.Injectable)()
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [])
 ], HttpCircuitBreakerService);
+/**
+ * 熔断器类
+ */
 class CircuitBreaker {
     constructor(key, config, logger) {
         this.key = key;
@@ -68,10 +239,29 @@ class CircuitBreaker {
         this.nextAttemptTime = 0;
         this.requestCount = 0;
         this.windowStartTime = Date.now();
+        this.lastAccessTime = Date.now(); // 添加最后访问时间跟踪
     }
-    execute(requestFn) {
+    /**
+     * 更新最后访问时间
+     */
+    updateLastAccessTime() {
+        this.lastAccessTime = Date.now();
+    }
+    /**
+     * 获取最后访问时间
+     */
+    getLastAccessTime() {
+        return this.lastAccessTime;
+    }
+    /**
+     * 执行请求
+     */
+    execute(requestFn, onStateChange) {
         return __awaiter(this, void 0, void 0, function* () {
+            // 保存状态变化回调
+            this.onStateChange = onStateChange;
             const currentTime = Date.now();
+            // 检查是否需要重置监控窗口
             if (currentTime - this.windowStartTime > this.config.monitoringPeriodMs) {
                 this.resetMonitoringWindow();
             }
@@ -87,6 +277,7 @@ class CircuitBreaker {
                     break;
                 case CircuitBreakerState.CLOSED:
                 default:
+                    // 正常状态，继续执行
                     break;
             }
             this.requestCount++;
@@ -101,10 +292,16 @@ class CircuitBreaker {
             }
         });
     }
+    /**
+     * 重置熔断器
+     */
     reset() {
         this.transitionToClosed();
         this.resetMonitoringWindow();
     }
+    /**
+     * 获取熔断器状态
+     */
     getState() {
         return {
             state: this.state,
@@ -117,6 +314,9 @@ class CircuitBreaker {
             config: this.config,
         };
     }
+    /**
+     * 处理成功请求
+     */
     onSuccess() {
         this.failureCount = 0;
         switch (this.state) {
@@ -128,9 +328,13 @@ class CircuitBreaker {
                 break;
             case CircuitBreakerState.CLOSED:
             default:
+                // 保持关闭状态
                 break;
         }
     }
+    /**
+     * 处理失败请求
+     */
     onFailure() {
         this.failureCount++;
         this.lastFailureTime = Date.now();
@@ -148,29 +352,55 @@ class CircuitBreaker {
                 break;
         }
     }
+    /**
+     * 转换到关闭状态
+     */
     transitionToClosed() {
         if (this.state !== CircuitBreakerState.CLOSED) {
             this.logger.log(`Circuit breaker ${this.key} transitioned to CLOSED`);
             this.state = CircuitBreakerState.CLOSED;
             this.failureCount = 0;
             this.successCount = 0;
+            // 通知状态变化
+            this.notifyStateChange(CircuitBreakerState.CLOSED);
         }
     }
+    /**
+     * 转换到开启状态
+     */
     transitionToOpen() {
         if (this.state !== CircuitBreakerState.OPEN) {
             this.logger.warn(`Circuit breaker ${this.key} transitioned to OPEN due to ${this.failureCount} failures`);
             this.state = CircuitBreakerState.OPEN;
             this.nextAttemptTime = Date.now() + this.config.recoveryTimeoutMs;
             this.successCount = 0;
+            // 通知状态变化
+            this.notifyStateChange(CircuitBreakerState.OPEN);
         }
     }
+    /**
+     * 转换到半开状态
+     */
     transitionToHalfOpen() {
         if (this.state !== CircuitBreakerState.HALF_OPEN) {
             this.logger.log(`Circuit breaker ${this.key} transitioned to HALF_OPEN`);
             this.state = CircuitBreakerState.HALF_OPEN;
             this.successCount = 0;
+            // 通知状态变化
+            this.notifyStateChange(CircuitBreakerState.HALF_OPEN);
+        }
+    }
+    /**
+     * 通知状态变化
+     */
+    notifyStateChange(state) {
+        if (this.onStateChange) {
+            this.onStateChange(state);
         }
     }
+    /**
+     * 重置监控窗口
+     */
     resetMonitoringWindow() {
         this.windowStartTime = Date.now();
         this.requestCount = 0;

package/http-client/services/http-client.service.d.ts

@@ -1,8 +1,8 @@
 import { AxiosRequestConfig, AxiosResponse } from 'axios';
 import { HttpClientConfig } from '../interfaces/http-client-config.interface';
+import { AuthType, ApiKeyConfig, BasicAuthConfig, BearerTokenConfig, CustomAuthConfig, OAuth2Config } from '../interfaces/api-client-config.interface';
 import { HttpCircuitBreakerService } from './circuit-breaker.service';
 import { HttpLoggingService } from './logging.service';
-import { HttpCacheService } from './cache.service';
 import { RedisLockService } from '../../redis-lock/redis-lock.service';
 interface ExtendedAxiosRequestConfig extends AxiosRequestConfig {
     metadata?: {
@@ -11,32 +11,106 @@ interface ExtendedAxiosRequestConfig extends AxiosRequestConfig {
         [key: string]: any;
     };
 }
+/**
+ * 认证配置接口
+ */
+interface AuthConfig {
+    type: AuthType;
+    config?: ApiKeyConfig | BasicAuthConfig | BearerTokenConfig | OAuth2Config | CustomAuthConfig;
+}
+/**
+ * HTTP客户端服务
+ * 基于Spring RestTemplate的设计理念，集成axios-retry库
+ * 支持两种创建模式:
+ * 1. 直接创建: 用于简单的HTTP请求场景
+ * 2. API客户端模式: 用于需要认证、统计等高级功能的API客户端
+ */
 export declare class HttpClientService {
     private readonly circuitBreakerService;
     private readonly loggingService;
-    private readonly cacheService;
     private readonly redisLockService?;
     private readonly logger;
     private readonly axiosInstance;
     private readonly defaultConfig;
+    private readonly authConfig?;
+    private readonly clientName?;
     private requestStats;
-    constructor(circuitBreakerService: HttpCircuitBreakerService, loggingService: HttpLoggingService, cacheService: HttpCacheService, redisLockService?: RedisLockService, config?: HttpClientConfig);
-    request<T = any>(config: ExtendedAxiosRequestConfig, decoratorContext?: any): Promise<T>;
+    constructor(circuitBreakerService: HttpCircuitBreakerService, loggingService: HttpLoggingService, redisLockService?: RedisLockService, config?: HttpClientConfig, clientName?: string, authConfig?: AuthConfig);
+    /**
+     * 静态工厂方法：创建API客户端模式的 HttpClientService
+     * @param dependencies 依赖服务
+     * @param config API客户端配置
+     * @returns HttpClientService 实例
+     */
+    static createApiClient(dependencies: {
+        circuitBreakerService: HttpCircuitBreakerService;
+        loggingService: HttpLoggingService;
+        redisLockService?: RedisLockService;
+    }, config: {
+        name: string;
+        baseURL?: string;
+        timeout?: number;
+        httpConfig?: HttpClientConfig;
+        auth?: AuthConfig;
+    }): HttpClientService;
+    /**
+     * 执行HTTP请求
+     */
+    request<T = any>(config: ExtendedAxiosRequestConfig, decoratorContext?: any, clientName?: string): Promise<T>;
+    /**
+     * 生成curl命令（动态生成，不存储）
+     */
     generateCurlCommand(config: ExtendedAxiosRequestConfig): string;
+    /**
+     * 生成调试curl命令（动态生成，不存储）
+     */
     generateDebugCurlCommand(config: ExtendedAxiosRequestConfig, response?: AxiosResponse): string;
+    /**
+     * 获取请求统计信息
+     */
     getStats(): any;
+    /**
+     * 重置统计信息
+     */
     resetStats(): void;
-    get<T = any>(url: string, config?: AxiosRequestConfig): Promise<T>;
-    post<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
-    put<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
-    patch<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
-    delete<T = any>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * 获取客户端名称
+     */
+    getName(): string | undefined;
+    /**
+     * Capture calling context information
+     * @returns Calling context with service class and method name
+     */
+    private captureCallingContext;
+    get<T = any>(url: string, config?: AxiosRequestConfig, clientName?: string): Promise<T>;
+    post<T = any>(url: string, data?: any, config?: AxiosRequestConfig, clientName?: string): Promise<T>;
+    put<T = any>(url: string, data?: any, config?: AxiosRequestConfig, clientName?: string): Promise<T>;
+    patch<T = any>(url: string, data?: any, config?: AxiosRequestConfig, clientName?: string): Promise<T>;
+    delete<T = any>(url: string, config?: AxiosRequestConfig, clientName?: string): Promise<T>;
+    /**
+     * 带等待锁的认证请求方法
+     * 用于需要确保只有一个进程执行认证相关操作的场景
+     *
+     * @param config 请求配置
+     * @param tokenProvider token提供函数
+     * @param options 等待锁选项
+     * @returns 响应数据
+     */
     authRequest<T = any>(config: AxiosRequestConfig, tokenProvider: () => Promise<string>, options?: {
         lockKey?: string;
         lockTimeout?: number;
         waitTimeout?: number;
         enableRetry?: boolean;
-    }): Promise<T>;
+    }, clientName?: string): Promise<T>;
+    /**
+     * 带等待锁的批量认证请求
+     * 用于需要批量执行认证相关操作但避免重复认证的场景
+     *
+     * @param requests 请求数组
+     * @param tokenProvider token提供函数
+     * @param options 等待锁选项
+     * @returns 响应数组
+     */
     authBatchRequest<T = any>(requests: Array<{
         config: AxiosRequestConfig;
         key: string;
@@ -45,16 +119,52 @@ export declare class HttpClientService {
         lockTimeout?: number;
         waitTimeout?: number;
         maxConcurrency?: number;
-    }): Promise<Array<T | null>>;
+    }, clientName?: string): Promise<Array<T | null>>;
+    /**
+     * 创建Axios实例并配置axios-retry
+     */
     private createAxiosInstance;
+    /**
+     * 执行带特性的请求（重试、熔断器等）
+     * 返回响应和熔断器状态
+     */
     private executeWithFeatures;
+    /**
+     * 计算重试延迟
+     */
     private calculateRetryDelay;
+    /**
+     * 应用装饰器配置
+     */
     private applyDecoratorConfig;
-    private shouldCacheRequest;
+    /**
+     * 生成熔断器键
+     */
     private generateCircuitBreakerKey;
-    private updateStats;
-    private updateErrorStats;
+    /**
+     * 合并默认配置
+     */
     private mergeWithDefaults;
+    /**
+     * 深度合并对象
+     */
     private deepMerge;
+    /**
+     * 解析代理配置
+     * 支持从环境变量或手动配置中读取
+     * @param proxyConfig 代理配置
+     * @param targetUrl 目标 URL（用于 NO_PROXY 检查）
+     * @returns 解析后的代理配置，如果不应使用代理则返回 false 或 undefined
+     */
+    private resolveProxyConfig;
+    /**
+     * 应用认证配置到请求配置
+     */
+    private applyAuthToConfig;
+    /**
+     * 更新请求统计信息
+     * 统一管理所有统计,避免在拦截器中重复统计
+     */
+    private updateRequestStats;
 }
 export {};