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

package/http-client/examples/proxy-from-environment.example.d.ts

@@ -0,0 +1,133 @@
+/**
+ * ProxyFromEnvironment 使用示例
+ *
+ * 本文件演示如何在 HTTP Client 中使用代理环境变量支持
+ */
+import { HttpClientService } from '../';
+/**
+ * 示例 1: 使用环境变量配置代理 (推荐方式)
+ *
+ * 设置环境变量:
+ * export HTTP_PROXY=http://proxy.example.com:8080
+ * export HTTPS_PROXY=https://secure-proxy.example.com:8443
+ * export NO_PROXY=localhost,127.0.0.1,.internal.com
+ */
+export declare class ProxyFromEnvironmentExample {
+    private readonly httpClient;
+    constructor(httpClient: HttpClientService);
+    /**
+     * 使用装饰器从环境变量读取代理配置
+     */
+    fetchWithProxyFromEnv(): Promise<any>;
+    /**
+     * 直接配置请求时指定从环境变量读取代理
+     */
+    fetchWithConfiguredProxy(): Promise<any>;
+}
+/**
+ * 示例 2: 带认证的代理环境变量
+ *
+ * 设置环境变量:
+ * export HTTP_PROXY=http://username:password@proxy.example.com:8080
+ */
+export declare class ProxyWithAuthExample {
+    private readonly httpClient;
+    constructor(httpClient: HttpClientService);
+    fetchWithAuthenticatedProxy(): Promise<any>;
+}
+/**
+ * 示例 3: NO_PROXY 使用示例
+ *
+ * 设置环境变量:
+ * export HTTP_PROXY=http://proxy.example.com:8080
+ * export NO_PROXY=localhost,127.0.0.1,.internal.com,.local
+ */
+export declare class NoProxyExample {
+    private readonly httpClient;
+    constructor(httpClient: HttpClientService);
+    fetchExternalApi(): Promise<any>;
+    fetchInternalApi(): Promise<any>;
+    fetchLocalhost(): Promise<any>;
+}
+/**
+ * 示例 4: 混合使用 - 部分请求使用代理，部分不使用
+ */
+export declare class MixedProxyExample {
+    private readonly httpClient;
+    constructor(httpClient: HttpClientService);
+    fetchWithProxy(): Promise<any>;
+    fetchWithoutProxy(): Promise<any>;
+}
+/**
+ * 示例 5: 企业环境中的实际使用场景
+ *
+ * 在 docker-compose.yml 或 Kubernetes 配置中设置:
+ * environment:
+ *   - HTTP_PROXY=http://proxy-user:proxy-pass@corporate-proxy.company.com:8080
+ *   - HTTPS_PROXY=http://proxy-user:proxy-pass@corporate-proxy.company.com:8080
+ *   - NO_PROXY=localhost,127.0.0.1,.company.com,.svc.cluster.local
+ */
+export declare class EnterpriseProxyExample {
+    private readonly httpClient;
+    constructor(httpClient: HttpClientService);
+    /**
+     * 访问外部 API（使用企业代理）
+     */
+    fetchFromExternalApi(): Promise<any>;
+    /**
+     * 访问内部服务（不使用代理）
+     */
+    fetchFromInternalService(): Promise<any>;
+    /**
+     * 访问 Kubernetes 集群内服务（不使用代理）
+     */
+    fetchFromK8sService(): Promise<any>;
+}
+/**
+ * 示例 6: 开发环境调试代理
+ *
+ * 本地开发时使用 Charles、Fiddler 等代理工具调试:
+ * export HTTP_PROXY=http://localhost:8888
+ * export HTTPS_PROXY=http://localhost:8888
+ */
+export declare class DevelopmentProxyExample {
+    private readonly httpClient;
+    constructor(httpClient: HttpClientService);
+    debugRequest(): Promise<any>;
+}
+/**
+ * 示例 7: 程序化检查代理配置
+ */
+export declare class ProxyUtilityExample {
+    checkProxyConfiguration(): Promise<void>;
+}
+/**
+ * 模块配置示例
+ */
+export declare const httpClientModuleConfig: {
+    globalProxyFromEnv: {
+        imports: {
+            proxy: {
+                enabled: boolean;
+                fromEnvironment: boolean;
+            };
+        }[];
+    };
+    selectiveProxy: {
+        imports: {
+            proxy: {
+                enabled: boolean;
+            };
+        }[];
+    };
+};
+/**
+ * 环境变量配置示例
+ */
+export declare const environmentVariablesExamples: {
+    basic: string;
+    withAuth: string;
+    specialChars: string;
+    enterprise: string;
+    development: string;
+};

package/http-client/examples/proxy-from-environment.example.js

@@ -0,0 +1,409 @@
+"use strict";
+/**
+ * ProxyFromEnvironment 使用示例
+ *
+ * 本文件演示如何在 HTTP Client 中使用代理环境变量支持
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+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.environmentVariablesExamples = exports.httpClientModuleConfig = exports.ProxyUtilityExample = exports.DevelopmentProxyExample = exports.EnterpriseProxyExample = exports.MixedProxyExample = exports.NoProxyExample = exports.ProxyWithAuthExample = exports.ProxyFromEnvironmentExample = void 0;
+const common_1 = require("@nestjs/common");
+const __1 = require("../");
+/**
+ * 示例 1: 使用环境变量配置代理 (推荐方式)
+ *
+ * 设置环境变量:
+ * export HTTP_PROXY=http://proxy.example.com:8080
+ * export HTTPS_PROXY=https://secure-proxy.example.com:8443
+ * export NO_PROXY=localhost,127.0.0.1,.internal.com
+ */
+let ProxyFromEnvironmentExample = class ProxyFromEnvironmentExample {
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    /**
+     * 使用装饰器从环境变量读取代理配置
+     */
+    fetchWithProxyFromEnv() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 此请求将根据环境变量使用代理
+            // - HTTP 请求使用 HTTP_PROXY
+            // - HTTPS 请求使用 HTTPS_PROXY（如果未设置则使用 HTTP_PROXY）
+            // - 匹配 NO_PROXY 的域名不使用代理
+            return this.httpClient.get('https://api.example.com/data');
+        });
+    }
+    /**
+     * 直接配置请求时指定从环境变量读取代理
+     */
+    fetchWithConfiguredProxy() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.httpClient.request({
+                url: 'https://api.example.com/data',
+                method: 'GET',
+                // 代理配置会在模块级别或请求级别应用
+            });
+        });
+    }
+};
+exports.ProxyFromEnvironmentExample = ProxyFromEnvironmentExample;
+__decorate([
+    (0, __1.HttpUseProxy)({
+        enabled: true,
+        fromEnvironment: true,
+    }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], ProxyFromEnvironmentExample.prototype, "fetchWithProxyFromEnv", null);
+exports.ProxyFromEnvironmentExample = ProxyFromEnvironmentExample = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [__1.HttpClientService])
+], ProxyFromEnvironmentExample);
+/**
+ * 示例 2: 带认证的代理环境变量
+ *
+ * 设置环境变量:
+ * export HTTP_PROXY=http://username:password@proxy.example.com:8080
+ */
+let ProxyWithAuthExample = class ProxyWithAuthExample {
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    fetchWithAuthenticatedProxy() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 自动从环境变量解析认证信息
+            return this.httpClient.get('https://api.example.com/data');
+        });
+    }
+};
+exports.ProxyWithAuthExample = ProxyWithAuthExample;
+__decorate([
+    (0, __1.HttpUseProxy)({
+        enabled: true,
+        fromEnvironment: true,
+    }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], ProxyWithAuthExample.prototype, "fetchWithAuthenticatedProxy", null);
+exports.ProxyWithAuthExample = ProxyWithAuthExample = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [__1.HttpClientService])
+], ProxyWithAuthExample);
+/**
+ * 示例 3: NO_PROXY 使用示例
+ *
+ * 设置环境变量:
+ * export HTTP_PROXY=http://proxy.example.com:8080
+ * export NO_PROXY=localhost,127.0.0.1,.internal.com,.local
+ */
+let NoProxyExample = class NoProxyExample {
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    fetchExternalApi() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 此请求会使用代理
+            return this.httpClient.get('https://api.external.com/data');
+        });
+    }
+    fetchInternalApi() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 此请求不会使用代理（匹配 NO_PROXY 中的 .internal.com）
+            return this.httpClient.get('https://api.internal.com/data');
+        });
+    }
+    fetchLocalhost() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 此请求不会使用代理（匹配 NO_PROXY 中的 localhost）
+            return this.httpClient.get('http://localhost:3000/api');
+        });
+    }
+};
+exports.NoProxyExample = NoProxyExample;
+__decorate([
+    (0, __1.HttpUseProxy)({
+        enabled: true,
+        fromEnvironment: true,
+    }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], NoProxyExample.prototype, "fetchExternalApi", null);
+__decorate([
+    (0, __1.HttpUseProxy)({
+        enabled: true,
+        fromEnvironment: true,
+    }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], NoProxyExample.prototype, "fetchInternalApi", null);
+__decorate([
+    (0, __1.HttpUseProxy)({
+        enabled: true,
+        fromEnvironment: true,
+    }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], NoProxyExample.prototype, "fetchLocalhost", null);
+exports.NoProxyExample = NoProxyExample = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [__1.HttpClientService])
+], NoProxyExample);
+/**
+ * 示例 4: 混合使用 - 部分请求使用代理，部分不使用
+ */
+let MixedProxyExample = class MixedProxyExample {
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    // 使用代理
+    fetchWithProxy() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.httpClient.get('https://api.external.com/data');
+        });
+    }
+    // 不使用代理
+    fetchWithoutProxy() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.httpClient.get('https://api.direct.com/data');
+        });
+    }
+};
+exports.MixedProxyExample = MixedProxyExample;
+__decorate([
+    (0, __1.HttpUseProxy)({
+        enabled: true,
+        fromEnvironment: true,
+    }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], MixedProxyExample.prototype, "fetchWithProxy", null);
+exports.MixedProxyExample = MixedProxyExample = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [__1.HttpClientService])
+], MixedProxyExample);
+/**
+ * 示例 5: 企业环境中的实际使用场景
+ *
+ * 在 docker-compose.yml 或 Kubernetes 配置中设置:
+ * environment:
+ *   - HTTP_PROXY=http://proxy-user:proxy-pass@corporate-proxy.company.com:8080
+ *   - HTTPS_PROXY=http://proxy-user:proxy-pass@corporate-proxy.company.com:8080
+ *   - NO_PROXY=localhost,127.0.0.1,.company.com,.svc.cluster.local
+ */
+let EnterpriseProxyExample = class EnterpriseProxyExample {
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    /**
+     * 访问外部 API（使用企业代理）
+     */
+    fetchFromExternalApi() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 通过企业代理访问外部 API
+            return this.httpClient.get('https://api.github.com/repos/microsoft/TypeScript');
+        });
+    }
+    /**
+     * 访问内部服务（不使用代理）
+     */
+    fetchFromInternalService() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 直接访问内部服务（匹配 NO_PROXY: .company.com）
+            return this.httpClient.get('https://api.company.com/internal/users');
+        });
+    }
+    /**
+     * 访问 Kubernetes 集群内服务（不使用代理）
+     */
+    fetchFromK8sService() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 直接访问 K8s 服务（匹配 NO_PROXY: .svc.cluster.local）
+            return this.httpClient.get('http://user-service.default.svc.cluster.local/api/users');
+        });
+    }
+};
+exports.EnterpriseProxyExample = EnterpriseProxyExample;
+__decorate([
+    (0, __1.HttpUseProxy)({
+        enabled: true,
+        fromEnvironment: true,
+    }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], EnterpriseProxyExample.prototype, "fetchFromExternalApi", null);
+__decorate([
+    (0, __1.HttpUseProxy)({
+        enabled: true,
+        fromEnvironment: true,
+    }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], EnterpriseProxyExample.prototype, "fetchFromInternalService", null);
+__decorate([
+    (0, __1.HttpUseProxy)({
+        enabled: true,
+        fromEnvironment: true,
+    }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], EnterpriseProxyExample.prototype, "fetchFromK8sService", null);
+exports.EnterpriseProxyExample = EnterpriseProxyExample = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [__1.HttpClientService])
+], EnterpriseProxyExample);
+/**
+ * 示例 6: 开发环境调试代理
+ *
+ * 本地开发时使用 Charles、Fiddler 等代理工具调试:
+ * export HTTP_PROXY=http://localhost:8888
+ * export HTTPS_PROXY=http://localhost:8888
+ */
+let DevelopmentProxyExample = class DevelopmentProxyExample {
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    debugRequest() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 开发环境下会通过本地代理工具
+            // 可以查看详细的请求和响应内容
+            return this.httpClient.post('https://api.example.com/debug', {
+                test: 'data',
+            });
+        });
+    }
+};
+exports.DevelopmentProxyExample = DevelopmentProxyExample;
+__decorate([
+    (0, __1.HttpUseProxy)({
+        enabled: process.env.NODE_ENV === 'development',
+        fromEnvironment: true,
+    }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], DevelopmentProxyExample.prototype, "debugRequest", null);
+exports.DevelopmentProxyExample = DevelopmentProxyExample = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [__1.HttpClientService])
+], DevelopmentProxyExample);
+/**
+ * 示例 7: 程序化检查代理配置
+ */
+let ProxyUtilityExample = class ProxyUtilityExample {
+    checkProxyConfiguration() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { ProxyEnvironmentParser } = yield Promise.resolve().then(() => require('../'));
+            // 检查是否设置了代理环境变量
+            const hasProxy = ProxyEnvironmentParser.hasProxyEnvironment();
+            console.log('Has proxy environment:', hasProxy);
+            // 获取所有代理环境变量
+            const vars = ProxyEnvironmentParser.getProxyEnvironmentVariables();
+            console.log('Proxy environment variables:', vars);
+            // 解析特定 URL 的代理配置
+            const proxyConfig = ProxyEnvironmentParser.parseFromEnvironment('https', 'https://api.example.com/data');
+            console.log('Parsed proxy config:', proxyConfig);
+        });
+    }
+};
+exports.ProxyUtilityExample = ProxyUtilityExample;
+exports.ProxyUtilityExample = ProxyUtilityExample = __decorate([
+    (0, common_1.Injectable)()
+], ProxyUtilityExample);
+/**
+ * 模块配置示例
+ */
+exports.httpClientModuleConfig = {
+    // 方式 1: 全局启用环境变量代理
+    globalProxyFromEnv: {
+        imports: [
+            {
+                // HttpClientModule.forRoot({
+                proxy: {
+                    enabled: true,
+                    fromEnvironment: true, // 所有请求默认使用环境变量代理
+                },
+                // })
+            },
+        ],
+    },
+    // 方式 2: 全局禁用，按需启用
+    selectiveProxy: {
+        imports: [
+            {
+                // HttpClientModule.forRoot({
+                proxy: {
+                    enabled: false, // 全局禁用，使用装饰器按需启用
+                },
+                // })
+            },
+        ],
+    },
+};
+/**
+ * 环境变量配置示例
+ */
+exports.environmentVariablesExamples = {
+    // 基本配置
+    basic: `
+# 基本 HTTP 代理
+HTTP_PROXY=http://proxy.example.com:8080
+
+# HTTPS 代理
+HTTPS_PROXY=https://proxy.example.com:8443
+
+# 不使用代理的域名
+NO_PROXY=localhost,127.0.0.1
+`,
+    // 带认证
+    withAuth: `
+# 带认证的代理
+HTTP_PROXY=http://username:password@proxy.example.com:8080
+HTTPS_PROXY=http://username:password@proxy.example.com:8080
+`,
+    // 特殊字符认证（URL 编码）
+    specialChars: `
+# 用户名: user@domain.com
+# 密码: p@ssw0rd
+HTTP_PROXY=http://user%40domain.com:p%40ssw0rd@proxy.example.com:8080
+`,
+    // 企业环境
+    enterprise: `
+# 企业代理配置
+HTTP_PROXY=http://proxy-user:proxy-pass@corporate-proxy.company.com:8080
+HTTPS_PROXY=http://proxy-user:proxy-pass@corporate-proxy.company.com:8080
+NO_PROXY=localhost,127.0.0.1,.company.com,.internal.com,.svc.cluster.local,10.0.0.0/8
+`,
+    // 开发环境
+    development: `
+# 本地代理工具（Charles, Fiddler 等）
+HTTP_PROXY=http://localhost:8888
+HTTPS_PROXY=http://localhost:8888
+NO_PROXY=localhost,127.0.0.1
+`,
+};

package/http-client/http-client.module.d.ts

@@ -1,11 +1,57 @@
 import { DynamicModule } from '@nestjs/common';
 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 {
-    static forRoot(config?: HttpClientConfig): DynamicModule;
+    /**
+     * 动态注册HTTP客户端模块
+     * @param config 用户配置，所有字段都是可选的
+     * @returns 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;
+    /**
+     * 从环境变量加载配置
+     */
     private static loadConfigFromEnvironment;
 }