@nest-omni/core 4.1.3-1 → 4.1.3-3

package/http-client/services/cache.service.js

@@ -23,11 +23,18 @@ exports.HttpCacheService = void 0;
 const common_1 = require("@nestjs/common");
 const cache_service_1 = require("../../cache/cache.service");
 const cache_options_interface_1 = require("../../cache/interfaces/cache-options.interface");
+/**
+ * HTTP缓存服务
+ * 集成现有的三层缓存架构
+ */
 let HttpCacheService = HttpCacheService_1 = class HttpCacheService {
     constructor(cacheService) {
         this.cacheService = cacheService;
         this.logger = new common_1.Logger(HttpCacheService_1.name);
     }
+    /**
+     * 获取缓存的响应
+     */
     get(config, cacheOptions) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -51,6 +58,9 @@ let HttpCacheService = HttpCacheService_1 = class HttpCacheService {
             }
         });
     }
+    /**
+     * 缓存响应
+     */
     set(config, response, cacheOptions) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d;
@@ -75,14 +85,19 @@ let HttpCacheService = HttpCacheService_1 = class HttpCacheService {
             }
         });
     }
+    /**
+     * 清除缓存
+     */
     clear(pattern) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 if (pattern) {
+                    // 使用通配符清除
                     yield this.cacheService.deletePattern(pattern);
                     this.logger.debug(`Cache cleared with pattern: ${pattern}`);
                 }
                 else {
+                    // 清除所有HTTP相关缓存
                     yield this.cacheService.deletePattern('http:*');
                     this.logger.debug('All HTTP cache cleared');
                 }
@@ -92,6 +107,9 @@ let HttpCacheService = HttpCacheService_1 = class HttpCacheService {
             }
         });
     }
+    /**
+     * 获取缓存统计信息
+     */
     getStats() {
         return __awaiter(this, void 0, void 0, function* () {
             try {
@@ -104,9 +122,13 @@ let HttpCacheService = HttpCacheService_1 = class HttpCacheService {
             }
         });
     }
+    /**
+     * 清理过期缓存
+     */
     cleanup() {
         return __awaiter(this, void 0, void 0, function* () {
             try {
+                // CacheService doesn't have cleanup method, so we'll clear HTTP cache patterns
                 yield this.cacheService.deletePattern('http:*');
                 this.logger.debug('HTTP cache cleanup completed');
             }
@@ -115,12 +137,21 @@ let HttpCacheService = HttpCacheService_1 = class HttpCacheService {
             }
         });
     }
+    /**
+     * 预热缓存
+     */
     warmup(urls, headers) {
         return __awaiter(this, void 0, void 0, function* () {
             this.logger.log(`Starting cache warmup for ${urls.length} URLs`);
+            // 这里可以实现预热逻辑
+            // 例如：预先请求这些URL并缓存响应
+            // 实际实现需要访问HTTP客户端服务，可能需要通过事件或其他方式实现
             this.logger.log('Cache warmup completed');
         });
     }
+    /**
+     * 获取缓存命中率详情
+     */
     getDetailedStats() {
         return __awaiter(this, void 0, void 0, function* () {
             try {
@@ -134,11 +165,15 @@ let HttpCacheService = HttpCacheService_1 = class HttpCacheService {
             }
         });
     }
+    /**
+     * 生成缓存键
+     */
     generateCacheKey(config, cacheOptions) {
         var _a;
         if (cacheOptions.keyGenerator) {
             return cacheOptions.keyGenerator(config);
         }
+        // 默认键生成逻辑
         const keyData = {
             method: (_a = config.method) === null || _a === void 0 ? void 0 : _a.toLowerCase(),
             url: config.url,
@@ -146,16 +181,23 @@ let HttpCacheService = HttpCacheService_1 = class HttpCacheService {
             data: config.data,
             headers: this.selectHeadersForCacheKey(config.headers),
         };
+        // 简单的哈希键生成
         return this.hashObject(keyData);
     }
+    /**
+     * 构建完整的缓存键
+     */
     buildCacheKey(cacheOptions, key) {
         var _a;
         const namespace = ((_a = cacheOptions.options) === null || _a === void 0 ? void 0 : _a.prefix) || 'http';
         return `${namespace}:${key}`;
     }
+    /**
+     * 映射缓存层
+     */
     mapLayers(layers) {
         if (!layers || layers.length === 0) {
-            return [cache_options_interface_1.CacheLayer.MEMORY, cache_options_interface_1.CacheLayer.REDIS];
+            return [cache_options_interface_1.CacheLayer.MEMORY, cache_options_interface_1.CacheLayer.REDIS]; // 默认使用内存和Redis
         }
         return layers.map((layer) => {
             switch (layer) {
@@ -170,15 +212,19 @@ let HttpCacheService = HttpCacheService_1 = class HttpCacheService {
             }
         });
     }
+    /**
+     * 选择用于缓存键的头信息
+     */
     selectHeadersForCacheKey(headers) {
         if (!headers)
             return {};
+        // 只选择影响响应内容的头信息
         const cacheKeyHeaders = [
             'accept',
             'accept-language',
             'accept-encoding',
             'content-type',
-            'authorization',
+            'authorization', // 包含授权信息以确保缓存的安全性
         ];
         const selectedHeaders = {};
         cacheKeyHeaders.forEach((key) => {
@@ -188,15 +234,21 @@ let HttpCacheService = HttpCacheService_1 = class HttpCacheService {
         });
         return selectedHeaders;
     }
+    /**
+     * 判断响应是否可缓存
+     */
     isResponseCacheable(response, config) {
         var _a;
+        // 检查状态码
         if (!config.cacheableStatusCodes.includes(response.status)) {
             return false;
         }
+        // 检查方法
         const method = (_a = response.config.method) === null || _a === void 0 ? void 0 : _a.toLowerCase();
         if (!config.cacheableMethods.includes(method || 'get')) {
             return false;
         }
+        // 检查缓存控制头
         const cacheControl = response.headers['cache-control'];
         if (cacheControl) {
             if (cacheControl.includes('no-store') ||
@@ -204,28 +256,37 @@ let HttpCacheService = HttpCacheService_1 = class HttpCacheService {
                 return false;
             }
             if (cacheControl.includes('private')) {
+                // 私有缓存可能需要特殊处理
                 this.logger.debug('Private cache detected, caching with caution');
             }
         }
+        // 检查响应大小
         if (response.data) {
             const responseSize = JSON.stringify(response.data).length;
             if (responseSize > 1024 * 1024) {
+                // 1MB限制
                 this.logger.warn(`Response too large for caching: ${responseSize} bytes`);
                 return false;
             }
         }
         return true;
     }
+    /**
+     * 哈希对象
+     */
     hashObject(obj) {
         const str = JSON.stringify(obj, Object.keys(obj).sort());
         let hash = 0;
         for (let i = 0; i < str.length; i++) {
             const char = str.charCodeAt(i);
             hash = (hash << 5) - hash + char;
-            hash = hash & hash;
+            hash = hash & hash; // 转换为32位整数
         }
         return Math.abs(hash).toString(36);
     }
+    /**
+     * 计算综合命中率
+     */
     calculateHitRate(...stats) {
         let totalHits = 0;
         let totalRequests = 0;
@@ -237,8 +298,13 @@ let HttpCacheService = HttpCacheService_1 = class HttpCacheService {
         });
         return totalRequests > 0 ? (totalHits / totalRequests) * 100 : 0;
     }
+    /**
+     * 获取最近的缓存活动
+     */
     getRecentCacheActivity() {
         return __awaiter(this, void 0, void 0, function* () {
+            // 这里可以实现获取最近缓存活动的逻辑
+            // 例如：从Redis获取最近的缓存键访问记录
             return {
                 recentHits: 0,
                 recentMisses: 0,
@@ -246,6 +312,9 @@ let HttpCacheService = HttpCacheService_1 = class HttpCacheService {
             };
         });
     }
+    /**
+     * 生成缓存优化建议
+     */
     generateRecommendations(stats) {
         const recommendations = [];
         if (stats.combined.hitRate < 50) {

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

@@ -1,13 +1,32 @@
 import { Logger } from '@nestjs/common';
 import { CircuitBreakerConfig } from '../interfaces/http-client-config.interface';
+/**
+ * 熔断器服务
+ * 基于Spring Cloud CircuitBreaker的设计理念
+ */
 export declare class HttpCircuitBreakerService {
     private readonly logger;
     private readonly circuitBreakers;
+    /**
+     * 获取或创建熔断器
+     */
     getCircuitBreaker(key: string, config: CircuitBreakerConfig): CircuitBreaker;
+    /**
+     * 执行带熔断保护的请求
+     */
     executeWithCircuitBreaker<T>(key: string, requestFn: () => Promise<T>, config: CircuitBreakerConfig): Promise<T>;
+    /**
+     * 重置所有熔断器
+     */
     resetAll(): void;
+    /**
+     * 获取所有熔断器状态
+     */
     getAllStates(): Record<string, any>;
 }
+/**
+ * 熔断器类
+ */
 declare class CircuitBreaker {
     private readonly key;
     private readonly config;
@@ -20,14 +39,41 @@ declare class CircuitBreaker {
     private requestCount;
     private windowStartTime;
     constructor(key: string, config: CircuitBreakerConfig, logger: Logger);
+    /**
+     * 执行请求
+     */
     execute<T>(requestFn: () => Promise<T>): Promise<T>;
+    /**
+     * 重置熔断器
+     */
     reset(): void;
+    /**
+     * 获取熔断器状态
+     */
     getState(): any;
+    /**
+     * 处理成功请求
+     */
     private onSuccess;
+    /**
+     * 处理失败请求
+     */
     private onFailure;
+    /**
+     * 转换到关闭状态
+     */
     private transitionToClosed;
+    /**
+     * 转换到开启状态
+     */
     private transitionToOpen;
+    /**
+     * 转换到半开状态
+     */
     private transitionToHalfOpen;
+    /**
+     * 重置监控窗口
+     */
     private resetMonitoringWindow;
 }
 export {};

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

@@ -18,32 +18,51 @@ 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();
     }
+    /**
+     * 获取或创建熔断器
+     */
     getCircuitBreaker(key, config) {
         if (!this.circuitBreakers.has(key)) {
             this.circuitBreakers.set(key, new CircuitBreaker(key, config, this.logger));
         }
         return this.circuitBreakers.get(key);
     }
+    /**
+     * 执行带熔断保护的请求
+     */
     executeWithCircuitBreaker(key, requestFn, config) {
         return __awaiter(this, void 0, void 0, function* () {
             const circuitBreaker = this.getCircuitBreaker(key, config);
             return circuitBreaker.execute(requestFn);
         });
     }
+    /**
+     * 重置所有熔断器
+     */
     resetAll() {
         this.circuitBreakers.forEach((cb) => cb.reset());
     }
+    /**
+     * 获取所有熔断器状态
+     */
     getAllStates() {
         const states = {};
         this.circuitBreakers.forEach((cb, key) => {
@@ -56,6 +75,9 @@ exports.HttpCircuitBreakerService = HttpCircuitBreakerService;
 exports.HttpCircuitBreakerService = HttpCircuitBreakerService = HttpCircuitBreakerService_1 = __decorate([
     (0, common_1.Injectable)()
 ], HttpCircuitBreakerService);
+/**
+ * 熔断器类
+ */
 class CircuitBreaker {
     constructor(key, config, logger) {
         this.key = key;
@@ -69,9 +91,13 @@ class CircuitBreaker {
         this.requestCount = 0;
         this.windowStartTime = Date.now();
     }
+    /**
+     * 执行请求
+     */
     execute(requestFn) {
         return __awaiter(this, void 0, void 0, function* () {
             const currentTime = Date.now();
+            // 检查是否需要重置监控窗口
             if (currentTime - this.windowStartTime > this.config.monitoringPeriodMs) {
                 this.resetMonitoringWindow();
             }
@@ -87,6 +113,7 @@ class CircuitBreaker {
                     break;
                 case CircuitBreakerState.CLOSED:
                 default:
+                    // 正常状态，继续执行
                     break;
             }
             this.requestCount++;
@@ -101,10 +128,16 @@ class CircuitBreaker {
             }
         });
     }
+    /**
+     * 重置熔断器
+     */
     reset() {
         this.transitionToClosed();
         this.resetMonitoringWindow();
     }
+    /**
+     * 获取熔断器状态
+     */
     getState() {
         return {
             state: this.state,
@@ -117,6 +150,9 @@ class CircuitBreaker {
             config: this.config,
         };
     }
+    /**
+     * 处理成功请求
+     */
     onSuccess() {
         this.failureCount = 0;
         switch (this.state) {
@@ -128,9 +164,13 @@ class CircuitBreaker {
                 break;
             case CircuitBreakerState.CLOSED:
             default:
+                // 保持关闭状态
                 break;
         }
     }
+    /**
+     * 处理失败请求
+     */
     onFailure() {
         this.failureCount++;
         this.lastFailureTime = Date.now();
@@ -148,6 +188,9 @@ class CircuitBreaker {
                 break;
         }
     }
+    /**
+     * 转换到关闭状态
+     */
     transitionToClosed() {
         if (this.state !== CircuitBreakerState.CLOSED) {
             this.logger.log(`Circuit breaker ${this.key} transitioned to CLOSED`);
@@ -156,6 +199,9 @@ class CircuitBreaker {
             this.successCount = 0;
         }
     }
+    /**
+     * 转换到开启状态
+     */
     transitionToOpen() {
         if (this.state !== CircuitBreakerState.OPEN) {
             this.logger.warn(`Circuit breaker ${this.key} transitioned to OPEN due to ${this.failureCount} failures`);
@@ -164,6 +210,9 @@ class CircuitBreaker {
             this.successCount = 0;
         }
     }
+    /**
+     * 转换到半开状态
+     */
     transitionToHalfOpen() {
         if (this.state !== CircuitBreakerState.HALF_OPEN) {
             this.logger.log(`Circuit breaker ${this.key} transitioned to HALF_OPEN`);
@@ -171,6 +220,9 @@ class CircuitBreaker {
             this.successCount = 0;
         }
     }
+    /**
+     * 重置监控窗口
+     */
     resetMonitoringWindow() {
         this.windowStartTime = Date.now();
         this.requestCount = 0;

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

@@ -11,6 +11,10 @@ interface ExtendedAxiosRequestConfig extends AxiosRequestConfig {
         [key: string]: any;
     };
 }
+/**
+ * HTTP客户端服务
+ * 基于Spring RestTemplate的设计理念，集成axios-retry库
+ */
 export declare class HttpClientService {
     private readonly circuitBreakerService;
     private readonly loggingService;
@@ -21,22 +25,55 @@ export declare class HttpClientService {
     private readonly defaultConfig;
     private requestStats;
     constructor(circuitBreakerService: HttpCircuitBreakerService, loggingService: HttpLoggingService, cacheService: HttpCacheService, redisLockService?: RedisLockService, config?: HttpClientConfig);
+    /**
+     * 执行HTTP请求
+     */
     request<T = any>(config: ExtendedAxiosRequestConfig, decoratorContext?: any): 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>;
+    /**
+     * 带等待锁的认证请求方法
+     * 用于需要确保只有一个进程执行认证相关操作的场景
+     *
+     * @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>;
+    /**
+     * 带等待锁的批量认证请求
+     * 用于需要批量执行认证相关操作但避免重复认证的场景
+     *
+     * @param requests 请求数组
+     * @param tokenProvider token提供函数
+     * @param options 等待锁选项
+     * @returns 响应数组
+     */
     authBatchRequest<T = any>(requests: Array<{
         config: AxiosRequestConfig;
         key: string;
@@ -46,15 +83,45 @@ export declare class HttpClientService {
         waitTimeout?: number;
         maxConcurrency?: number;
     }): 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;
 }
 export {};