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

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/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/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;
@@ -436,14 +447,44 @@ 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"]);
+            Object.assign(axiosCreateConfig, restAxiosConfig);
+        }
+        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 ||

package/package.json

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