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

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

@@ -1,80 +1,129 @@
 import { AxiosRequestConfig, AxiosResponse } from 'axios';
-import { CacheOptions } from '../../cache/interfaces/cache-options.interface';
 import { LogCleanupConfig } from '../services/log-cleanup.service';
+import { SSRFProtectionConfig, URLValidationConfig } from '../utils/security-validator.util';
+/**
+ * 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;
+    /** 重试配置 */
+    retry?: Partial<RetryConfig>;
+    /** 熔断器配置 */
+    circuitBreaker?: Partial<CircuitBreakerConfig>;
+    /** 代理配置 */
+    proxy?: Partial<ProxyConfig>;
+    /** 日志配置 */
+    logging?: Partial<LoggingConfig>;
+    /** 日志清理配置 */
+    logCleanup?: Partial<LogCleanupConfig>;
+    /** 拦截器配置 */
+    interceptors?: Partial<InterceptorConfig>;
+    /** 连接池配置 */
+    connectionPool?: Partial<ConnectionPoolConfig>;
+    /** 安全配置 */
+    security?: {
+        /** URL验证配置 */
+        urlValidation?: Partial<URLValidationConfig>;
+        /** SSRF防护配置 */
+        ssrfProtection?: Partial<SSRFProtectionConfig>;
+        /** 是否启用安全验证 */
+        enabled?: boolean;
+    };
 }
+/**
+ * 重试配置
+ * 基于axios-retry库的配置
+ * 所有字段都是可选的
+ */
 export interface RetryConfig {
-    enabled: boolean;
+    enabled?: boolean;
     retries?: number;
     retryDelay?: (retryCount: number) => number;
     retryCondition?: (error: any) => boolean;
     shouldResetTimeout?: boolean;
     onRetry?: (retryCount: number, error: any, requestConfig: AxiosRequestConfig) => void;
 }
+/**
+ * 熔断器配置
+ * 类似Spring Cloud CircuitBreaker
+ * 所有字段都是可选的
+ */
 export interface CircuitBreakerConfig {
-    enabled: boolean;
-    failureThreshold: number;
-    recoveryTimeoutMs: number;
-    monitoringPeriodMs: number;
-    minimumThroughputThreshold: number;
-    countHalfOpenCalls: boolean;
-}
-export interface HttpCacheConfig {
-    enabled: boolean;
-    options?: Omit<CacheOptions, 'ttl' | 'namespace'>;
-    defaultTtl?: number;
-    cacheableMethods: string[];
-    cacheableStatusCodes: number[];
-    keyGenerator?: (config: AxiosRequestConfig) => string;
+    enabled?: boolean;
+    failureThreshold?: number;
+    recoveryTimeoutMs?: number;
+    monitoringPeriodMs?: number;
+    minimumThroughputThreshold?: number;
+    countHalfOpenCalls?: boolean;
 }
+/**
+ * 代理配置
+ * 所有字段都是可选的
+ */
 export interface ProxyConfig {
-    enabled: boolean;
+    enabled?: boolean;
+    /** 是否从环境变量读取代理配置 (HTTP_PROXY, HTTPS_PROXY, NO_PROXY) */
+    fromEnvironment?: boolean;
+    /** 手动指定的代理主机 (当 fromEnvironment 为 false 时使用) */
     host?: string;
+    /** 手动指定的代理端口 (当 fromEnvironment 为 false 时使用) */
     port?: number;
+    /** 代理协议 */
     protocol?: 'http' | 'https';
+    /** 代理认证信息 */
     auth?: {
-        username: string;
-        password: string;
+        username?: string;
+        password?: string;
     };
 }
+/**
+ * 日志配置
+ * 类似Spring Boot的logging配置
+ * 所有字段都是可选的
+ */
 export interface LoggingConfig {
-    enabled: boolean;
-    logRequests: boolean;
-    logResponses: boolean;
-    logErrors: boolean;
-    logHeaders: boolean;
-    logBody: boolean;
-    maxBodyLength: number;
-    sanitizeHeaders: string[];
-    logLevel: 'debug' | 'info' | 'warn' | 'error';
+    enabled?: boolean;
+    logRequests?: boolean;
+    logResponses?: boolean;
+    logErrors?: boolean;
+    logHeaders?: boolean;
+    logBody?: boolean;
+    maxBodyLength?: number;
+    sanitizeHeaders?: string[];
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
     databaseLogging?: {
-        enabled: boolean;
-        dataSource: string;
-        tableName: string;
+        enabled?: boolean;
+        dataSource?: string;
     };
 }
+/**
+ * 拦截器配置
+ * 所有字段都是可选的
+ */
 export interface InterceptorConfig {
-    requestInterceptors: string[];
-    responseInterceptors: string[];
-    errorInterceptors: string[];
+    requestInterceptors?: string[];
+    responseInterceptors?: string[];
+    errorInterceptors?: string[];
 }
+/**
+ * 连接池配置
+ * 所有字段都是可选的
+ */
 export interface ConnectionPoolConfig {
-    enabled: boolean;
-    maxSockets: number;
-    maxFreeSockets: number;
-    timeoutMs: number;
-    keepAlive: boolean;
+    enabled?: boolean;
+    maxSockets?: number;
+    maxFreeSockets?: number;
+    timeoutMs?: number;
+    keepAlive?: boolean;
 }
+/**
+ * HTTP请求上下文
+ * 类似Spring的RequestContextHolder
+ */
 export interface HttpContext {
     requestId: string;
     startTime: number;
@@ -85,6 +134,10 @@ export interface HttpContext {
     correlationId?: string;
     metadata: Record<string, any>;
 }
+/**
+ * HTTP请求日志实体
+ * 用于TypeORM数据库记录
+ */
 export interface HttpLogEntity {
     id: string;
     requestId: string;
@@ -101,12 +154,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;
@@ -115,9 +177,4 @@ export interface HttpStats {
     requestsByMethod: Record<HttpMethod, number>;
     requestsByStatus: Record<number, number>;
     circuitBreakerStats: Record<string, any>;
-    cacheStats: {
-        hits: number;
-        misses: number;
-        hitRate: number;
-    };
 }

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

@@ -1,31 +1,71 @@
-import { ApiClientConfig, ApiClientInstanceConfig, ApiClientRegistryConfig, AuthType, OAuth2Config, ResponseTransformerConfig } from '../interfaces/api-client-config.interface';
-import { HttpClientService } from './http-client.service';
+import { ApiClientConfig, ApiClientInstanceConfig, ApiClientRegistryConfig, AuthType, ResponseTransformerConfig } from '../interfaces/api-client-config.interface';
 import { HttpCircuitBreakerService } from './circuit-breaker.service';
 import { HttpLoggingService } from './logging.service';
-import { HttpCacheService } from './cache.service';
-export { ApiClientInstanceConfig, AuthType, OAuth2Config, ResponseTransformerConfig, };
+export { ApiClientInstanceConfig, AuthType, ResponseTransformerConfig, };
+/**
+ * API客户端注册服务
+ * 负责管理多个 HttpClientService 实例
+ */
 export declare class ApiClientRegistryService {
-    private readonly httpClientService;
     private readonly circuitBreakerService;
     private readonly loggingService;
-    private readonly cacheService;
     private readonly logger;
     private readonly clients;
     private readonly clientConfigs;
     private readonly globalDefaults;
-    constructor(httpClientService: HttpClientService, circuitBreakerService: HttpCircuitBreakerService, loggingService: HttpLoggingService, cacheService: HttpCacheService, globalConfig?: ApiClientRegistryConfig);
+    constructor(circuitBreakerService: HttpCircuitBreakerService, loggingService: HttpLoggingService, globalConfig?: ApiClientRegistryConfig);
+    /**
+     * 创建API客户端实例
+     * 使用 HttpClientService.createApiClient 静态方法创建
+     */
     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 +73,8 @@ export declare class ApiClientRegistryService {
             error?: string;
         }>;
     }>;
-    private createAxiosInstance;
-    private applyAuthentication;
-    private applyResponseTransformer;
-    private extractDataByPath;
+    /**
+     * 合并环境特定配置
+     */
     private mergeEnvironmentConfig;
 }