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

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

@@ -0,0 +1,432 @@
+"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());
+    }
+    // 重新创建客户端以使用新证书
+    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);
+        });
+    }
+    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 }),
+            },
+        };
+    }
+}
+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/http-client.module.d.ts

@@ -3,20 +3,61 @@ import { HttpClientConfig } from './interfaces/http-client-config.interface';
 /**
  * HTTP客户端模块
  * 类似Spring Boot的自动配置机制，集成现有的cache服务
+ *
+ * @example
+ * // 最简单的方式 - 使用所有默认配置
+ * HttpClientModule.forRoot()
+ *
+ * @example
+ * // 只覆盖部分配置
+ * HttpClientModule.forRoot({
+ *   baseURL: 'https://api.example.com',
+ *   timeout: 5000,
+ * })
+ *
+ * @example
+ * // 深度合并配置
+ * HttpClientModule.forRoot({
+ *   logging: {
+ *     logLevel: 'debug',
+ *     // 其他 logging 配置会使用默认值
+ *   },
+ * })
  */
 export declare class HttpClientModule {
     /**
      * 动态注册HTTP客户端模块
+     * @param config 用户配置，所有字段都是可选的
+     * @returns DynamicModule
      */
-    static forRoot(config?: HttpClientConfig): DynamicModule;
+    static forRoot(config?: Partial<HttpClientConfig>): DynamicModule;
     /**
      * 异步注册HTTP客户端模块
+     * @param config 异步配置，所有字段都是可选的
+     * @returns DynamicModule
+     *
+     * @example
+     * HttpClientModule.forRootAsync({
+     *   useFactory: (configService: ConfigService) => ({
+     *     baseURL: configService.get('API_BASE_URL'),
+     *     timeout: 5000,
+     *   }),
+     *   inject: [ConfigService],
+     * })
      */
     static forRootAsync(config: {
-        useFactory: (...args: any[]) => Promise<HttpClientConfig> | HttpClientConfig;
+        useFactory: (...args: any[]) => Promise<Partial<HttpClientConfig>> | Partial<HttpClientConfig>;
         inject?: any[];
         imports?: any[];
     }): DynamicModule;
+    /**
+     * 安全地从环境变量解析整数
+     * @param configService NestJS ConfigService
+     * @param key 环境变量键
+     * @param defaultValue 默认值
+     * @returns 解析后的数字或默认值
+     */
+    private static parseEnvInt;
     /**
      * 从环境变量加载配置
      */