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

package/http-client/examples/axios-config-extended.example.d.ts

@@ -0,0 +1,17 @@
+import { HttpClientConfig } from '../interfaces/http-client-config.interface';
+/**
+ * axiosConfig 透传配置示例
+ * 展示如何通过 axiosConfig 直接传递 Axios 原生配置
+ */
+export declare function httpAgentExample(): void;
+export declare function redirectAndValidationExample(): void;
+export declare function responseTypeExample(): void;
+export declare function sizeAndRateLimitExample(): void;
+export declare function paramsSerializationExample(): void;
+export declare function formSerializationExample(): void;
+export declare function securityOptionsExample(): void;
+export declare function abortControllerExample(): void;
+export declare function transitionalOptionsExample(): void;
+export declare function progressEventsExample(): void;
+export declare function comprehensiveConfigExample(): HttpClientConfig;
+export declare function environmentSpecificConfig(): HttpClientConfig;

package/http-client/examples/axios-config-extended.example.js

@@ -0,0 +1,313 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.httpAgentExample = httpAgentExample;
+exports.redirectAndValidationExample = redirectAndValidationExample;
+exports.responseTypeExample = responseTypeExample;
+exports.sizeAndRateLimitExample = sizeAndRateLimitExample;
+exports.paramsSerializationExample = paramsSerializationExample;
+exports.formSerializationExample = formSerializationExample;
+exports.securityOptionsExample = securityOptionsExample;
+exports.abortControllerExample = abortControllerExample;
+exports.transitionalOptionsExample = transitionalOptionsExample;
+exports.progressEventsExample = progressEventsExample;
+exports.comprehensiveConfigExample = comprehensiveConfigExample;
+exports.environmentSpecificConfig = environmentSpecificConfig;
+const http_1 = require("http");
+const https_1 = require("https");
+/**
+ * axiosConfig 透传配置示例
+ * 展示如何通过 axiosConfig 直接传递 Axios 原生配置
+ */
+// ============================================================================
+// 示例 1: 使用 httpAgent 和 httpsAgent 启用连接池
+// ============================================================================
+function httpAgentExample() {
+    const config = {
+        baseURL: 'https://api.example.com',
+        timeout: 30000,
+        // 通过 axiosConfig 透传 Axios 原生配置
+        axiosConfig: {
+            // 启用 HTTP keep-alive 连接池
+            httpAgent: new http_1.Agent({
+                keepAlive: true,
+                keepAliveMsecs: 1000,
+                maxSockets: 50,
+                maxFreeSockets: 10,
+                timeout: 60000,
+            }),
+            // 启用 HTTPS keep-alive 连接池
+            httpsAgent: new https_1.Agent({
+                keepAlive: true,
+                keepAliveMsecs: 1000,
+                maxSockets: 50,
+                maxFreeSockets: 10,
+                timeout: 60000,
+                // 可选：跳过证书验证（不推荐用于生产环境）
+                rejectUnauthorized: true,
+            }),
+        },
+    };
+    // 创建 HttpClientService 实例...
+}
+// ============================================================================
+// 示例 2: 配置重定向和响应验证
+// ============================================================================
+function redirectAndValidationExample() {
+    const config = {
+        baseURL: 'https://api.example.com',
+        axiosConfig: {
+            // 禁止自动跟随重定向
+            maxRedirects: 0,
+            // 或者限制重定向次数
+            // maxRedirects: 5,
+            // 自定义状态码验证逻辑
+            validateStatus: (status) => {
+                // 将 400-499 视为成功（不抛出异常）
+                return status >= 200 && status < 500;
+            },
+            // 重定向前回调
+            beforeRedirect: (options, { headers }) => {
+                // 可以在这里修改重定向请求
+                if (options.hostname === 'restricted.com') {
+                    throw new Error('Redirect to restricted domain not allowed');
+                }
+            },
+        },
+    };
+}
+// ============================================================================
+// 示例 3: 配置响应类型和数据转换
+// ============================================================================
+function responseTypeExample() {
+    const config = {
+        baseURL: 'https://api.example.com',
+        axiosConfig: {
+            // 指定响应类型
+            responseType: 'arraybuffer', // 'arraybuffer' | 'document' | 'json' | 'text' | 'stream' | 'blob'
+            responseEncoding: 'utf8',
+            // 自定义请求/响应转换器
+            transformRequest: [
+                (data, headers) => {
+                    // 在发送前修改数据
+                    if (typeof data === 'object') {
+                        // 自动添加时间戳
+                        data.timestamp = Date.now();
+                    }
+                    return JSON.stringify(data);
+                },
+                ...require('axios').defaults.transformRequest,
+            ],
+            transformResponse: [
+                (data) => {
+                    // 在接收后修改数据
+                    if (typeof data === 'string') {
+                        try {
+                            const parsed = JSON.parse(data);
+                            // 统一处理响应格式
+                            return parsed.data || parsed;
+                        }
+                        catch (_a) {
+                            return data;
+                        }
+                    }
+                    return data;
+                },
+                ...require('axios').defaults.transformResponse,
+            ],
+        },
+    };
+}
+// ============================================================================
+// 示例 4: 配置大小限制和速率限制
+// ============================================================================
+function sizeAndRateLimitExample() {
+    const config = {
+        baseURL: 'https://api.example.com',
+        axiosConfig: {
+            // 响应体大小限制（字节）
+            maxContentLength: 10 * 1024 * 1024, // 10MB
+            // 请求体大小限制（字节）
+            maxBodyLength: 5 * 1024 * 1024, // 5MB
+            // 速率限制 [上传 B/s, 下载 B/s]
+            maxRate: [1024 * 1024, 2 * 1024 * 1024], // 上传 1MB/s, 下载 2MB/s
+        },
+    };
+}
+// ============================================================================
+// 示例 5: 配置参数序列化
+// ============================================================================
+function paramsSerializationExample() {
+    const config = {
+        baseURL: 'https://api.example.com',
+        axiosConfig: {
+            paramsSerializer: {
+                // 自定义编码函数
+                encode: (param) => {
+                    return encodeURIComponent(param)
+                        .replace(/%40/gi, '@')
+                        .replace(/%3A/gi, ':')
+                        .replace(/%24/g, '$')
+                        .replace(/%2C/gi, ',')
+                        .replace(/%20/g, '+');
+                },
+                // 数组索引格式
+                indexes: true, // true=a[0]=b, false=a[]=b, null=a=b
+            },
+        },
+    };
+}
+// ============================================================================
+// 示例 6: 配置表单序列化
+// ============================================================================
+function formSerializationExample() {
+    const config = {
+        baseURL: 'https://api.example.com',
+        axiosConfig: {
+            formSerializer: {
+                // 自定义访问器
+                visitor: (value, key, path) => {
+                    // 自定义值转换逻辑
+                    if (value instanceof Date) {
+                        return value.toISOString();
+                    }
+                    return value;
+                },
+                // 使用点符号而不是括号
+                dots: true,
+                // 保留特殊结尾（如 {}）
+                metaTokens: true,
+                // 数组索引格式
+                indexes: true,
+            },
+        },
+    };
+}
+// ============================================================================
+// 示例 7: 配置安全选项
+// ============================================================================
+function securityOptionsExample() {
+    const config = {
+        baseURL: 'https://api.example.com',
+        axiosConfig: {
+            // 是否允许绝对 URL 覆盖 baseURL
+            allowAbsoluteUrls: true,
+            // 跨域请求是否携带凭证
+            withCredentials: true,
+            // 禁用自动解压
+            decompress: false,
+            // 使用不安全的 HTTP 解析器（允许无效的 HTTP 头）
+            // 警告：仅在与非标准 HTTP 实现交互时使用
+            insecureHTTPParser: false,
+        },
+    };
+}
+// ============================================================================
+// 示例 8: 使用 AbortSignal 取消请求
+// ============================================================================
+function abortControllerExample() {
+    const config = {
+        baseURL: 'https://api.example.com',
+        axiosConfig: {
+        // 可以在每次请求时动态设置
+        // signal: new AbortController().signal,
+        },
+    };
+    // 使用示例：
+    // const abortController = new AbortController();
+    // config.axiosConfig!.signal = abortController.signal;
+    //
+    // setTimeout(() => abortController.abort(), 5000); // 5秒后取消
+}
+// ============================================================================
+// 示例 9: 向后兼容选项
+// ============================================================================
+function transitionalOptionsExample() {
+    const config = {
+        baseURL: 'https://api.example.com',
+        axiosConfig: {
+            transitional: {
+                // 静默 JSON 解析错误（旧行为）
+                silentJSONParsing: false,
+                // 即使 responseType 不是 'json' 也尝试解析
+                forcedJSONParsing: true,
+                // 超时时抛出明确的 ETIMEDOUT 错误
+                clarifyTimeoutError: true,
+            },
+        },
+    };
+}
+// ============================================================================
+// 示例 10: 进度事件（浏览器环境）
+// ============================================================================
+function progressEventsExample() {
+    const config = {
+        baseURL: 'https://api.example.com',
+        axiosConfig: {
+            // 上传进度
+            onUploadProgress: (progressEvent) => {
+                const percentCompleted = Math.round((progressEvent.loaded * 100) / (progressEvent.total || 1));
+                console.log(`Upload ${percentCompleted}%`);
+            },
+            // 下载进度
+            onDownloadProgress: (progressEvent) => {
+                const percentCompleted = Math.round((progressEvent.loaded * 100) / (progressEvent.total || 1));
+                console.log(`Download ${percentCompleted}%`);
+            },
+        },
+    };
+}
+// ============================================================================
+// 示例 11: 综合配置
+// ============================================================================
+function comprehensiveConfigExample() {
+    const config = {
+        // 显式配置（优先级高）
+        baseURL: 'https://api.example.com',
+        timeout: 30000,
+        // 内置功能配置
+        retry: {
+            enabled: true,
+            retries: 3,
+        },
+        circuitBreaker: {
+            enabled: true,
+            failureThreshold: 5,
+        },
+        logging: {
+            enabled: true,
+            logLevel: 'info',
+        },
+        // Axios 原生配置透传（优先级低，会被显式配置覆盖）
+        axiosConfig: {
+            httpAgent: new http_1.Agent({ keepAlive: true }),
+            httpsAgent: new https_1.Agent({ keepAlive: true }),
+            maxRedirects: 5,
+            responseType: 'json',
+            validateStatus: (status) => status >= 200 && status < 300,
+            maxContentLength: 10 * 1024 * 1024,
+        },
+    };
+    return config;
+}
+// ============================================================================
+// 示例 12: 环境相关的配置
+// ============================================================================
+function environmentSpecificConfig() {
+    const isDevelopment = process.env.NODE_ENV === 'development';
+    const config = {
+        baseURL: isDevelopment
+            ? 'https://dev-api.example.com'
+            : 'https://api.example.com',
+        axiosConfig: {
+            // 开发环境使用更宽松的验证
+            validateStatus: isDevelopment
+                ? (status) => status >= 200 && status < 500
+                : (status) => status >= 200 && status < 300,
+            // 开发环境禁用 keep-alive 以便调试
+            httpAgent: isDevelopment
+                ? undefined
+                : new http_1.Agent({ keepAlive: true }),
+        },
+    };
+    return config;
+}

package/http-client/examples/index.d.ts

@@ -1,3 +1,5 @@
 export * from './basic-usage.example';
 export * from './advanced-usage.example';
 export * from './multi-api-configuration.example';
+export * from './axios-config-extended.example';
+export * from './ssl-certificate.example';

package/http-client/examples/index.js

@@ -17,3 +17,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./basic-usage.example"), exports);
 __exportStar(require("./advanced-usage.example"), exports);
 __exportStar(require("./multi-api-configuration.example"), exports);
+__exportStar(require("./axios-config-extended.example"), exports);
+__exportStar(require("./ssl-certificate.example"), exports);

package/http-client/examples/ssl-certificate.example.d.ts

@@ -0,0 +1,47 @@
+import { HttpClientConfig } from '../index';
+/**
+ * SSL/TLS 证书配置示例
+ * 解决自签名证书、客户端证书认证等问题
+ */
+export declare function disableSslVerificationExample(): void;
+export declare function selfSignedCaExample(): HttpClientConfig;
+export declare function multipleCaCertsExample(): HttpClientConfig;
+export declare function clientCertificateExample(): HttpClientConfig;
+export declare function tlsVersionAndCiphersExample(): HttpClientConfig;
+export declare function certFromEnvExample(): HttpClientConfig;
+export declare function productionSslConfigExample(): HttpClientConfig;
+export declare function environmentBasedSslConfig(): HttpClientConfig;
+export declare function handleCertExpirationExample(): HttpClientConfig;
+export declare function directHttpsAgentExample(): HttpClientConfig;
+export declare function sslErrorHandlingExample(): Promise<void>;
+export declare class DynamicCertificateManager {
+    private circuitBreakerService;
+    private loggingService;
+    private certPaths;
+    private httpClient;
+    private certCache;
+    private lastUpdate;
+    private cacheDuration;
+    constructor(circuitBreakerService: any, loggingService: any, certPaths: {
+        ca?: string;
+        cert?: string;
+        key?: string;
+    });
+    private loadCerts;
+    private buildConfig;
+    refreshCerts(): Promise<void>;
+    get(url: string): Promise<void>;
+}
+export declare const sslEnvVars: {
+    SSL_CA_PATH: string;
+    SSL_CLIENT_CERT_PATH: string;
+    SSL_CLIENT_KEY_PATH: string;
+    SSL_PASSPHRASE: string;
+    SSL_REJECT_UNAUTHORIZED: string;
+    SSL_MIN_VERSION: string;
+    SSL_CIPHERS: string;
+    SSL_CA_CERT: string;
+    SSL_CLIENT_CERT: string;
+    SSL_CLIENT_KEY: string;
+};
+export declare function diagnoseSslConfig(apiUrl: string): Promise<unknown>;

package/http-client/examples/ssl-certificate.example.js

@@ -0,0 +1,431 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sslEnvVars = exports.DynamicCertificateManager = void 0;
+exports.disableSslVerificationExample = disableSslVerificationExample;
+exports.selfSignedCaExample = selfSignedCaExample;
+exports.multipleCaCertsExample = multipleCaCertsExample;
+exports.clientCertificateExample = clientCertificateExample;
+exports.tlsVersionAndCiphersExample = tlsVersionAndCiphersExample;
+exports.certFromEnvExample = certFromEnvExample;
+exports.productionSslConfigExample = productionSslConfigExample;
+exports.environmentBasedSslConfig = environmentBasedSslConfig;
+exports.handleCertExpirationExample = handleCertExpirationExample;
+exports.directHttpsAgentExample = directHttpsAgentExample;
+exports.sslErrorHandlingExample = sslErrorHandlingExample;
+exports.diagnoseSslConfig = diagnoseSslConfig;
+const index_1 = require("../index");
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * SSL/TLS 证书配置示例
+ * 解决自签名证书、客户端证书认证等问题
+ */
+// ============================================================================
+// 示例 1: 禁用证书验证（仅用于开发环境）
+// ============================================================================
+function disableSslVerificationExample() {
+    const config = {
+        baseURL: 'https://self-signed.example.com',
+        timeout: 30000,
+        axiosConfig: {
+            ssl: {
+                // ⚠️ 危险：禁用证书验证，仅用于开发/测试环境
+                // 生产环境严禁使用！
+                rejectUnauthorized: false,
+            },
+        },
+    };
+    // 使用示例
+    // const httpClient = new HttpClientService(circuitBreakerService, loggingService, null, config);
+    // return httpClient.get('/api/data');
+}
+// ============================================================================
+// 示例 2: 使用自签名 CA 证书（推荐）
+// ============================================================================
+function selfSignedCaExample() {
+    // 方式1: 从文件读取 CA 证书
+    const caCert = (0, fs_1.readFileSync)((0, path_1.join)(process.cwd(), 'certs/ca.crt'));
+    const config = {
+        baseURL: 'https://self-signed.example.com',
+        timeout: 30000,
+        axiosConfig: {
+            ssl: {
+                // 指定信任的 CA 证书
+                ca: caCert,
+                // 仍然验证证书，但信任我们的自签名 CA
+                rejectUnauthorized: true,
+            },
+        },
+    };
+    return config;
+}
+// ============================================================================
+// 示例 3: 使用多个 CA 证书
+// ============================================================================
+function multipleCaCertsExample() {
+    const ca1 = (0, fs_1.readFileSync)((0, path_1.join)(process.cwd(), 'certs/ca1.crt'), 'utf8');
+    const ca2 = (0, fs_1.readFileSync)((0, path_1.join)(process.cwd(), 'certs/ca2.crt'), 'utf8');
+    const ca3 = (0, fs_1.readFileSync)((0, path_1.join)(process.cwd(), 'certs/ca3.crt'), 'utf8');
+    const config = {
+        baseURL: 'https://multi-ca.example.com',
+        timeout: 30000,
+        axiosConfig: {
+            ssl: {
+                // 支持多个 CA 证书
+                ca: [ca1, ca2, ca3],
+                rejectUnauthorized: true,
+            },
+        },
+    };
+    return config;
+}
+// ============================================================================
+// 示例 4: 使用客户端证书（双向 TLS 认证）
+// ============================================================================
+function clientCertificateExample() {
+    const caCert = (0, fs_1.readFileSync)((0, path_1.join)(process.cwd(), 'certs/ca.crt'));
+    const clientCert = (0, fs_1.readFileSync)((0, path_1.join)(process.cwd(), 'certs/client.crt'));
+    const clientKey = (0, fs_1.readFileSync)((0, path_1.join)(process.cwd(), 'certs/client.key'));
+    const config = {
+        baseURL: 'https://mutual-tls.example.com',
+        timeout: 30000,
+        axiosConfig: {
+            ssl: {
+                // CA 证书（验证服务器）
+                ca: caCert,
+                // 客户端证书（服务器验证客户端）
+                cert: clientCert,
+                // 客户端私钥
+                key: clientKey,
+                // 如果私钥有密码
+                passphrase: 'your-private-key-password',
+                rejectUnauthorized: true,
+            },
+        },
+    };
+    return config;
+}
+// ============================================================================
+// 示例 5: 配置 TLS 版本和加密套件
+// ============================================================================
+function tlsVersionAndCiphersExample() {
+    const config = {
+        baseURL: 'https://secure-api.example.com',
+        timeout: 30000,
+        axiosConfig: {
+            ssl: {
+                // 限制 TLS 版本
+                minVersion: 'TLSv1.2',
+                maxVersion: 'TLSv1.3',
+                // 指定加密套件
+                ciphers: 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:' +
+                    'ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384',
+                rejectUnauthorized: true,
+            },
+        },
+    };
+    return config;
+}
+// ============================================================================
+// 示例 6: 从环境变量加载证书
+// ============================================================================
+function certFromEnvExample() {
+    const config = {
+        baseURL: process.env.API_BASE_URL,
+        timeout: 30000,
+        axiosConfig: {
+            ssl: {
+                // CA 证书路径或内容
+                ca: process.env.SSL_CA_CERT,
+                // 客户端证书
+                cert: process.env.SSL_CLIENT_CERT,
+                // 客户端私钥
+                key: process.env.SSL_CLIENT_KEY,
+                // 私钥密码
+                passphrase: process.env.SSL_PASSPHRASE,
+                rejectUnauthorized: true,
+            },
+        },
+    };
+    return config;
+}
+// ============================================================================
+// 示例 7: 完整的 SSL 配置（生产环境）
+// ============================================================================
+function productionSslConfigExample() {
+    // 在实际应用中，证书应该从安全的配置中心加载
+    const caCert = (0, fs_1.readFileSync)(process.env.SSL_CA_PATH || '/etc/ssl/certs/ca.pem');
+    const clientCert = (0, fs_1.readFileSync)(process.env.SSL_CLIENT_CERT_PATH || '/etc/ssl/certs/client.pem');
+    const clientKey = (0, fs_1.readFileSync)(process.env.SSL_CLIENT_KEY_PATH || '/etc/ssl/private/client.key');
+    return {
+        baseURL: process.env.API_BASE_URL,
+        timeout: 30000,
+        // 重试配置
+        retry: {
+            enabled: true,
+            retries: 3,
+        },
+        // 熔断器配置
+        circuitBreaker: {
+            enabled: true,
+            failureThreshold: 5,
+        },
+        // 日志配置
+        logging: {
+            enabled: true,
+            logLevel: 'info',
+        },
+        // SSL 配置
+        axiosConfig: {
+            ssl: {
+                ca: caCert,
+                cert: clientCert,
+                key: clientKey,
+                passphrase: process.env.SSL_PASSPHRASE,
+                rejectUnauthorized: true, // 生产环境必须验证证书
+                minVersion: 'TLSv1.2', // 最低 TLS 1.2
+            },
+        },
+    };
+}
+// ============================================================================
+// 示例 8: 不同环境使用不同 SSL 配置
+// ============================================================================
+function environmentBasedSslConfig() {
+    const isDevelopment = process.env.NODE_ENV === 'development';
+    const isTest = process.env.NODE_ENV === 'test';
+    const baseConfig = {
+        baseURL: process.env.API_BASE_URL,
+        timeout: 30000,
+    };
+    // 开发/测试环境：禁用证书验证
+    if (isDevelopment || isTest) {
+        baseConfig.axiosConfig = {
+            ssl: {
+                rejectUnauthorized: false, // 仅用于开发/测试
+            },
+        };
+    }
+    else {
+        // 生产环境：使用证书验证
+        baseConfig.axiosConfig = {
+            ssl: {
+                ca: (0, fs_1.readFileSync)(process.env.SSL_CA_PATH),
+                rejectUnauthorized: true,
+                minVersion: 'TLSv1.2',
+            },
+        };
+    }
+    return baseConfig;
+}
+// ============================================================================
+// 示例 9: 处理证书过期问题
+// ============================================================================
+function handleCertExpirationExample() {
+    const config = {
+        baseURL: 'https://api.example.com',
+        timeout: 30000,
+        axiosConfig: {
+            ssl: {
+                // 设置服务器名称（SNI）
+                servername: 'api.example.com',
+                // 如果服务器证书过期但仍需要连接（不推荐）
+                rejectUnauthorized: process.env.ALLOW_EXPIRED_CERT === 'true',
+            },
+        },
+        // 重试配置：证书问题通常不需要重试
+        retry: {
+            enabled: true,
+            retries: 1,
+            retryCondition: (error) => {
+                // 不重试证书错误
+                if (error.code === 'CERT_HAS_EXPIRED' ||
+                    error.code === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE') {
+                    return false;
+                }
+                return !error.response || error.response.status >= 500;
+            },
+        },
+    };
+    return config;
+}
+// ============================================================================
+// 示例 10: 使用 https.Agent 直接配置（兼容旧方式）
+// ============================================================================
+function directHttpsAgentExample() {
+    const https = require('https');
+    const fs = require('fs');
+    // 直接创建 https.Agent
+    const httpsAgent = new https.Agent({
+        ca: fs.readFileSync('/path/to/ca.crt'),
+        cert: fs.readFileSync('/path/to/client.crt'),
+        key: fs.readFileSync('/path/to/client.key'),
+        rejectUnauthorized: true,
+        keepAlive: true,
+    });
+    const config = {
+        baseURL: 'https://api.example.com',
+        timeout: 30000,
+        axiosConfig: {
+            // 直接使用 httpsAgent
+            httpsAgent: httpsAgent,
+        },
+    };
+    return config;
+}
+// ============================================================================
+// 示例 11: 错误处理和调试
+// ============================================================================
+function sslErrorHandlingExample() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const config = {
+            baseURL: 'https://self-signed.example.com',
+            timeout: 30000,
+            axiosConfig: {
+                ssl: {
+                    rejectUnauthorized: true, // 先启用验证
+                    ca: (0, fs_1.readFileSync)((0, path_1.join)(process.cwd(), 'certs/ca.crt')),
+                },
+            },
+        };
+        // const httpClient = new HttpClientService(circuitBreakerService, loggingService, null, config);
+        try {
+            // return await httpClient.get('/api/data');
+        }
+        catch (error) {
+            // 常见的 SSL 错误码
+            switch (error.code) {
+                case 'CERT_HAS_EXPIRED':
+                    console.error('证书已过期');
+                    break;
+                case 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY':
+                    console.error('无法获取本地颁发者证书，请检查 CA 配置');
+                    break;
+                case 'SELF_SIGNED_CERT_IN_CHAIN':
+                    console.error('证书链中有自签名证书，请添加 CA 证书');
+                    break;
+                case 'DEPTH_ZERO_SELF_SIGNED_CERT':
+                    console.error('自签名证书，需要设置 rejectUnauthorized: false 或添加 CA');
+                    break;
+                case 'CERT_REVOKED':
+                    console.error('证书已被吊销');
+                    break;
+                default:
+                    console.error('SSL 错误:', error.message);
+            }
+            throw error;
+        }
+    });
+}
+// ============================================================================
+// 示例 12: 动态加载证书（支持证书更新）
+// ============================================================================
+class DynamicCertificateManager {
+    constructor(circuitBreakerService, loggingService, certPaths) {
+        this.circuitBreakerService = circuitBreakerService;
+        this.loggingService = loggingService;
+        this.certPaths = certPaths;
+        this.certCache = {};
+        this.lastUpdate = 0;
+        this.cacheDuration = 5 * 60 * 1000; // 5分钟
+        this.httpClient = new index_1.HttpClientService(this.circuitBreakerService, this.loggingService, null, this.buildConfig());
+    }
+    loadCerts() {
+        const now = Date.now();
+        if (now - this.lastUpdate < this.cacheDuration && Object.keys(this.certCache).length > 0) {
+            return this.certCache;
+        }
+        // 重新加载证书
+        if (this.certPaths.ca) {
+            this.certCache.ca = (0, fs_1.readFileSync)(this.certPaths.ca);
+        }
+        if (this.certPaths.cert) {
+            this.certCache.cert = (0, fs_1.readFileSync)(this.certPaths.cert);
+        }
+        if (this.certPaths.key) {
+            this.certCache.key = (0, fs_1.readFileSync)(this.certPaths.key);
+        }
+        this.lastUpdate = now;
+        return this.certCache;
+    }
+    buildConfig() {
+        const certs = this.loadCerts();
+        return {
+            baseURL: process.env.API_BASE_URL,
+            timeout: 30000,
+            axiosConfig: {
+                ssl: Object.assign(Object.assign({}, certs), { rejectUnauthorized: true }),
+            },
+        };
+    }
+    // 重新创建客户端以使用新证书
+    refreshCerts() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.lastUpdate = 0;
+            const config = this.buildConfig();
+            // 在实际应用中，可能需要重新创建 HttpClientService 实例
+            // 或者提供更新配置的方法
+        });
+    }
+    get(url) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 每次请求前检查是否需要更新证书
+            this.loadCerts();
+            // return this.httpClient.get(url);
+        });
+    }
+}
+exports.DynamicCertificateManager = DynamicCertificateManager;
+// ============================================================================
+// 环境变量配置示例
+// ============================================================================
+exports.sslEnvVars = {
+    // SSL 配置
+    SSL_CA_PATH: '/path/to/ca.crt', // CA 证书文件路径
+    SSL_CLIENT_CERT_PATH: '/path/to/client.crt', // 客户端证书文件路径
+    SSL_CLIENT_KEY_PATH: '/path/to/client.key', // 客户端私钥文件路径
+    SSL_PASSPHRASE: 'your-passphrase', // 私钥密码
+    SSL_REJECT_UNAUTHORIZED: 'true', // 是否验证证书（true/false）
+    SSL_MIN_VERSION: 'TLSv1.2', // 最低 TLS 版本
+    SSL_CIPHERS: 'ECDHE-RSA-AES128-GCM-SHA256:...', // 加密套件
+    // 或者直接提供证书内容
+    SSL_CA_CERT: '-----BEGIN CERTIFICATE-----\n...', // CA 证书内容
+    SSL_CLIENT_CERT: '-----BEGIN CERTIFICATE-----\n...', // 客户端证书内容
+    SSL_CLIENT_KEY: '-----BEGIN PRIVATE KEY-----\n...', // 客户端私钥内容
+};
+// ============================================================================
+// 快速诊断脚本
+// ============================================================================
+function diagnoseSslConfig(apiUrl) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const https = require('https');
+        return new Promise((resolve, reject) => {
+            const req = https.get(apiUrl, (res) => {
+                const cert = res.socket.getPeerCertificate();
+                console.log('服务器证书信息:');
+                console.log('  主题:', cert.subject);
+                console.log('  颁发者:', cert.issuer);
+                console.log('  有效期:', new Date(cert.valid_from), '至', new Date(cert.valid_to));
+                console.log('  序列号:', cert.serialNumber);
+                resolve(cert);
+            });
+            req.on('error', (error) => {
+                console.error('SSL 连接失败:', error.code, error.message);
+                reject(error);
+            });
+        });
+    });
+}
+// 使用示例：
+// diagnoseSslConfig('https://self-signed.example.com')
+//   .then(cert => console.log('证书 OK'))
+//   .catch(err => console.log('证书错误'));

package/http-client/index.d.ts

@@ -1,4 +1,4 @@
-export { HttpClientConfig, RetryConfig, CircuitBreakerConfig, ProxyConfig, LoggingConfig, InterceptorConfig, ConnectionPoolConfig, HttpContext, HttpInterceptor, HttpMethod, HttpStats, } from './interfaces/http-client-config.interface';
+export { HttpClientConfig, AxiosNativeConfig, SslCertificateConfig, RetryConfig, CircuitBreakerConfig, ProxyConfig, LoggingConfig, InterceptorConfig, ConnectionPoolConfig, HttpContext, HttpInterceptor, HttpMethod, HttpStats, } from './interfaces/http-client-config.interface';
 export * from './interfaces/api-client-config.interface';
 export { HttpLogEntity, RetryRecord } from './entities';
 export * from './decorators';

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

@@ -116,17 +116,36 @@ export interface ResponseTransformerConfig {
 }
 /**
  * API客户端配置
+ * 用于创建多个具有不同配置的 HttpClient 实例
  */
 export interface ApiClientConfig {
     /** API名称（用于标识和日志） */
     name: string;
     /** 基础URL */
     baseURL: string;
-    /** HTTP客户端基础配置 */
-    httpConfig?: HttpClientConfig;
-    /** 鉴权配置 */
+    /**
+     * HttpClient 配置
+     * 包含所有 HttpClientConfig 的配置项（timeout, retry, logging, axiosConfig 等）
+     */
+    httpConfig?: Partial<HttpClientConfig>;
+    /**
+     * 重试配置（快捷方式，会合并到 httpConfig.retry）
+     * @deprecated 使用 httpConfig.retry 代替
+     */
+    retry?: {
+        enabled?: boolean;
+        retries?: number;
+        retryCondition?: (error: any) => boolean;
+    };
+    /**
+     * 鉴权配置
+     * API客户端特有的鉴权功能
+     */
     auth?: AuthConfig;
-    /** 响应转换配置 */
+    /**
+     * 响应转换配置
+     * API客户端特有的响应处理
+     */
     responseTransformer?: ResponseTransformerConfig;
     /** 默认请求头 */
     defaultHeaders?: Record<string, string>;
@@ -138,20 +157,12 @@ export interface ApiClientConfig {
         response?: Array<(response: AxiosResponse) => AxiosResponse | Promise<AxiosResponse>>;
         error?: Array<(error: any) => any>;
     };
-    /** 重试配置（覆盖全局配置） */
-    retry?: {
-        enabled?: boolean;
-        retries?: number;
-        retryCondition?: (error: any) => boolean;
-    };
     /** 是否启用响应验证 */
     enableValidation?: boolean;
     /** 响应时间警告阈值（毫秒） */
     responseTimeWarningThreshold?: number;
     /** 自定义标签（用于分类和查询） */
     tags?: string[];
-    /** 是否启用详细日志 */
-    enableDetailedLogging?: boolean;
 }
 /**
  * API客户端实例配置

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

@@ -1,6 +1,73 @@
 import { AxiosRequestConfig, AxiosResponse } from 'axios';
 import { LogCleanupConfig } from '../services/log-cleanup.service';
 import { SSRFProtectionConfig, URLValidationConfig } from '../utils/security-validator.util';
+import type { AgentOptions } from 'https';
+/**
+ * SSL/TLS 证书配置
+ * 兼容 Node.js https.Agent 的选项
+ * 参考: https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options
+ */
+export interface SslCertificateConfig extends Partial<Omit<AgentOptions, 'host' | 'port' | 'path'>> {
+    /**
+     * 是否禁用证书验证（仅用于开发/测试环境）
+     * 警告：设置为 true 会使连接不安全，生产环境严禁使用
+     */
+    rejectUnauthorized?: boolean;
+    /**
+     * CA 证书内容（PEM 格式）
+     * 可以是单个证书或多个证书的字符串
+     */
+    ca?: string | string[] | Buffer;
+    /**
+     * 客户端证书内容（PEM 格式）
+     */
+    cert?: string | string[] | Buffer;
+    /**
+     * 客户端私钥内容（PEM 格式）
+     */
+    key?: string | string[] | Buffer;
+    /**
+     * 私钥密码
+     */
+    passphrase?: string;
+    /**
+     * 服务器名称（用于 SNI）
+     */
+    servername?: string;
+    /**
+     * 支持的 TLS 版本
+     */
+    minVersion?: 'TLSv1' | 'TLSv1.1' | 'TLSv1.2' | 'TLSv1.3';
+    maxVersion?: 'TLSv1' | 'TLSv1.1' | 'TLSv1.2' | 'TLSv1.3';
+    /**
+     * 支持的加密套件
+     */
+    ciphers?: string;
+    /**
+     * 是否支持 DH 参数
+     */
+    dhparam?: string | Buffer;
+    /**
+     * 是否使用安全 renegotiation
+     */
+    secureOptions?: number;
+}
+/**
+ * Axios 原生配置透传
+ * 基于 AxiosRequestConfig，排除已在 HttpClientConfig 中定义的字段
+ *
+ * 使用方式：
+ * - 直接传 Axios 原生配置对象
+ * - 类型安全，支持所有 Axios 配置项
+ * - ssl 配置会被自动转换为 httpsAgent
+ */
+export type AxiosNativeConfig = Omit<AxiosRequestConfig, 'baseURL' | 'timeout' | 'proxy' | 'url' | 'method' | 'data' | 'headers' | 'params'> & {
+    /**
+     * SSL/TLS 证书配置（简化版）
+     * 会自动转换为 httpsAgent，优先级高于直接指定的 httpsAgent
+     */
+    ssl?: SslCertificateConfig;
+};
 /**
  * HTTP客户端配置接口
  * 基于Spring Boot的@ConfigurationProperties设计理念
@@ -33,6 +100,12 @@ export interface HttpClientConfig {
         /** 是否启用安全验证 */
         enabled?: boolean;
     };
+    /**
+     * Axios 原生配置透传
+     * 用于直接传递 Axios 支持的任何配置项，提供最大灵活性
+     * 优先级低于上述显式配置，会进行深度合并
+     */
+    axiosConfig?: AxiosNativeConfig;
 }
 /**
  * 重试配置

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

@@ -19,6 +19,11 @@ export declare class ApiClientRegistryService {
      * 使用 HttpClientService.createApiClient 静态方法创建
      */
     createClient<T = any>(config: ApiClientInstanceConfig): T;
+    /**
+     * 深度合并配置（已废弃，不再需要）
+     * @deprecated 配置结构简化后不再需要此方法
+     */
+    private deepMergeConfigs;
     /**
      * 获取已注册的客户端
      */

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

@@ -62,7 +62,6 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
      * 使用 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) {
@@ -71,6 +70,15 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
         }
         // 合并环境特定配置
         const finalConfig = this.mergeEnvironmentConfig(config);
+        // 构建 HttpClient 配置
+        // 1. 从全局默认配置开始
+        // 2. 合并 ApiClient 的 httpConfig
+        // 3. 应用 ApiClient 特有的 retry 配置（兼容旧代码）
+        let mergedHttpConfig = Object.assign(Object.assign({}, this.globalDefaults.globalDefaults), finalConfig.httpConfig);
+        // 兼容：如果 ApiClientConfig 顶层有 retry 配置，合并到 httpConfig.retry
+        if (finalConfig.retry) {
+            mergedHttpConfig.retry = Object.assign(Object.assign({}, mergedHttpConfig.retry), finalConfig.retry);
+        }
         // 使用静态工厂方法创建 HttpClientService 实例
         const httpClient = http_client_service_1.HttpClientService.createApiClient({
             circuitBreakerService: this.circuitBreakerService,
@@ -78,30 +86,7 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
         }, {
             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),
+            httpConfig: mergedHttpConfig,
             auth: finalConfig.auth,
         });
         // 存储客户端和配置
@@ -110,6 +95,13 @@ let ApiClientRegistryService = ApiClientRegistryService_1 = class ApiClientRegis
         this.logger.log(`Created API client: ${clientName}`);
         return httpClient;
     }
+    /**
+     * 深度合并配置（已废弃，不再需要）
+     * @deprecated 配置结构简化后不再需要此方法
+     */
+    deepMergeConfigs(defaults, userConfig) {
+        return Object.assign(Object.assign({}, defaults), userConfig);
+    }
     /**
      * 获取已注册的客户端
      */

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

@@ -135,6 +135,7 @@ export declare class HttpClientService {
     private calculateRetryDelay;
     /**
      * 应用装饰器配置
+     * 只在装饰器配置值有效时才覆盖请求配置
      */
     private applyDecoratorConfig;
     /**
@@ -147,6 +148,7 @@ export declare class HttpClientService {
     private mergeWithDefaults;
     /**
      * 深度合并对象
+     * 只在源值有效（非 undefined）时才覆盖目标值
      */
     private deepMerge;
     /**

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

@@ -17,6 +17,17 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 var HttpClientService_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpClientService = void 0;
@@ -68,14 +79,23 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
      * @returns HttpClientService 实例
      */
     static createApiClient(dependencies, config) {
-        return new HttpClientService_1(dependencies.circuitBreakerService, dependencies.loggingService, dependencies.redisLockService, Object.assign({ baseURL: config.baseURL, timeout: config.timeout || 30000 }, config.httpConfig), config.name, config.auth);
+        // 构建配置，只在值有效时才覆盖
+        const mergedConfig = Object.assign({}, config.httpConfig);
+        // 只在显式提供且值有效时才覆盖
+        if (config.baseURL !== undefined) {
+            mergedConfig.baseURL = config.baseURL;
+        }
+        if (config.timeout !== undefined) {
+            mergedConfig.timeout = config.timeout;
+        }
+        return new HttpClientService_1(dependencies.circuitBreakerService, dependencies.loggingService, dependencies.redisLockService, mergedConfig, config.name, config.auth);
     }
     /**
      * 执行HTTP请求
      */
     request(config, decoratorContext, clientName) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
             // Use the instance's clientName as fallback if not provided
             const effectiveClientName = clientName || this.clientName;
             // If no decorator context provided, try to get it from CallStackExtractor
@@ -83,22 +103,36 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
             const effectiveDecoratorContext = decoratorContext || call_stack_extractor_util_1.CallStackExtractor.getDecoratorContext();
             // ========== 安全验证开始 ==========
             // 构造完整URL进行验证
-            const fullURL = config.url || '';
+            const requestURL = config.url || '';
             const baseURL = config.baseURL || this.defaultConfig.baseURL || '';
-            // 执行URL安全验证
-            const sanitizeResult = security_validator_util_1.SecurityValidator.sanitizeURL(fullURL, {
-                urlConfig: (_a = this.defaultConfig.security) === null || _a === void 0 ? void 0 : _a.urlValidation,
-                ssrfConfig: (_b = this.defaultConfig.security) === null || _b === void 0 ? void 0 : _b.ssrfProtection,
-            });
-            if (!sanitizeResult.valid) {
-                const error = new Error(`URL validation failed: ${sanitizeResult.error}`);
-                this.logger.error(`URL validation failed for ${fullURL}: ${sanitizeResult.error}`);
-                throw error;
+            // 构建完整的URL用于验证
+            let fullURL = requestURL;
+            if (requestURL && !requestURL.startsWith('http://') && !requestURL.startsWith('https://') && baseURL) {
+                // 处理相对URL
+                try {
+                    fullURL = new URL(requestURL, baseURL).href;
+                }
+                catch (_m) {
+                    // 如果URL构建失败，使用原始URL
+                    fullURL = requestURL;
+                }
             }
-            // 如果URL被修改，更新配置
-            if (sanitizeResult.url !== fullURL) {
-                config.url = sanitizeResult.url;
-                this.logger.debug(`URL sanitized from "${fullURL}" to "${sanitizeResult.url}"`);
+            // 执行URL安全验证（只对完整URL进行验证）
+            if (fullURL && (fullURL.startsWith('http://') || fullURL.startsWith('https://'))) {
+                const sanitizeResult = security_validator_util_1.SecurityValidator.sanitizeURL(fullURL, {
+                    urlConfig: (_a = this.defaultConfig.security) === null || _a === void 0 ? void 0 : _a.urlValidation,
+                    ssrfConfig: (_b = this.defaultConfig.security) === null || _b === void 0 ? void 0 : _b.ssrfProtection,
+                });
+                if (!sanitizeResult.valid) {
+                    const error = new Error(`URL validation failed: ${sanitizeResult.error}`);
+                    this.logger.error(`URL validation failed for ${fullURL}: ${sanitizeResult.error}`);
+                    throw error;
+                }
+                // 如果URL被修改，更新配置
+                if (sanitizeResult.url !== fullURL) {
+                    // 仅更新完整URL，保留原始的相对路径
+                    this.logger.debug(`URL sanitized from "${fullURL}" to "${sanitizeResult.url}"`);
+                }
             }
             // ========== 安全验证结束 ==========
             // Capture the calling context information
@@ -156,7 +190,7 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
                     this.loggingService.logRequestSuccess(response, startTime, requestId, loggingOptions, databaseLogging, retryRecorder.getRecords(), circuitBreakerState, decoratorContext, effectiveClientName, callingContext);
                 }
                 // 更新统计信息
-                this.updateRequestStats(true, Date.now() - startTime, response.config.method, response.status);
+                this.updateRequestStats(true, Date.now() - startTime, ((_f = response.config) === null || _f === void 0 ? void 0 : _f.method) || 'GET', response.status);
                 return response.data;
             }
             catch (error) {
@@ -164,16 +198,16 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
                 const decoratorLogging = effectiveDecoratorContext
                     ? decorators_1.HttpDecoratorUtils.getLoggingOptions(effectiveDecoratorContext.target, effectiveDecoratorContext.propertyKey)
                     : {};
-                const loggingOptions = Object.assign(Object.assign(Object.assign({}, this.defaultConfig.logging), decoratorLogging), { databaseLogging: (_f = this.defaultConfig.logging) === null || _f === void 0 ? void 0 : _f.databaseLogging });
+                const loggingOptions = Object.assign(Object.assign(Object.assign({}, this.defaultConfig.logging), decoratorLogging), { databaseLogging: (_g = this.defaultConfig.logging) === null || _g === void 0 ? void 0 : _g.databaseLogging });
                 if (loggingOptions === null || loggingOptions === void 0 ? void 0 : loggingOptions.enabled) {
                     const databaseLogging = (loggingOptions === null || loggingOptions === void 0 ? void 0 : loggingOptions.databaseLog) ||
-                        ((_h = (_g = this.defaultConfig.logging) === null || _g === void 0 ? void 0 : _g.databaseLogging) === null || _h === void 0 ? void 0 : _h.enabled);
+                        ((_j = (_h = this.defaultConfig.logging) === null || _h === void 0 ? void 0 : _h.databaseLogging) === null || _j === void 0 ? void 0 : _j.enabled);
                     const records = retryRecorder.getRecords();
                     this.loggingService.logRequestError(error, startTime, requestId, (records === null || records === void 0 ? void 0 : records.length) ? Math.max(...records.map((r) => r.attempt)) + 1 : 1, loggingOptions, databaseLogging, records, circuitBreakerState, effectiveDecoratorContext, effectiveClientName, callingContext);
                 }
                 // 更新统计信息
-                const errorMethod = (_j = error.config) === null || _j === void 0 ? void 0 : _j.method;
-                const errorStatus = (_k = error.response) === null || _k === void 0 ? void 0 : _k.status;
+                const errorMethod = (_k = error.config) === null || _k === void 0 ? void 0 : _k.method;
+                const errorStatus = (_l = error.response) === null || _l === void 0 ? void 0 : _l.status;
                 this.updateRequestStats(false, Date.now() - startTime, errorMethod, errorStatus);
                 throw error;
             }
@@ -436,14 +470,49 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
      * 创建Axios实例并配置axios-retry
      */
     createAxiosInstance() {
-        var _a;
-        const instance = require('axios').create({
+        var _a, _b, _c;
+        // 合并代理配置和 axiosConfig 透传配置
+        const resolvedProxy = this.resolveProxyConfig(this.defaultConfig.proxy);
+        // 处理 SSL 配置和 httpsAgent
+        let httpsAgent = (_a = this.defaultConfig.axiosConfig) === null || _a === void 0 ? void 0 : _a.httpsAgent;
+        if ((_b = this.defaultConfig.axiosConfig) === null || _b === void 0 ? void 0 : _b.ssl) {
+            const ssl = this.defaultConfig.axiosConfig.ssl;
+            const https = require('https');
+            if (!httpsAgent) {
+                // 如果没有预定义的 httpsAgent，使用 SSL 配置创建
+                httpsAgent = new https.Agent(Object.assign(Object.assign({}, ssl), { keepAlive: true }));
+            }
+            else {
+                // 如果同时提供了 httpsAgent 和 ssl 配置
+                // ssl 配置会覆盖 httpsAgent 的相关选项
+                this.logger.warn('Both httpsAgent and ssl config provided. SSL config will take precedence for certificate options.');
+                // 创建新的 Agent，合并原有配置和 SSL 配置
+                httpsAgent = new https.Agent(Object.assign({ 
+                    // 保留原 Agent 的选项（除了证书相关）
+                    keepAlive: true }, ssl));
+            }
+        }
+        // 构建 axios 创建配置
+        const axiosCreateConfig = {
             baseURL: this.defaultConfig.baseURL,
             timeout: this.defaultConfig.timeout,
-            proxy: this.resolveProxyConfig(this.defaultConfig.proxy),
-        });
+            proxy: resolvedProxy !== undefined ? resolvedProxy : undefined,
+            // 应用处理后的 httpsAgent
+            httpsAgent: httpsAgent,
+        };
+        // 透传所有其他 axiosConfig 配置（排除已特殊处理的字段）
+        // 只在值有效时才覆盖
+        if (this.defaultConfig.axiosConfig) {
+            const _d = this.defaultConfig.axiosConfig, { ssl, httpsAgent: _ } = _d, restAxiosConfig = __rest(_d, ["ssl", "httpsAgent"]);
+            for (const key in restAxiosConfig) {
+                if (restAxiosConfig[key] !== undefined) {
+                    axiosCreateConfig[key] = restAxiosConfig[key];
+                }
+            }
+        }
+        const instance = require('axios').create(axiosCreateConfig);
         // 配置axios-retry
-        if ((_a = this.defaultConfig.retry) === null || _a === void 0 ? void 0 : _a.enabled) {
+        if ((_c = this.defaultConfig.retry) === null || _c === void 0 ? void 0 : _c.enabled) {
             (0, axios_retry_1.default)(instance, {
                 retries: this.defaultConfig.retry.retries || 3,
                 retryDelay: this.defaultConfig.retry.retryDelay ||
@@ -546,12 +615,20 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
     }
     /**
      * 应用装饰器配置
+     * 只在装饰器配置值有效时才覆盖请求配置
      */
     applyDecoratorConfig(config, decoratorContext) {
         if (!decoratorContext)
             return Object.assign({}, config);
         const httpClientConfig = decorators_1.HttpDecoratorUtils.getHttpClientOptions(decoratorContext.target);
-        return Object.assign(Object.assign({}, config), httpClientConfig);
+        // 只在值有效时才合并
+        const result = Object.assign({}, config);
+        for (const key in httpClientConfig) {
+            if (httpClientConfig[key] !== undefined) {
+                result[key] = httpClientConfig[key];
+            }
+        }
+        return result;
     }
     // Note: applyDecoratorConfig is not currently being called in executeWithFeatures
     // The decorator config is already being applied via effectiveDecoratorContext
@@ -622,10 +699,15 @@ let HttpClientService = HttpClientService_1 = class HttpClientService {
     }
     /**
      * 深度合并对象
+     * 只在源值有效（非 undefined）时才覆盖目标值
      */
     deepMerge(target, source) {
         const result = Object.assign({}, target);
         for (const key in source) {
+            // 跳过 undefined 值，不覆盖目标值
+            if (source[key] === undefined) {
+                continue;
+            }
             if (source[key] &&
                 typeof source[key] === 'object' &&
                 !Array.isArray(source[key])) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nest-omni/core",
-  "version": "4.1.3-22",
+  "version": "4.1.3-24",
   "description": "A comprehensive NestJS framework for building enterprise-grade applications with best practices",
   "main": "index.js",
   "types": "index.d.ts",