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

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

@@ -32,6 +32,10 @@ const curl_generator_util_1 = require("../utils/curl-generator.util");
 const retry_recorder_util_1 = require("../utils/retry-recorder.util");
 const request_id_util_1 = require("../utils/request-id.util");
 const redis_lock_service_1 = require("../../redis-lock/redis-lock.service");
+/**
+ * HTTP客户端服务
+ * 基于Spring RestTemplate的设计理念，集成axios-retry库
+ */
 let HttpClientService = HttpClientService_1 = class HttpClientService {
     constructor(circuitBreakerService, loggingService, cacheService, redisLockService, config = {}) {
         this.circuitBreakerService = circuitBreakerService;
@@ -50,6 +54,9 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
         this.defaultConfig = this.mergeWithDefaults(config);
         this.axiosInstance = this.createAxiosInstance();
     }
+    /**
+     * 执行HTTP请求
+     */
     request(config, decoratorContext) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d, _e, _f, _g;
@@ -59,16 +66,21 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
             let circuitBreakerState;
             let cacheHit = false;
             try {
+                // 应用装饰器配置
                 const enhancedConfig = this.applyDecoratorConfig(config, decoratorContext);
+                // 获取装饰器配置
                 const decoratorConfigs = decoratorContext
                     ? decorators_1.HttpDecoratorUtils.getAllDecoratorConfigs(decoratorContext.target, decoratorContext.propertyKey)
                     : {};
+                // 日志记录开始
                 const loggingOptions = decoratorConfigs.logging || this.defaultConfig.logging;
                 if (loggingOptions === null || loggingOptions === void 0 ? void 0 : loggingOptions.enabled) {
                     requestId = this.loggingService.logRequestStart(enhancedConfig, loggingOptions);
+                    // 将requestId保存到config中
                     enhancedConfig.metadata = enhancedConfig.metadata || {};
                     enhancedConfig.metadata.requestId = requestId;
                 }
+                // 缓存检查
                 const cacheConfig = decoratorConfigs.cache || this.defaultConfig.cache;
                 if ((cacheConfig === null || cacheConfig === void 0 ? void 0 : cacheConfig.enabled) &&
                     this.shouldCacheRequest(enhancedConfig, cacheConfig)) {
@@ -78,15 +90,19 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
                         if (loggingOptions === null || loggingOptions === void 0 ? void 0 : loggingOptions.enabled) {
                             const databaseLogging = (loggingOptions === null || loggingOptions === void 0 ? void 0 : loggingOptions.databaseLog) ||
                                 ((_b = (_a = this.defaultConfig.logging) === null || _a === void 0 ? void 0 : _a.databaseLogging) === null || _b === void 0 ? void 0 : _b.enabled);
-                            this.loggingService.logRequestSuccess(cachedResponse, startTime, requestId, loggingOptions, databaseLogging, undefined, cacheHit, undefined, decoratorContext);
+                            this.loggingService.logRequestSuccess(cachedResponse, startTime, requestId, loggingOptions, databaseLogging, undefined, // no retry records for cache hit
+                            cacheHit, undefined, // circuit breaker state
+                            decoratorContext);
                         }
                         return cachedResponse.data;
                     }
                 }
+                // 应用超时配置
                 const timeout = decoratorConfigs.timeout || this.defaultConfig.timeout;
                 if (timeout) {
                     enhancedConfig.timeout = timeout;
                 }
+                // 应用代理配置
                 const proxyConfig = decoratorConfigs.proxy || this.defaultConfig.proxy;
                 if (proxyConfig === null || proxyConfig === void 0 ? void 0 : proxyConfig.enabled) {
                     enhancedConfig.proxy = {
@@ -96,23 +112,29 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
                         auth: proxyConfig.auth,
                     };
                 }
+                // 配置axios-retry的onRetry回调以记录重试
                 if ((_c = this.defaultConfig.retry) === null || _c === void 0 ? void 0 : _c.enabled) {
                     const originalOnRetry = this.defaultConfig.retry.onRetry;
                     this.defaultConfig.retry.onRetry = (retryCount, error, requestConfig) => {
+                        // 记录重试
                         const retryRecord = retry_recorder_util_1.RetryRecorder.recordRetry(retryCount, error, requestConfig, this.calculateRetryDelay(retryCount, this.defaultConfig.retry));
                         retryRecorder.addRecord(retryRecord);
+                        // 调用原始回调
                         if (originalOnRetry) {
                             originalOnRetry(retryCount, error, requestConfig);
                         }
                     };
                 }
+                // 执行请求（带重试和熔断器）
                 const response = yield this.executeWithFeatures(enhancedConfig, decoratorConfigs, requestId, startTime, retryRecorder, (state) => {
                     circuitBreakerState = state;
                 });
+                // 缓存响应
                 if ((cacheConfig === null || cacheConfig === void 0 ? void 0 : cacheConfig.enabled) &&
                     this.shouldCacheRequest(enhancedConfig, cacheConfig)) {
                     yield this.cacheService.set(enhancedConfig, response, cacheConfig);
                 }
+                // 成功日志
                 if (loggingOptions === null || loggingOptions === void 0 ? void 0 : loggingOptions.enabled) {
                     const databaseLogging = (loggingOptions === null || loggingOptions === void 0 ? void 0 : loggingOptions.databaseLog) ||
                         ((_e = (_d = this.defaultConfig.logging) === null || _d === void 0 ? void 0 : _d.databaseLogging) === null || _e === void 0 ? void 0 : _e.enabled);
@@ -121,6 +143,7 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
                 return response.data;
             }
             catch (error) {
+                // 错误日志
                 const loggingOptions = decoratorContext
                     ? decorators_1.HttpDecoratorUtils.getLoggingOptions(decoratorContext.target, decoratorContext.propertyKey)
                     : this.defaultConfig.logging;
@@ -133,12 +156,21 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
             }
         });
     }
+    /**
+     * 生成curl命令（动态生成，不存储）
+     */
     generateCurlCommand(config) {
         return curl_generator_util_1.CurlGenerator.generateSimplifiedCurl(config);
     }
+    /**
+     * 生成调试curl命令（动态生成，不存储）
+     */
     generateDebugCurlCommand(config, response) {
         return curl_generator_util_1.CurlGenerator.generateDebugCurl(config, response);
     }
+    /**
+     * 获取请求统计信息
+     */
     getStats() {
         const avgResponseTime = this.requestStats.totalRequests > 0
             ? this.requestStats.totalResponseTime / this.requestStats.totalRequests
@@ -149,6 +181,9 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
                     100
                 : 0, circuitBreakerStats: this.circuitBreakerService.getAllStates(), cacheStats: this.cacheService.getStats() });
     }
+    /**
+     * 重置统计信息
+     */
     resetStats() {
         this.requestStats = {
             totalRequests: 0,
@@ -159,6 +194,7 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
             requestsByStatus: {},
         };
     }
+    // 便捷方法
     get(url, config) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.request(Object.assign(Object.assign({}, config), { method: 'GET', url }));
@@ -184,6 +220,15 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
             return this.request(Object.assign(Object.assign({}, config), { method: 'DELETE', url }));
         });
     }
+    /**
+     * 带等待锁的认证请求方法
+     * 用于需要确保只有一个进程执行认证相关操作的场景
+     *
+     * @param config 请求配置
+     * @param tokenProvider token提供函数
+     * @param options 等待锁选项
+     * @returns 响应数据
+     */
     authRequest(config, tokenProvider, options) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.redisLockService) {
@@ -192,9 +237,13 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
             }
             const { lockKey = `auth-request:${(0, request_id_util_1.generateRequestId)()}`, lockTimeout = 30000, waitTimeout = 60000, enableRetry = true, } = options || {};
             try {
+                // 尝试获取锁并执行请求
                 const result = yield this.redisLockService.withLock(lockKey, () => __awaiter(this, void 0, void 0, function* () {
+                    // 获取token
                     const token = yield tokenProvider();
+                    // 添加认证头
                     const authConfig = Object.assign(Object.assign({}, config), { headers: Object.assign(Object.assign({}, config.headers), { Authorization: `Bearer ${token}` }) });
+                    // 执行请求
                     return this.request(authConfig);
                 }), {
                     ttl: lockTimeout,
@@ -209,6 +258,7 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
             }
             catch (error) {
                 this.logger.error(`Auth request failed with lock ${lockKey}`, error);
+                // 如果是锁获取失败且启用重试，尝试无锁执行
                 if (enableRetry && error.message.includes('Failed to acquire lock')) {
                     this.logger.warn('Retrying auth request without lock');
                     const token = yield tokenProvider();
@@ -219,10 +269,20 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
             }
         });
     }
+    /**
+     * 带等待锁的批量认证请求
+     * 用于需要批量执行认证相关操作但避免重复认证的场景
+     *
+     * @param requests 请求数组
+     * @param tokenProvider token提供函数
+     * @param options 等待锁选项
+     * @returns 响应数组
+     */
     authBatchRequest(requests, tokenProvider, options) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.redisLockService) {
                 this.logger.warn('RedisLockService not available, proceeding batch auth requests without lock');
+                // 无锁批量执行
                 const token = yield tokenProvider();
                 const promises = requests.map((request) => __awaiter(this, void 0, void 0, function* () {
                     try {
@@ -238,8 +298,11 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
             }
             const { lockKey = `batch-auth-request:${(0, request_id_util_1.generateRequestId)()}`, lockTimeout = 60000, waitTimeout = 120000, maxConcurrency = 5, } = options || {};
             try {
+                // 使用锁获取token并执行批量请求
                 const results = yield this.redisLockService.withLock(lockKey, () => __awaiter(this, void 0, void 0, function* () {
+                    // 获取token（只获取一次）
                     const token = yield tokenProvider();
+                    // 创建并发请求
                     const semaphore = new Array(maxConcurrency).fill(null);
                     const results = new Array(requests.length);
                     const executing = new Set();
@@ -259,6 +322,7 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
                             executing.delete(key);
                         }
                     });
+                    // 创建并发的请求Promise
                     const promises = requests.map((request, index) => __awaiter(this, void 0, void 0, function* () {
                         return new Promise((resolve, reject) => {
                             const checkSlot = () => {
@@ -301,6 +365,9 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
             }
         });
     }
+    /**
+     * 创建Axios实例并配置axios-retry
+     */
     createAxiosInstance() {
         var _a, _b;
         const instance = require('axios').create({
@@ -315,6 +382,7 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
                 }
                 : undefined,
         });
+        // 配置axios-retry
         if ((_b = this.defaultConfig.retry) === null || _b === void 0 ? void 0 : _b.enabled) {
             (0, axios_retry_1.default)(instance, {
                 retries: this.defaultConfig.retry.retries || 3,
@@ -323,9 +391,9 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
                 retryCondition: this.defaultConfig.retry.retryCondition ||
                     ((error) => {
                         if (!error.response)
-                            return true;
+                            return true; // 网络错误
                         const status = error.response.status;
-                        return status >= 500 || status === 429;
+                        return status >= 500 || status === 429; // 5xx错误或429限流
                     }),
                 shouldResetTimeout: this.defaultConfig.retry.shouldResetTimeout !== false,
                 onRetry: this.defaultConfig.retry.onRetry ||
@@ -335,14 +403,17 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
                     }),
             });
         }
+        // 设置请求拦截器
         instance.interceptors.request.use((config) => {
             config.headers = config.headers || {};
+            // 从ContextProvider获取上下文信息
             const context = context_extractor_util_1.ContextExtractor.getHttpContext();
             const requestId = context.requestId || (0, request_id_util_1.generateRequestId)();
             config.headers['X-Request-ID'] = requestId;
             if (context.userId) {
                 config.headers['X-User-ID'] = context.userId;
             }
+            // 存储requestId到config中供后续使用
             config.metadata = config.metadata || {};
             config.metadata.requestId = requestId;
             return config;
@@ -350,6 +421,7 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
             this.logger.error('Request interceptor error', error);
             return Promise.reject(error);
         });
+        // 设置响应拦截器
         instance.interceptors.response.use((response) => {
             this.updateStats(response);
             return response;
@@ -359,9 +431,13 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
         });
         return instance;
     }
+    /**
+     * 执行带特性的请求（重试、熔断器等）
+     */
     executeWithFeatures(config, decoratorConfigs, requestId, startTime, retryRecorder, onCircuitBreakerStateChange) {
         return __awaiter(this, void 0, void 0, function* () {
             const requestFn = () => this.axiosInstance.request(config);
+            // 熔断器保护
             const circuitBreakerConfig = decoratorConfigs.circuitBreaker || this.defaultConfig.circuitBreaker;
             if (circuitBreakerConfig === null || circuitBreakerConfig === void 0 ? void 0 : circuitBreakerConfig.enabled) {
                 const circuitBreakerKey = this.generateCircuitBreakerKey(config);
@@ -372,29 +448,45 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
             }
         });
     }
+    /**
+     * 计算重试延迟
+     */
     calculateRetryDelay(retryCount, retryConfig) {
         if (retryConfig.retryDelay) {
             return retryConfig.retryDelay(retryCount);
         }
+        // 默认指数退避
         return Math.pow(2, retryCount) * 1000;
     }
+    /**
+     * 应用装饰器配置
+     */
     applyDecoratorConfig(config, decoratorContext) {
         if (!decoratorContext)
             return Object.assign({}, config);
         const httpClientConfig = decorators_1.HttpDecoratorUtils.getHttpClientOptions(decoratorContext.target);
         return Object.assign(Object.assign({}, config), httpClientConfig);
     }
+    /**
+     * 判断是否应该缓存请求
+     */
     shouldCacheRequest(config, cacheConfig) {
         var _a;
         const method = (_a = config.method) === null || _a === void 0 ? void 0 : _a.toLowerCase();
         return cacheConfig.cacheableMethods.includes(method || 'get');
     }
+    /**
+     * 生成熔断器键
+     */
     generateCircuitBreakerKey(config) {
         var _a;
         const method = ((_a = config.method) === null || _a === void 0 ? void 0 : _a.toUpperCase()) || 'UNKNOWN';
         const url = new URL(config.url || '', this.defaultConfig.baseURL || 'http://localhost');
         return `${method}:${url.host}${url.pathname}`;
     }
+    /**
+     * 更新请求统计
+     */
     updateStats(response) {
         var _a, _b;
         this.requestStats.totalRequests++;
@@ -412,6 +504,9 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
             this.requestStats.totalResponseTime += responseTime;
         }
     }
+    /**
+     * 更新错误统计
+     */
     updateErrorStats(error) {
         var _a;
         this.requestStats.totalRequests++;
@@ -427,6 +522,9 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
             }
         }
     }
+    /**
+     * 合并默认配置
+     */
     mergeWithDefaults(config) {
         const defaults = {
             baseURL: process.env.HTTP_CLIENT_BASE_URL,
@@ -453,7 +551,7 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
             },
             cache: {
                 enabled: true,
-                defaultTtl: 300000,
+                defaultTtl: 300000, // 5分钟
                 cacheableMethods: ['get'],
                 cacheableStatusCodes: [200, 201, 202, 204, 301, 302, 304],
                 options: {
@@ -479,6 +577,9 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
         };
         return this.deepMerge(defaults, config);
     }
+    /**
+     * 深度合并对象
+     */
     deepMerge(target, source) {
         const result = Object.assign({}, target);
         for (const key in source) {

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

@@ -1,10 +1,16 @@
 import { DataSource } from 'typeorm';
 import { HttpLogEntity, HttpLogQueryOptions, HttpLogStats } from '../entities/http-log.entity';
+/**
+ * HTTP日志查询服务
+ */
 export declare class HttpLogQueryService {
     private readonly dataSource?;
     private readonly logger;
     private logRepository;
     constructor(dataSource?: DataSource);
+    /**
+     * 查询HTTP日志
+     */
     findLogs(options?: HttpLogQueryOptions): Promise<{
         logs: HttpLogEntity[];
         total: number;
@@ -12,8 +18,17 @@ export declare class HttpLogQueryService {
         limit: number;
         totalPages: number;
     }>;
+    /**
+     * 根据ID查询单条日志
+     */
     findLogById(id: string, includeDetails?: boolean): Promise<HttpLogEntity | null>;
+    /**
+     * 根据请求ID查询日志
+     */
     findLogByRequestId(requestId: string): Promise<HttpLogEntity | null>;
+    /**
+     * 查询错误日志
+     */
     findErrorLogs(options?: {
         startDate?: Date;
         endDate?: Date;
@@ -25,6 +40,9 @@ export declare class HttpLogQueryService {
         logs: HttpLogEntity[];
         total: number;
     }>;
+    /**
+     * 查询慢请求日志
+     */
     findSlowRequests(minResponseTime?: number, options?: {
         page?: number;
         limit?: number;
@@ -32,6 +50,9 @@ export declare class HttpLogQueryService {
         logs: HttpLogEntity[];
         total: number;
     }>;
+    /**
+     * 查询重试日志
+     */
     findRetryLogs(options?: {
         minRetries?: number;
         page?: number;
@@ -40,6 +61,9 @@ export declare class HttpLogQueryService {
         logs: HttpLogEntity[];
         total: number;
     }>;
+    /**
+     * 获取统计信息
+     */
     getStats(options?: {
         startDate?: Date;
         endDate?: Date;
@@ -47,30 +71,89 @@ export declare class HttpLogQueryService {
         serviceName?: string;
         groupBy?: 'hour' | 'day' | 'week';
     }): Promise<HttpLogStats>;
+    /**
+     * 删除旧日志
+     */
     deleteOldLogs(daysToKeep?: number): Promise<number>;
+    /**
+     * 清空所有日志
+     */
     clearAllLogs(): Promise<number>;
+    /**
+     * 根据日志ID生成curl命令
+     * @param logId 日志ID
+     * @returns curl命令字符串
+     */
     generateCurlFromLog(logId: string): Promise<string | null>;
+    /**
+     * 根据请求ID生成curl命令
+     * @param requestId 请求ID
+     * @returns curl命令字符串
+     */
     generateCurlFromRequestId(requestId: string): Promise<string | null>;
+    /**
+     * 根据日志生成可重放的请求配置
+     * @param logId 日志ID
+     * @returns 请求配置对象
+     */
     generateReplayConfigFromLog(logId: string): Promise<any | null>;
+    /**
+     * 根据请求ID生成可重放的请求配置
+     * @param requestId 请求ID
+     * @returns 请求配置对象
+     */
     generateReplayConfigFromRequestId(requestId: string): Promise<any | null>;
+    /**
+     * 批量生成curl命令
+     * @param options 查询选项
+     * @returns curl命令数组
+     */
     generateBatchCurlCommands(options?: HttpLogQueryOptions): Promise<Array<{
         logId: string;
         requestId?: string;
         curlCommand: string;
     }>>;
+    /**
+     * 获取日志的完整重放信息
+     * @param logId 日志ID
+     * @returns 包含curl命令和重放配置的对象
+     */
     getLogReplayInfo(logId: string): Promise<{
         log: HttpLogEntity;
         curlCommand: string | null;
         replayConfig: any | null;
     } | null>;
+    /**
+     * 根据请求ID获取日志的完整重放信息
+     * @param requestId 请求ID
+     * @returns 包含curl命令和重放配置的对象
+     */
     getLogReplayInfoByRequestId(requestId: string): Promise<{
         log: HttpLogEntity;
         curlCommand: string | null;
         replayConfig: any | null;
     } | null>;
+    /**
+     * 初始化仓库
+     */
     private initializeRepository;
+    /**
+     * 计算响应时间百分位数
+     */
     private calculatePercentiles;
+    /**
+     * 格式化统计结果
+     */
     private formatStats;
+    /**
+     * 构建查询
+     */
     private buildQuery;
+    /**
+     * 清理敏感信息用于生成curl命令
+     * 移除或替换敏感的请求头和认证信息
+     * @param headers 原始请求头
+     * @returns 清理后的请求头
+     */
     private sanitizeHeadersForCurl;
 }