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

package/http-client/services/api-client-registry.service.js

@@ -21,22 +21,19 @@ var ApiClientRegistryService_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiClientRegistryService = exports.AuthType = void 0;
 const common_1 = require("@nestjs/common");
-const axios_1 = require("axios");
-const axios_retry_1 = require("axios-retry");
 const api_client_config_interface_1 = require("../interfaces/api-client-config.interface");
 Object.defineProperty(exports, "AuthType", { enumerable: true, get: function () { return api_client_config_interface_1.AuthType; } });
 const http_client_service_1 = require("./http-client.service");
 const circuit_breaker_service_1 = require("./circuit-breaker.service");
 const logging_service_1 = require("./logging.service");
-const cache_service_1 = require("./cache.service");
-const context_extractor_util_1 = require("../utils/context-extractor.util");
-const utils_1 = require("../../common/utils");
+/**
+ * API客户端注册服务
+ * 负责管理多个 HttpClientService 实例
+ */
 let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegistryService {
-    constructor(httpClientService, circuitBreakerService, loggingService, cacheService, globalConfig = {}) {
-        this.httpClientService = httpClientService;
+    constructor(circuitBreakerService, loggingService, globalConfig = {}) {
         this.circuitBreakerService = circuitBreakerService;
         this.loggingService = loggingService;
-        this.cacheService = cacheService;
         this.logger = new common_1.Logger(ApiClientRegistryService_1.name);
         this.clients = new Map();
         this.clientConfigs = new Map();
@@ -60,21 +57,62 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
                 maxRecords: 1000000,
             }, enableGlobalRetry: true, enableCircuitBreaker: true }, globalConfig);
     }
+    /**
+     * 创建API客户端实例
+     * 使用 HttpClientService.createApiClient 静态方法创建
+     */
     createClient(config) {
+        var _a, _b, _c, _d, _e, _f, _g;
         const clientName = config.name;
         const existingClient = this.clients.get(clientName);
         if (existingClient && !config.override) {
             this.logger.warn(`Client '${clientName}' already exists. Use override: true to replace it.`);
             return existingClient;
         }
+        // 合并环境特定配置
         const finalConfig = this.mergeEnvironmentConfig(config);
-        const axiosInstance = this.createAxiosInstance(finalConfig);
-        const client = new ApiClientInstance(clientName, finalConfig, axiosInstance, this.httpClientService, this.loggingService, this.cacheService);
-        this.clients.set(clientName, client);
+        // 使用静态工厂方法创建 HttpClientService 实例
+        const httpClient = http_client_service_1.HttpClientService.createApiClient({
+            circuitBreakerService: this.circuitBreakerService,
+            loggingService: this.loggingService,
+        }, {
+            name: clientName,
+            baseURL: finalConfig.baseURL,
+            timeout: ((_a = finalConfig.httpConfig) === null || _a === void 0 ? void 0 : _a.timeout) || 30000,
+            httpConfig: Object.assign({ retry: {
+                    enabled: ((_b = finalConfig.retry) === null || _b === void 0 ? void 0 : _b.enabled) !== false &&
+                        this.globalDefaults.enableGlobalRetry,
+                    retries: ((_c = finalConfig.retry) === null || _c === void 0 ? void 0 : _c.retries) ||
+                        ((_e = (_d = this.globalDefaults.globalDefaults) === null || _d === void 0 ? void 0 : _d.retry) === null || _e === void 0 ? void 0 : _e.retries) ||
+                        3,
+                    retryDelay: (retryCount) => Math.pow(2, retryCount) * 1000,
+                    retryCondition: ((_f = finalConfig.retry) === null || _f === void 0 ? void 0 : _f.retryCondition) ||
+                        ((error) => {
+                            if (!error.response)
+                                return true;
+                            const status = error.response.status;
+                            return status >= 500 || status === 429;
+                        }),
+                    shouldResetTimeout: true,
+                }, logging: Object.assign({ enabled: true, logRequests: true, logResponses: true, logErrors: true, logHeaders: true, logBody: true, maxBodyLength: 10000, sanitizeHeaders: ['authorization', 'api-key'], logLevel: 'info' }, (_g = this.globalDefaults.globalDefaults) === null || _g === void 0 ? void 0 : _g.logging), circuitBreaker: {
+                    enabled: this.globalDefaults.enableCircuitBreaker,
+                    failureThreshold: 5,
+                    recoveryTimeoutMs: 60000,
+                    monitoringPeriodMs: 10000,
+                    minimumThroughputThreshold: 10,
+                    countHalfOpenCalls: true,
+                } }, finalConfig.httpConfig),
+            auth: finalConfig.auth,
+        });
+        // 存储客户端和配置
+        this.clients.set(clientName, httpClient);
         this.clientConfigs.set(clientName, finalConfig);
         this.logger.log(`Created API client: ${clientName}`);
-        return client;
+        return httpClient;
     }
+    /**
+     * 获取已注册的客户端
+     */
     getClient(name) {
         const client = this.clients.get(name);
         if (!client) {
@@ -82,9 +120,15 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
         }
         return client;
     }
+    /**
+     * 列出所有已注册的客户端
+     */
     listClients() {
         return Array.from(this.clients.keys());
     }
+    /**
+     * 更新客户端配置
+     */
     updateClient(name, config) {
         const existingConfig = this.clientConfigs.get(name);
         if (!existingConfig) {
@@ -92,9 +136,13 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
         }
         const updatedConfig = Object.assign(Object.assign({}, existingConfig), config);
         this.clientConfigs.set(name, updatedConfig);
+        // 重新创建客户端实例
         this.createClient(Object.assign(Object.assign({}, updatedConfig), { name, override: true }));
         this.logger.log(`Updated API client: ${name}`);
     }
+    /**
+     * 移除客户端
+     */
     removeClient(name) {
         const removed = this.clients.delete(name);
         this.clientConfigs.delete(name);
@@ -102,9 +150,15 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
             this.logger.log(`Removed API client: ${name}`);
         }
     }
+    /**
+     * 获取客户端配置
+     */
     getClientConfig(name) {
         return this.clientConfigs.get(name);
     }
+    /**
+     * 获取所有客户端配置
+     */
     getAllClientConfigs() {
         const configs = {};
         this.clientConfigs.forEach((config, name) => {
@@ -112,6 +166,9 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
         });
         return configs;
     }
+    /**
+     * 批量创建客户端
+     */
     createClients(configs) {
         configs.forEach((config) => {
             try {
@@ -122,13 +179,22 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
             }
         });
     }
+    /**
+     * 获取全局配置
+     */
     getGlobalConfig() {
         return this.globalDefaults;
     }
+    /**
+     * 更新全局配置
+     */
     updateGlobalConfig(config) {
         Object.assign(this.globalDefaults, config);
         this.logger.log('Global configuration updated');
     }
+    /**
+     * 获取统计信息
+     */
     getAllStats() {
         const stats = {};
         this.clients.forEach((client, name) => {
@@ -136,17 +202,24 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
         });
         return stats;
     }
+    /**
+     * 重置所有统计信息
+     */
     resetAllStats() {
         this.clients.forEach((client) => {
             client.resetStats();
         });
     }
+    /**
+     * 健康检查
+     */
     healthCheck() {
         return __awaiter(this, void 0, void 0, function* () {
             const results = {};
             let overallStatus = 'healthy';
             for (const [name, client] of this.clients.entries()) {
                 try {
+                    // 简单的健康检查：尝试获取客户端统计信息
                     client.getStats();
                     results[name] = { status: 'healthy' };
                 }
@@ -161,156 +234,9 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
             };
         });
     }
-    createAxiosInstance(config) {
-        var _a, _b, _c, _d, _e, _f;
-        const axiosConfig = {
-            baseURL: config.baseURL,
-            timeout: ((_a = config.httpConfig) === null || _a === void 0 ? void 0 : _a.timeout) || 30000,
-            headers: Object.assign({ 'Content-Type': 'application/json', 'User-Agent': `${config.name}/1.0.0` }, config.defaultHeaders),
-            params: config.defaultParams,
-        };
-        const instance = axios_1.default.create(axiosConfig);
-        const clientName = config.name;
-        instance.interceptors.request.use((config) => {
-            const authenticatedConfig = config;
-            if (config.auth) {
-                switch (config.auth.type) {
-                    case api_client_config_interface_1.AuthType.BEARER_TOKEN:
-                        const bearerConfig = config.auth.config;
-                        authenticatedConfig.headers = authenticatedConfig.headers || {};
-                        authenticatedConfig.headers['Authorization'] =
-                            `Bearer ${bearerConfig.token}`;
-                        break;
-                    case api_client_config_interface_1.AuthType.API_KEY:
-                        const apiKeyConfig = config.auth.config;
-                        if (apiKeyConfig.location === 'header') {
-                            const headerName = apiKeyConfig.name || 'X-API-Key';
-                            const value = apiKeyConfig.prefix
-                                ? `${apiKeyConfig.prefix} ${apiKeyConfig.key}`
-                                : apiKeyConfig.key;
-                            authenticatedConfig.headers = authenticatedConfig.headers || {};
-                            authenticatedConfig.headers[headerName] = value;
-                        }
-                        break;
-                }
-            }
-            const context = context_extractor_util_1.ContextExtractor.getHttpContext();
-            const requestId = context.requestId || (0, utils_1.generateRequestId)();
-            authenticatedConfig.headers = authenticatedConfig.headers || {};
-            authenticatedConfig.headers['X-Request-ID'] = requestId;
-            if (context.userId) {
-                authenticatedConfig.headers['X-User-ID'] = context.userId;
-            }
-            authenticatedConfig.headers['X-API-Client'] = clientName;
-            return authenticatedConfig;
-        }, (error) => {
-            this.logger.error(`[${clientName}] Request interceptor error`, error);
-            return Promise.reject(error);
-        });
-        instance.interceptors.response.use((response) => {
-            return this.applyResponseTransformer(response, config.responseTransformer);
-        }, (error) => {
-            var _a;
-            if ((_a = config.responseTransformer) === null || _a === void 0 ? void 0 : _a.error) {
-                return config.responseTransformer.error(error);
-            }
-            return Promise.reject(error);
-        });
-        if (((_b = config.retry) === null || _b === void 0 ? void 0 : _b.enabled) !== false &&
-            this.globalDefaults.enableGlobalRetry) {
-            (0, axios_retry_1.default)(instance, {
-                retries: ((_c = config.retry) === null || _c === void 0 ? void 0 : _c.retries) ||
-                    ((_e = (_d = this.globalDefaults.globalDefaults) === null || _d === void 0 ? void 0 : _d.retry) === null || _e === void 0 ? void 0 : _e.retries) ||
-                    3,
-                retryDelay: (retryCount) => Math.pow(2, retryCount) * 1000,
-                retryCondition: ((_f = config.retry) === null || _f === void 0 ? void 0 : _f.retryCondition) ||
-                    ((error) => {
-                        if (!error.response)
-                            return true;
-                        const status = error.response.status;
-                        return status >= 500 || status === 429;
-                    }),
-                shouldResetTimeout: true,
-                onRetry: (retryCount, error, requestConfig) => {
-                    var _a;
-                    this.logger.warn(`[${config.name}] Retrying request (attempt ${retryCount}): ${(_a = requestConfig.method) === null || _a === void 0 ? void 0 : _a.toUpperCase()} ${requestConfig.url}`);
-                },
-            });
-        }
-        return instance;
-    }
-    applyAuthentication(config, auth) {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (!auth) {
-                return config;
-            }
-            const authenticatedConfig = Object.assign({}, config);
-            switch (auth.type) {
-                case api_client_config_interface_1.AuthType.NONE:
-                    break;
-                case api_client_config_interface_1.AuthType.API_KEY:
-                    const apiKeyConfig = auth.config;
-                    if (apiKeyConfig.location === 'header') {
-                        const headerName = apiKeyConfig.name || 'X-API-Key';
-                        const value = apiKeyConfig.prefix
-                            ? `${apiKeyConfig.prefix} ${apiKeyConfig.key}`
-                            : apiKeyConfig.key;
-                        authenticatedConfig.headers = Object.assign(Object.assign({}, authenticatedConfig.headers), { [headerName]: value });
-                    }
-                    else if (apiKeyConfig.location === 'query') {
-                        const paramName = apiKeyConfig.name || 'api_key';
-                        authenticatedConfig.params = Object.assign(Object.assign({}, authenticatedConfig.params), { [paramName]: apiKeyConfig.key });
-                    }
-                    break;
-                case api_client_config_interface_1.AuthType.BEARER_TOKEN:
-                    const bearerConfig = auth.config;
-                    const scheme = bearerConfig.scheme || 'Bearer';
-                    authenticatedConfig.headers = Object.assign(Object.assign({}, authenticatedConfig.headers), { Authorization: `${scheme} ${bearerConfig.token}` });
-                    break;
-                case api_client_config_interface_1.AuthType.BASIC_AUTH:
-                    const basicConfig = auth.config;
-                    const credentials = Buffer.from(`${basicConfig.username}:${basicConfig.password}`).toString('base64');
-                    authenticatedConfig.headers = Object.assign(Object.assign({}, authenticatedConfig.headers), { Authorization: `Basic ${credentials}` });
-                    break;
-                case api_client_config_interface_1.AuthType.OAUTH2:
-                    const oauthConfig = auth.config;
-                    authenticatedConfig.headers = Object.assign(Object.assign({}, authenticatedConfig.headers), { Authorization: `Bearer ${oauthConfig.clientSecret}` });
-                    break;
-                case api_client_config_interface_1.AuthType.CUSTOM:
-                    const customConfig = auth.config;
-                    return yield customConfig.authenticator(authenticatedConfig);
-            }
-            return authenticatedConfig;
-        });
-    }
-    applyResponseTransformer(response, transformer) {
-        if (!transformer) {
-            return response;
-        }
-        if (transformer.success) {
-            response.data = transformer.success(response);
-        }
-        if (transformer.dataPath) {
-            response.data = this.extractDataByPath(response.data, transformer.dataPath);
-        }
-        if (transformer.validateResponse && transformer.validator) {
-            if (!transformer.validator(response.data)) {
-                throw new Error(`Response validation failed for ${transformer.dataPath}`);
-            }
-        }
-        return response;
-    }
-    extractDataByPath(data, path) {
-        const keys = path.split('.');
-        let current = data;
-        for (const key of keys) {
-            if (current === null || current === undefined) {
-                return undefined;
-            }
-            current = current[key];
-        }
-        return current;
-    }
+    /**
+     * 合并环境特定配置
+     */
     mergeEnvironmentConfig(config) {
         var _a;
         const env = process.env.NODE_ENV || 'development';
@@ -321,92 +247,6 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
 exports.ApiClientRegistryService = ApiClientRegistryService;
 exports.ApiClientRegistryService = ApiClientRegistryService = ApiClientRegistryService_1 = __decorate([
     (0, common_1.Injectable)(),
-    __metadata("design:paramtypes", [http_client_service_1.HttpClientService,
-        circuit_breaker_service_1.HttpCircuitBreakerService,
-        logging_service_1.HttpLoggingService,
-        cache_service_1.HttpCacheService, Object])
+    __metadata("design:paramtypes", [circuit_breaker_service_1.HttpCircuitBreakerService,
+        logging_service_1.HttpLoggingService, Object])
 ], ApiClientRegistryService);
-class ApiClientInstance {
-    constructor(name, config, axiosInstance, httpClientService, loggingService, cacheService) {
-        this.name = name;
-        this.config = config;
-        this.axiosInstance = axiosInstance;
-        this.httpClientService = httpClientService;
-        this.loggingService = loggingService;
-        this.cacheService = cacheService;
-        this.stats = {
-            totalRequests: 0,
-            successfulRequests: 0,
-            failedRequests: 0,
-            totalResponseTime: 0,
-            averageResponseTime: 0,
-        };
-    }
-    get(url, config) {
-        return __awaiter(this, void 0, void 0, function* () {
-            return this.request(Object.assign(Object.assign({}, config), { method: 'GET', url }));
-        });
-    }
-    post(url, data, config) {
-        return __awaiter(this, void 0, void 0, function* () {
-            return this.request(Object.assign(Object.assign({}, config), { method: 'POST', url, data }));
-        });
-    }
-    put(url, data, config) {
-        return __awaiter(this, void 0, void 0, function* () {
-            return this.request(Object.assign(Object.assign({}, config), { method: 'PUT', url, data }));
-        });
-    }
-    patch(url, data, config) {
-        return __awaiter(this, void 0, void 0, function* () {
-            return this.request(Object.assign(Object.assign({}, config), { method: 'PATCH', url, data }));
-        });
-    }
-    delete(url, config) {
-        return __awaiter(this, void 0, void 0, function* () {
-            return this.request(Object.assign(Object.assign({}, config), { method: 'DELETE', url }));
-        });
-    }
-    request(config) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const startTime = Date.now();
-            this.stats.totalRequests++;
-            try {
-                const response = yield this.axiosInstance.request(config);
-                const responseTime = Date.now() - startTime;
-                this.updateStats(true, responseTime);
-                return response.data;
-            }
-            catch (error) {
-                const responseTime = Date.now() - startTime;
-                this.updateStats(false, responseTime);
-                throw error;
-            }
-        });
-    }
-    getStats() {
-        return Object.assign({}, this.stats);
-    }
-    resetStats() {
-        this.stats.totalRequests = 0;
-        this.stats.successfulRequests = 0;
-        this.stats.failedRequests = 0;
-        this.stats.totalResponseTime = 0;
-        this.stats.averageResponseTime = 0;
-    }
-    updateStats(success, responseTime) {
-        if (success) {
-            this.stats.successfulRequests++;
-        }
-        else {
-            this.stats.failedRequests++;
-        }
-        this.stats.totalResponseTime += responseTime;
-        this.stats.averageResponseTime =
-            this.stats.totalResponseTime / this.stats.totalRequests;
-        if (this.config.responseTimeWarningThreshold &&
-            responseTime > this.config.responseTimeWarningThreshold) {
-            console.warn(`[API Client ${this.name}] Slow response detected: ${responseTime}ms for ${this.axiosInstance.defaults.baseURL}`);
-        }
-    }
-}

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

@@ -1,13 +1,85 @@
 import { Logger } from '@nestjs/common';
 import { CircuitBreakerConfig } from '../interfaces/http-client-config.interface';
+/**
+ * Circuit Breaker 清理配置
+ */
+interface CircuitBreakerCleanupConfig {
+    /** 最大空闲时间（毫秒），超过此时间未使用的circuit breaker将被清理 */
+    maxIdleTimeMs: number;
+    /** 清理间隔（毫秒），定期清理的时间间隔 */
+    cleanupIntervalMs: number;
+    /** 最大circuit breaker数量，超过此数量时触发LRU清理 */
+    maxSize: number;
+}
+/**
+ * 熔断器服务
+ * 基于Spring Cloud CircuitBreaker的设计理念
+ */
 export declare class HttpCircuitBreakerService {
     private readonly logger;
     private readonly circuitBreakers;
+    private cleanupTimer?;
+    /** 默认清理配置 */
+    private readonly cleanupConfig;
+    constructor();
+    onModuleDestroy(): void;
+    /**
+     * 获取或创建熔断器
+     */
     getCircuitBreaker(key: string, config: CircuitBreakerConfig): CircuitBreaker;
-    executeWithCircuitBreaker<T>(key: string, requestFn: () => Promise<T>, config: CircuitBreakerConfig): Promise<T>;
+    /**
+     * 执行带熔断保护的请求
+     */
+    executeWithCircuitBreaker<T>(key: string, requestFn: () => Promise<T>, config: CircuitBreakerConfig, onStateChange?: (state: string) => void): Promise<T>;
+    /**
+     * 获取熔断器当前状态
+     */
+    getCircuitBreakerState(key: string): string | undefined;
+    /**
+     * 重置所有熔断器
+     */
     resetAll(): void;
+    /**
+     * 获取所有熔断器状态
+     */
     getAllStates(): Record<string, any>;
+    /**
+     * 获取Circuit Breaker统计信息
+     */
+    getStats(): {
+        total: number;
+        byState: Record<string, number>;
+    };
+    /**
+     * 清理空闲的Circuit Breaker
+     * 清理超过最大空闲时间的Circuit Breaker
+     */
+    cleanupIdle(): number;
+    /**
+     * 基于LRU策略清理Circuit Breaker
+     * 删除最久未访问的Circuit Breaker直到数量降到maxSize以下
+     */
+    private cleanupLRU;
+    /**
+     * 启动定期清理任务
+     */
+    private startCleanupTask;
+    /**
+     * 手动触发清理（用于测试）
+     */
+    manualCleanup(): number;
+    /**
+     * 设置清理配置
+     */
+    setCleanupConfig(config: Partial<CircuitBreakerCleanupConfig>): void;
+    /**
+     * 获取清理配置
+     */
+    getCleanupConfig(): CircuitBreakerCleanupConfig;
 }
+/**
+ * 熔断器类
+ */
 declare class CircuitBreaker {
     private readonly key;
     private readonly config;
@@ -19,15 +91,56 @@ declare class CircuitBreaker {
     private nextAttemptTime;
     private requestCount;
     private windowStartTime;
+    private onStateChange?;
+    private lastAccessTime;
     constructor(key: string, config: CircuitBreakerConfig, logger: Logger);
-    execute<T>(requestFn: () => Promise<T>): Promise<T>;
+    /**
+     * 更新最后访问时间
+     */
+    updateLastAccessTime(): void;
+    /**
+     * 获取最后访问时间
+     */
+    getLastAccessTime(): number;
+    /**
+     * 执行请求
+     */
+    execute<T>(requestFn: () => Promise<T>, onStateChange?: (state: string) => void): Promise<T>;
+    /**
+     * 重置熔断器
+     */
     reset(): void;
+    /**
+     * 获取熔断器状态
+     */
     getState(): any;
+    /**
+     * 处理成功请求
+     */
     private onSuccess;
+    /**
+     * 处理失败请求
+     */
     private onFailure;
+    /**
+     * 转换到关闭状态
+     */
     private transitionToClosed;
+    /**
+     * 转换到开启状态
+     */
     private transitionToOpen;
+    /**
+     * 转换到半开状态
+     */
     private transitionToHalfOpen;
+    /**
+     * 通知状态变化
+     */
+    private notifyStateChange;
+    /**
+     * 重置监控窗口
+     */
     private resetMonitoringWindow;
 }
 export {};