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

package/http-client/interfaces/http-client-config.interface.d.ts

@@ -1,18 +1,35 @@
 import { AxiosRequestConfig, AxiosResponse } from 'axios';
 import { CacheOptions } from '../../cache/interfaces/cache-options.interface';
 import { LogCleanupConfig } from '../services/log-cleanup.service';
+/**
+ * HTTP客户端配置接口
+ * 基于Spring Boot的@ConfigurationProperties设计理念
+ */
 export interface HttpClientConfig {
+    /** 基础配置 */
     baseURL?: string;
     timeout?: number;
+    /** 重试配置 */
     retry?: RetryConfig;
+    /** 熔断器配置 */
     circuitBreaker?: CircuitBreakerConfig;
+    /** 缓存配置 */
     cache?: HttpCacheConfig;
+    /** 代理配置 */
     proxy?: ProxyConfig;
+    /** 日志配置 */
     logging?: LoggingConfig;
+    /** 日志清理配置 */
     logCleanup?: LogCleanupConfig;
+    /** 拦截器配置 */
     interceptors?: InterceptorConfig;
+    /** 连接池配置 */
     connectionPool?: ConnectionPoolConfig;
 }
+/**
+ * 重试配置
+ * 基于axios-retry库的配置
+ */
 export interface RetryConfig {
     enabled: boolean;
     retries?: number;
@@ -21,6 +38,10 @@ export interface RetryConfig {
     shouldResetTimeout?: boolean;
     onRetry?: (retryCount: number, error: any, requestConfig: AxiosRequestConfig) => void;
 }
+/**
+ * 熔断器配置
+ * 类似Spring Cloud CircuitBreaker
+ */
 export interface CircuitBreakerConfig {
     enabled: boolean;
     failureThreshold: number;
@@ -29,14 +50,26 @@ export interface CircuitBreakerConfig {
     minimumThroughputThreshold: number;
     countHalfOpenCalls: boolean;
 }
+/**
+ * HTTP缓存配置
+ * 集成现有的三层缓存架构
+ */
 export interface HttpCacheConfig {
     enabled: boolean;
+    /** 缓存选项，使用core中的CacheOptions */
     options?: Omit<CacheOptions, 'ttl' | 'namespace'>;
+    /** 默认TTL（毫秒） */
     defaultTtl?: number;
+    /** 可缓存的方法 */
     cacheableMethods: string[];
+    /** 可缓存的状态码 */
     cacheableStatusCodes: number[];
+    /** 自定义缓存键生成器 */
     keyGenerator?: (config: AxiosRequestConfig) => string;
 }
+/**
+ * 代理配置
+ */
 export interface ProxyConfig {
     enabled: boolean;
     host?: string;
@@ -47,6 +80,10 @@ export interface ProxyConfig {
         password: string;
     };
 }
+/**
+ * 日志配置
+ * 类似Spring Boot的logging配置
+ */
 export interface LoggingConfig {
     enabled: boolean;
     logRequests: boolean;
@@ -63,11 +100,17 @@ export interface LoggingConfig {
         tableName: string;
     };
 }
+/**
+ * 拦截器配置
+ */
 export interface InterceptorConfig {
     requestInterceptors: string[];
     responseInterceptors: string[];
     errorInterceptors: string[];
 }
+/**
+ * 连接池配置
+ */
 export interface ConnectionPoolConfig {
     enabled: boolean;
     maxSockets: number;
@@ -75,6 +118,10 @@ export interface ConnectionPoolConfig {
     timeoutMs: number;
     keepAlive: boolean;
 }
+/**
+ * HTTP请求上下文
+ * 类似Spring的RequestContextHolder
+ */
 export interface HttpContext {
     requestId: string;
     startTime: number;
@@ -85,6 +132,10 @@ export interface HttpContext {
     correlationId?: string;
     metadata: Record<string, any>;
 }
+/**
+ * HTTP请求日志实体
+ * 用于TypeORM数据库记录
+ */
 export interface HttpLogEntity {
     id: string;
     requestId: string;
@@ -101,12 +152,21 @@ export interface HttpLogEntity {
     timestamp: Date;
     metadata: Record<string, any>;
 }
+/**
+ * 拦截器接口
+ */
 export interface HttpInterceptor {
     name: string;
     order: number;
     intercept(request: AxiosRequestConfig, next: () => Promise<AxiosResponse>): Promise<AxiosResponse>;
 }
+/**
+ * HTTP方法类型
+ */
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * HTTP请求统计信息
+ */
 export interface HttpStats {
     totalRequests: number;
     successfulRequests: number;

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

@@ -4,6 +4,9 @@ import { HttpCircuitBreakerService } from './circuit-breaker.service';
 import { HttpLoggingService } from './logging.service';
 import { HttpCacheService } from './cache.service';
 export { ApiClientInstanceConfig, AuthType, OAuth2Config, ResponseTransformerConfig, };
+/**
+ * API客户端注册服务
+ */
 export declare class ApiClientRegistryService {
     private readonly httpClientService;
     private readonly circuitBreakerService;
@@ -14,18 +17,57 @@ export declare class ApiClientRegistryService {
     private readonly clientConfigs;
     private readonly globalDefaults;
     constructor(httpClientService: HttpClientService, circuitBreakerService: HttpCircuitBreakerService, loggingService: HttpLoggingService, cacheService: HttpCacheService, globalConfig?: ApiClientRegistryConfig);
+    /**
+     * 创建API客户端实例
+     */
     createClient<T = any>(config: ApiClientInstanceConfig): T;
+    /**
+     * 获取已注册的客户端
+     */
     getClient<T = any>(name: string): T;
+    /**
+     * 列出所有已注册的客户端
+     */
     listClients(): string[];
+    /**
+     * 更新客户端配置
+     */
     updateClient(name: string, config: Partial<ApiClientConfig>): void;
+    /**
+     * 移除客户端
+     */
     removeClient(name: string): void;
+    /**
+     * 获取客户端配置
+     */
     getClientConfig(name: string): ApiClientConfig | undefined;
+    /**
+     * 获取所有客户端配置
+     */
     getAllClientConfigs(): Record<string, ApiClientConfig>;
+    /**
+     * 批量创建客户端
+     */
     createClients(configs: ApiClientInstanceConfig[]): void;
+    /**
+     * 获取全局配置
+     */
     getGlobalConfig(): ApiClientRegistryConfig;
+    /**
+     * 更新全局配置
+     */
     updateGlobalConfig(config: Partial<ApiClientRegistryConfig>): void;
+    /**
+     * 获取统计信息
+     */
     getAllStats(): Record<string, any>;
+    /**
+     * 重置所有统计信息
+     */
     resetAllStats(): void;
+    /**
+     * 健康检查
+     */
     healthCheck(): Promise<{
         status: 'healthy' | 'unhealthy';
         clients: Record<string, {
@@ -33,9 +75,24 @@ export declare class ApiClientRegistryService {
             error?: string;
         }>;
     }>;
+    /**
+     * 创建Axios实例
+     */
     private createAxiosInstance;
+    /**
+     * 应用鉴权配置
+     */
     private applyAuthentication;
+    /**
+     * 应用响应转换器
+     */
     private applyResponseTransformer;
+    /**
+     * 根据路径提取数据
+     */
     private extractDataByPath;
+    /**
+     * 合并环境特定配置
+     */
     private mergeEnvironmentConfig;
 }

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

@@ -31,6 +31,9 @@ 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客户端注册服务
+ */
 let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegistryService {
     constructor(httpClientService, circuitBreakerService, loggingService, cacheService, globalConfig = {}) {
         this.httpClientService = httpClientService;
@@ -60,6 +63,9 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
                 maxRecords: 1000000,
             }, enableGlobalRetry: true, enableCircuitBreaker: true }, globalConfig);
     }
+    /**
+     * 创建API客户端实例
+     */
     createClient(config) {
         const clientName = config.name;
         const existingClient = this.clients.get(clientName);
@@ -67,14 +73,21 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
             this.logger.warn(`Client '${clientName}' already exists. Use override: true to replace it.`);
             return existingClient;
         }
+        // 合并环境特定配置
         const finalConfig = this.mergeEnvironmentConfig(config);
+        // 创建Axios实例
         const axiosInstance = this.createAxiosInstance(finalConfig);
+        // 创建API客户端
         const client = new ApiClientInstance(clientName, finalConfig, axiosInstance, this.httpClientService, this.loggingService, this.cacheService);
+        // 存储客户端和配置
         this.clients.set(clientName, client);
         this.clientConfigs.set(clientName, finalConfig);
         this.logger.log(`Created API client: ${clientName}`);
         return client;
     }
+    /**
+     * 获取已注册的客户端
+     */
     getClient(name) {
         const client = this.clients.get(name);
         if (!client) {
@@ -82,9 +95,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 +111,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 +125,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 +141,9 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
         });
         return configs;
     }
+    /**
+     * 批量创建客户端
+     */
     createClients(configs) {
         configs.forEach((config) => {
             try {
@@ -122,13 +154,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 +177,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,6 +209,9 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
             };
         });
     }
+    /**
+     * 创建Axios实例
+     */
     createAxiosInstance(config) {
         var _a, _b, _c, _d, _e, _f;
         const axiosConfig = {
@@ -170,9 +221,12 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
             params: config.defaultParams,
         };
         const instance = axios_1.default.create(axiosConfig);
-        const clientName = config.name;
+        const clientName = config.name; // Capture client name for use in closures
+        // 配置请求拦截器
         instance.interceptors.request.use((config) => {
+            // 添加鉴权信息 - for now, skip async authentication to avoid type issues
             const authenticatedConfig = config;
+            // Add simple auth headers for basic cases
             if (config.auth) {
                 switch (config.auth.type) {
                     case api_client_config_interface_1.AuthType.BEARER_TOKEN:
@@ -194,6 +248,7 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
                         break;
                 }
             }
+            // 添加请求ID和上下文信息
             const context = context_extractor_util_1.ContextExtractor.getHttpContext();
             const requestId = context.requestId || (0, utils_1.generateRequestId)();
             authenticatedConfig.headers = authenticatedConfig.headers || {};
@@ -201,21 +256,26 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
             if (context.userId) {
                 authenticatedConfig.headers['X-User-ID'] = context.userId;
             }
+            // 添加API标识
             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);
         });
+        // 配置axios-retry
         if (((_b = config.retry) === null || _b === void 0 ? void 0 : _b.enabled) !== false &&
             this.globalDefaults.enableGlobalRetry) {
             (0, axios_retry_1.default)(instance, {
@@ -239,6 +299,9 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
         }
         return instance;
     }
+    /**
+     * 应用鉴权配置
+     */
     applyAuthentication(config, auth) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!auth) {
@@ -274,6 +337,8 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
                     break;
                 case api_client_config_interface_1.AuthType.OAUTH2:
                     const oauthConfig = auth.config;
+                    // OAuth2实现需要异步获取token
+                    // 这里简化处理，实际项目中可能需要更复杂的逻辑
                     authenticatedConfig.headers = Object.assign(Object.assign({}, authenticatedConfig.headers), { Authorization: `Bearer ${oauthConfig.clientSecret}` });
                     break;
                 case api_client_config_interface_1.AuthType.CUSTOM:
@@ -283,16 +348,22 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
             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}`);
@@ -300,6 +371,9 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
         }
         return response;
     }
+    /**
+     * 根据路径提取数据
+     */
     extractDataByPath(data, path) {
         const keys = path.split('.');
         let current = data;
@@ -311,6 +385,9 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
         }
         return current;
     }
+    /**
+     * 合并环境特定配置
+     */
     mergeEnvironmentConfig(config) {
         var _a;
         const env = process.env.NODE_ENV || 'development';
@@ -326,6 +403,9 @@ exports.ApiClientRegistryService = ApiClientRegistryService = ApiClientRegistryS
         logging_service_1.HttpLoggingService,
         cache_service_1.HttpCacheService, Object])
 ], ApiClientRegistryService);
+/**
+ * API客户端实例实现
+ */
 class ApiClientInstance {
     constructor(name, config, axiosInstance, httpClientService, loggingService, cacheService) {
         this.name = name;
@@ -373,11 +453,13 @@ class ApiClientInstance {
             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;
@@ -404,6 +486,7 @@ class ApiClientInstance {
         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/cache.service.d.ts

@@ -1,24 +1,76 @@
 import { AxiosRequestConfig, AxiosResponse } from 'axios';
 import { HttpCacheConfig } from '../interfaces/http-client-config.interface';
 import { CacheService } from '../../cache/cache.service';
+/**
+ * HTTP缓存服务
+ * 集成现有的三层缓存架构
+ */
 export declare class HttpCacheService {
     private readonly cacheService;
     private readonly logger;
     constructor(cacheService: CacheService);
+    /**
+     * 获取缓存的响应
+     */
     get(config: AxiosRequestConfig, cacheOptions: HttpCacheConfig): Promise<AxiosResponse | null>;
+    /**
+     * 缓存响应
+     */
     set(config: AxiosRequestConfig, response: AxiosResponse, cacheOptions: HttpCacheConfig): Promise<void>;
+    /**
+     * 清除缓存
+     */
     clear(pattern?: string): Promise<void>;
+    /**
+     * 获取缓存统计信息
+     */
     getStats(): Promise<any>;
+    /**
+     * 清理过期缓存
+     */
     cleanup(): Promise<void>;
+    /**
+     * 预热缓存
+     */
     warmup(urls: string[], headers?: Record<string, string>): Promise<void>;
+    /**
+     * 获取缓存命中率详情
+     */
     getDetailedStats(): Promise<any>;
+    /**
+     * 生成缓存键
+     */
     private generateCacheKey;
+    /**
+     * 构建完整的缓存键
+     */
     private buildCacheKey;
+    /**
+     * 映射缓存层
+     */
     private mapLayers;
+    /**
+     * 选择用于缓存键的头信息
+     */
     private selectHeadersForCacheKey;
+    /**
+     * 判断响应是否可缓存
+     */
     private isResponseCacheable;
+    /**
+     * 哈希对象
+     */
     private hashObject;
+    /**
+     * 计算综合命中率
+     */
     private calculateHitRate;
+    /**
+     * 获取最近的缓存活动
+     */
     private getRecentCacheActivity;
+    /**
+     * 生成缓存优化建议
+     */
     private generateRecommendations;
 }