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

package/http-client/examples/multi-api-configuration.example.js

@@ -21,11 +21,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExampleController = exports.ApiManagementService = exports.CustomApiService = exports.WeChatApiService = exports.StripeApiService = exports.GitHubApiService = void 0;
 const common_1 = require("@nestjs/common");
 const api_client_registry_service_1 = require("../services/api-client-registry.service");
+/**
+ * GitHub API 客户端示例
+ */
 let GitHubApiService = class GitHubApiService {
     constructor(apiRegistry) {
         this.apiRegistry = apiRegistry;
         this.initializeClients();
     }
+    /**
+     * 获取GitHub客户端
+     */
     get github() {
         return this.apiRegistry.getClient('github');
     }
@@ -40,10 +46,11 @@ let GitHubApiService = class GitHubApiService {
                 },
             },
             responseTransformer: {
-                dataPath: 'data',
+                dataPath: 'data', // GitHub API通常返回 { data: [...] }
                 success: (response) => response.data,
                 error: (error) => {
                     var _a, _b;
+                    // GitHub API 错误处理
                     if ((_b = (_a = error.response) === null || _a === void 0 ? void 0 : _a.data) === null || _b === void 0 ? void 0 : _b.message) {
                         throw new Error(`GitHub API Error: ${error.response.data.message}`);
                     }
@@ -55,10 +62,11 @@ let GitHubApiService = class GitHubApiService {
                 retries: 3,
                 retryCondition: (error) => {
                     var _a, _b;
+                    // GitHub API 速率限制时重试
                     return (((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 403 || ((_b = error.response) === null || _b === void 0 ? void 0 : _b.status) === 429);
                 },
             },
-            responseTimeWarningThreshold: 2000,
+            responseTimeWarningThreshold: 2000, // 2秒警告
             tags: ['github', 'vcs'],
         });
     }
@@ -68,6 +76,9 @@ exports.GitHubApiService = GitHubApiService = __decorate([
     (0, common_1.Injectable)(),
     __metadata("design:paramtypes", [api_client_registry_service_1.ApiClientRegistryService])
 ], GitHubApiService);
+/**
+ * Stripe API 客户端示例
+ */
 let StripeApiService = class StripeApiService {
     constructor(apiRegistry) {
         this.apiRegistry = apiRegistry;
@@ -94,13 +105,14 @@ let StripeApiService = class StripeApiService {
                 dataPath: 'data',
                 error: (error) => {
                     var _a, _b, _c;
+                    // Stripe API 错误处理
                     if ((_c = (_b = (_a = error.response) === null || _a === void 0 ? void 0 : _a.data) === null || _b === void 0 ? void 0 : _b.error) === null || _c === void 0 ? void 0 : _c.message) {
                         throw new Error(`Stripe API Error: ${error.response.data.error.message}`);
                     }
                     throw error;
                 },
             },
-            responseTimeWarningThreshold: 3000,
+            responseTimeWarningThreshold: 3000, // 3秒警告
             tags: ['stripe', 'payment'],
         });
     }
@@ -110,6 +122,9 @@ exports.StripeApiService = StripeApiService = __decorate([
     (0, common_1.Injectable)(),
     __metadata("design:paramtypes", [api_client_registry_service_1.ApiClientRegistryService])
 ], StripeApiService);
+/**
+ * 微信API客户端示例
+ */
 let WeChatApiService = class WeChatApiService {
     constructor(apiRegistry) {
         this.apiRegistry = apiRegistry;
@@ -123,10 +138,11 @@ let WeChatApiService = class WeChatApiService {
             name: 'wechat',
             baseURL: 'https://api.weixin.qq.com',
             auth: {
-                type: api_client_registry_service_1.AuthType.NONE,
+                type: api_client_registry_service_1.AuthType.NONE, // 微信API通常使用签名验证
             },
             responseTransformer: {
                 success: (response) => {
+                    // 微信API响应格式: { errcode: 0, errmsg: 'success', data: {...} }
                     if (response.data.errcode !== 0) {
                         throw new Error(`WeChat API Error (${response.data.errcode}): ${response.data.errmsg}`);
                     }
@@ -136,7 +152,7 @@ let WeChatApiService = class WeChatApiService {
             tags: ['wechat', 'social'],
             environments: {
                 development: {
-                    baseURL: 'https://api.tunnel.com/wechat',
+                    baseURL: 'https://api.tunnel.com/wechat', // 开发环境使用隧道
                 },
             },
         });
@@ -147,6 +163,9 @@ exports.WeChatApiService = WeChatApiService = __decorate([
     (0, common_1.Injectable)(),
     __metadata("design:paramtypes", [api_client_registry_service_1.ApiClientRegistryService])
 ], WeChatApiService);
+/**
+ * 自定义API客户端示例（复杂响应格式）
+ */
 let CustomApiService = class CustomApiService {
     constructor(apiRegistry) {
         this.apiRegistry = apiRegistry;
@@ -164,6 +183,7 @@ let CustomApiService = class CustomApiService {
                 config: {
                     authenticator(config) {
                         return __awaiter(this, void 0, void 0, function* () {
+                            // 自定义JWT token刷新逻辑
                             const token = yield this.getValidToken();
                             config.headers = Object.assign(Object.assign({}, config.headers), { Authorization: `Bearer ${token}`, 'X-Timestamp': Date.now().toString(), 'X-Signature': this.generateSignature(config) });
                             return config;
@@ -172,6 +192,7 @@ let CustomApiService = class CustomApiService {
                     refresher(config, error) {
                         return __awaiter(this, void 0, void 0, function* () {
                             var _a;
+                            // Token过期时自动刷新
                             if (((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 401) {
                                 const newToken = yield this.refreshToken();
                                 config.headers['Authorization'] = `Bearer ${newToken}`;
@@ -184,10 +205,13 @@ let CustomApiService = class CustomApiService {
             },
             responseTransformer: {
                 success: (response) => {
+                    // 复杂响应格式处理
                     const result = response.data;
+                    // 统一成功格式
                     if (result.success === false) {
                         throw new Error(result.message || 'API request failed');
                     }
+                    // 数据包装处理
                     return {
                         data: result.data || result,
                         code: result.code || 0,
@@ -198,6 +222,7 @@ let CustomApiService = class CustomApiService {
                 },
                 error: (error) => {
                     var _a;
+                    // 统一错误格式
                     if ((_a = error.response) === null || _a === void 0 ? void 0 : _a.data) {
                         const errorData = error.response.data;
                         const customError = new Error(errorData.message || 'API request failed');
@@ -216,6 +241,7 @@ let CustomApiService = class CustomApiService {
                 enabled: true,
                 retries: 2,
                 retryCondition: (error) => {
+                    // 只对网络错误和5xx错误重试
                     if (!error.response)
                         return true;
                     return error.response.status >= 500;
@@ -226,15 +252,18 @@ let CustomApiService = class CustomApiService {
     }
     getValidToken() {
         return __awaiter(this, void 0, void 0, function* () {
+            // 实现token获取逻辑
             return 'mock-jwt-token';
         });
     }
     refreshToken() {
         return __awaiter(this, void 0, void 0, function* () {
+            // 实现token刷新逻辑
             return 'refreshed-jwt-token';
         });
     }
     generateSignature(config) {
+        // 实现签名生成逻辑
         return 'mock-signature';
     }
 };
@@ -243,27 +272,48 @@ exports.CustomApiService = CustomApiService = __decorate([
     (0, common_1.Injectable)(),
     __metadata("design:paramtypes", [api_client_registry_service_1.ApiClientRegistryService])
 ], CustomApiService);
+/**
+ * API管理服务示例
+ */
 let ApiManagementService = class ApiManagementService {
     constructor(apiRegistry) {
         this.apiRegistry = apiRegistry;
     }
+    /**
+     * 动态创建API客户端
+     */
     createDynamicClient(name, config) {
         return this.apiRegistry.createClient(Object.assign({ name, baseURL: config.baseURL || '' }, config));
     }
+    /**
+     * 获取所有客户端统计信息
+     */
     getAllStats() {
         return this.apiRegistry.getAllStats();
     }
+    /**
+     * 重置所有统计信息
+     */
     resetAllStats() {
         this.apiRegistry.resetAllStats();
     }
+    /**
+     * 健康检查
+     */
     healthCheck() {
         return __awaiter(this, void 0, void 0, function* () {
             return this.apiRegistry.healthCheck();
         });
     }
+    /**
+     * 批量创建客户端
+     */
     createMultipleClients(configs) {
         this.apiRegistry.createClients(configs);
     }
+    /**
+     * 获取客户端列表
+     */
     listClients() {
         return this.apiRegistry.listClients();
     }
@@ -273,6 +323,9 @@ exports.ApiManagementService = ApiManagementService = __decorate([
     (0, common_1.Injectable)(),
     __metadata("design:paramtypes", [api_client_registry_service_1.ApiClientRegistryService])
 ], ApiManagementService);
+/**
+ * 使用示例控制器
+ */
 let ExampleController = class ExampleController {
     constructor(githubApi, stripeApi, wechatApi, customApi, apiManagement) {
         this.githubApi = githubApi;
@@ -281,12 +334,18 @@ let ExampleController = class ExampleController {
         this.customApi = customApi;
         this.apiManagement = apiManagement;
     }
+    /**
+     * GitHub API 示例
+     */
     getGitHubUser(username) {
         return __awaiter(this, void 0, void 0, function* () {
             const github = this.githubApi.github;
             return github.get(`/users/${username}`);
         });
     }
+    /**
+     * Stripe API 示例
+     */
     createStripePayment(amount, currency) {
         return __awaiter(this, void 0, void 0, function* () {
             const stripe = this.stripeApi.stripe;
@@ -297,6 +356,9 @@ let ExampleController = class ExampleController {
             });
         });
     }
+    /**
+     * 微信 API 示例
+     */
     sendWeChatMessage(openid, content) {
         return __awaiter(this, void 0, void 0, function* () {
             const wechat = this.wechatApi.wechat;
@@ -309,12 +371,18 @@ let ExampleController = class ExampleController {
             });
         });
     }
+    /**
+     * 自定义API 示例
+     */
     getCustomData(id) {
         return __awaiter(this, void 0, void 0, function* () {
             const custom = this.customApi.customApi;
             return custom.get(`/data/${id}`);
         });
     }
+    /**
+     * 动态API示例
+     */
     callDynamicApi(url) {
         return __awaiter(this, void 0, void 0, function* () {
             const client = this.apiManagement.createDynamicClient('dynamic', {
@@ -331,6 +399,9 @@ let ExampleController = class ExampleController {
             return client.get('/');
         });
     }
+    /**
+     * API管理示例
+     */
     getApiHealth() {
         return __awaiter(this, void 0, void 0, function* () {
             return this.apiManagement.healthCheck();

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

@@ -1,11 +1,24 @@
 import { DynamicModule } from '@nestjs/common';
 import { HttpClientConfig } from './interfaces/http-client-config.interface';
+/**
+ * HTTP客户端模块
+ * 类似Spring Boot的自动配置机制，集成现有的cache服务
+ */
 export declare class HttpClientModule {
+    /**
+     * 动态注册HTTP客户端模块
+     */
     static forRoot(config?: HttpClientConfig): DynamicModule;
+    /**
+     * 异步注册HTTP客户端模块
+     */
     static forRootAsync(config: {
         useFactory: (...args: any[]) => Promise<HttpClientConfig> | HttpClientConfig;
         inject?: any[];
         imports?: any[];
     }): DynamicModule;
+    /**
+     * 从环境变量加载配置
+     */
     private static loadConfigFromEnvironment;
 }

package/http-client/http-client.module.js

@@ -32,9 +32,17 @@ const api_client_registry_service_1 = require("./services/api-client-registry.se
 const entities_1 = require("./entities");
 const cache_options_interface_1 = require("../cache/interfaces/cache-options.interface");
 const redis_lock_service_1 = require("../redis-lock/redis-lock.service");
+/**
+ * HTTP客户端模块
+ * 类似Spring Boot的自动配置机制，集成现有的cache服务
+ */
 let HttpClientModule = HttpClientModule_1 = class HttpClientModule {
+    /**
+     * 动态注册HTTP客户端模块
+     */
     static forRoot(config = {}) {
         var _a, _b, _c;
+        // 基础服务提供者
         const baseProviders = [
             {
                 provide: 'HTTP_CLIENT_CONFIG',
@@ -64,6 +72,7 @@ let HttpClientModule = HttpClientModule_1 = class HttpClientModule {
                 ],
             },
         ];
+        // 基础导出
         const baseExports = [
             http_client_service_1.HttpClientService,
             circuit_breaker_service_1.HttpCircuitBreakerService,
@@ -73,6 +82,7 @@ let HttpClientModule = HttpClientModule_1 = class HttpClientModule {
             log_cleanup_service_1.HttpLogCleanupService,
             api_client_registry_service_1.ApiClientRegistryService,
         ];
+        // 动态导入
         const dynamicImports = [config_1.ConfigModule];
         if ((_b = (_a = config.logging) === null || _a === void 0 ? void 0 : _a.databaseLogging) === null || _b === void 0 ? void 0 : _b.enabled) {
             dynamicImports.push(typeorm_1.TypeOrmModule.forFeature([entities_1.HttpLogEntity]));
@@ -87,7 +97,11 @@ let HttpClientModule = HttpClientModule_1 = class HttpClientModule {
             exports: baseExports,
         };
     }
+    /**
+     * 异步注册HTTP客户端模块
+     */
     static forRootAsync(config) {
+        // 基础服务提供者
         const baseProviders = [
             {
                 provide: 'HTTP_CLIENT_CONFIG',
@@ -118,6 +132,7 @@ let HttpClientModule = HttpClientModule_1 = class HttpClientModule {
                 ],
             },
         ];
+        // 基础导出
         const baseExports = [
             http_client_service_1.HttpClientService,
             circuit_breaker_service_1.HttpCircuitBreakerService,
@@ -127,6 +142,7 @@ let HttpClientModule = HttpClientModule_1 = class HttpClientModule {
             log_cleanup_service_1.HttpLogCleanupService,
             api_client_registry_service_1.ApiClientRegistryService,
         ];
+        // 动态导入
         const dynamicImports = [config_1.ConfigModule, ...(config.imports || [])];
         return {
             module: HttpClientModule_1,
@@ -135,6 +151,9 @@ let HttpClientModule = HttpClientModule_1 = class HttpClientModule {
             exports: baseExports,
         };
     }
+    /**
+     * 从环境变量加载配置
+     */
     static loadConfigFromEnvironment(configService) {
         var _a, _b, _c, _d, _e, _f, _g;
         return {

package/http-client/index.js

@@ -16,12 +16,20 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpLogEntity = void 0;
 __exportStar(require("./interfaces/api-client-config.interface"), exports);
+// 实体类
 var entities_1 = require("./entities");
 Object.defineProperty(exports, "HttpLogEntity", { enumerable: true, get: function () { return entities_1.HttpLogEntity; } });
+// 装饰器
 __exportStar(require("./decorators"), exports);
+// 服务
 __exportStar(require("./services"), exports);
+// 工具类
 __exportStar(require("./utils"), exports);
+// 错误处理
 __exportStar(require("./errors"), exports);
+// 配置
 __exportStar(require("./config"), exports);
+// 模块
 __exportStar(require("./http-client.module"), exports);
+// 示例
 __exportStar(require("./examples"), exports);

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

@@ -1,5 +1,8 @@
 import { AxiosRequestConfig, AxiosResponse } from 'axios';
 import { HttpClientConfig } from './http-client-config.interface';
+/**
+ * 鉴权类型枚举
+ */
 export declare enum AuthType {
     NONE = "none",
     API_KEY = "apiKey",
@@ -8,20 +11,32 @@ export declare enum AuthType {
     OAUTH2 = "oauth2",
     CUSTOM = "custom"
 }
+/**
+ * API密钥配置
+ */
 export interface ApiKeyConfig {
     key: string;
     location: 'header' | 'query';
     name?: string;
     prefix?: string;
 }
+/**
+ * Bearer Token配置
+ */
 export interface BearerTokenConfig {
     token: string;
     scheme?: string;
 }
+/**
+ * 基础认证配置
+ */
 export interface BasicAuthConfig {
     username: string;
     password: string;
 }
+/**
+ * OAuth2配置
+ */
 export interface OAuth2Config {
     clientId: string;
     clientSecret: string;
@@ -33,10 +48,22 @@ export interface OAuth2Config {
     redirectUri?: string;
     refreshToken?: string;
 }
+/**
+ * 自定义鉴权配置
+ */
 export interface CustomAuthConfig {
+    /**
+     * 自定义鉴权函数
+     */
     authenticator: (config: AxiosRequestConfig) => Promise<AxiosRequestConfig>;
+    /**
+     * 刷新token函数
+     */
     refresher?: (config: AxiosRequestConfig, error: any) => Promise<AxiosRequestConfig>;
 }
+/**
+ * 鉴权配置
+ */
 export type AuthConfig = {
     type: AuthType.NONE;
 } | {
@@ -55,98 +82,196 @@ export type AuthConfig = {
     type: AuthType.CUSTOM;
     config: CustomAuthConfig;
 };
+/**
+ * 响应转换器配置
+ */
 export interface ResponseTransformerConfig {
+    /**
+     * 成功响应转换器
+     */
     success?: (response: AxiosResponse) => any;
+    /**
+     * 错误响应转换器
+     */
     error?: (error: any) => any;
+    /**
+     * 响应数据提取路径
+     * 例如 'data.items' 表示从 response.data.items 获取数据
+     */
     dataPath?: string;
+    /**
+     * 错误信息提取路径
+     * 例如 'error.message' 表示从 error.response.data.error.message 获取错误信息
+     */
     errorPath?: string;
+    /**
+     * 是否自动验证响应格式
+     */
     validateResponse?: boolean;
+    /**
+     * 响应格式验证器
+     */
     validator?: (data: any) => boolean;
 }
+/**
+ * API客户端配置
+ */
 export interface ApiClientConfig {
+    /** API名称（用于标识和日志） */
     name: string;
+    /** 基础URL */
     baseURL: string;
+    /** HTTP客户端基础配置 */
     httpConfig?: HttpClientConfig;
+    /** 鉴权配置 */
     auth?: AuthConfig;
+    /** 响应转换配置 */
     responseTransformer?: ResponseTransformerConfig;
+    /** 默认请求头 */
     defaultHeaders?: Record<string, string>;
+    /** 默认查询参数 */
     defaultParams?: Record<string, any>;
+    /** 拦截器配置 */
     interceptors?: {
         request?: Array<(config: AxiosRequestConfig) => AxiosRequestConfig | Promise<AxiosRequestConfig>>;
         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客户端实例配置
+ */
 export interface ApiClientInstanceConfig extends ApiClientConfig {
+    /** 是否覆盖现有配置 */
     override?: boolean;
+    /** 环境特定配置 */
     environments?: {
         development?: Partial<ApiClientConfig>;
         staging?: Partial<ApiClientConfig>;
         production?: Partial<ApiClientConfig>;
     };
 }
+/**
+ * API客户端注册配置
+ */
 export interface ApiClientRegistryConfig {
+    /** 全局默认配置 */
     globalDefaults?: Partial<HttpClientConfig>;
+    /** 日志清理配置 */
     logCleanup?: {
         enabled?: boolean;
         retentionDays?: number;
         maxRecords?: number;
     };
+    /** 默认响应转换器 */
     defaultResponseTransformer?: ResponseTransformerConfig;
+    /** 是否启用自动重试 */
     enableGlobalRetry?: boolean;
+    /** 是否启用熔断器 */
     enableCircuitBreaker?: boolean;
 }
+/**
+ * API客户端工厂接口
+ */
 export interface ApiClientFactory {
+    /**
+     * 创建API客户端实例
+     */
     createClient<T = any>(config: ApiClientInstanceConfig): T;
+    /**
+     * 获取已注册的客户端
+     */
     getClient<T = any>(name: string): T;
+    /**
+     * 列出所有已注册的客户端
+     */
     listClients(): string[];
+    /**
+     * 更新客户端配置
+     */
     updateClient(name: string, config: Partial<ApiClientConfig>): void;
+    /**
+     * 移除客户端
+     */
     removeClient(name: string): void;
 }
+/**
+ * API客户端接口
+ */
 export interface ApiClient {
+    /** 客户端名称 */
     name: string;
+    /** 客户端配置 */
     config: ApiClientConfig;
+    /** 基础HTTP请求方法 */
     get<T = any>(url: string, config?: AxiosRequestConfig): Promise<T>;
     post<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
     put<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
     patch<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
     delete<T = any>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    /** 通用请求方法 */
     request<T = any>(config: AxiosRequestConfig): Promise<T>;
+    /** 获取客户端统计信息 */
     getStats(): any;
+    /** 重置统计信息 */
     resetStats(): void;
 }
+/**
+ * 通用API响应格式
+ */
 export interface ApiResponse<T = any> {
+    /** 响应数据 */
     data?: T;
+    /** 响应代码 */
     code?: number;
+    /** 响应消息 */
     message?: string;
+    /** 成功标识 */
     success?: boolean;
+    /** 错误详情 */
     error?: {
         code?: string;
         message?: string;
         details?: any;
     };
+    /** 分页信息 */
     pagination?: {
         page?: number;
         pageSize?: number;
         total?: number;
         totalPages?: number;
     };
+    /** 请求ID */
     requestId?: string;
+    /** 时间戳 */
     timestamp?: string;
 }
+/**
+ * 错误响应格式
+ */
 export interface ErrorResponse {
+    /** 错误代码 */
     code: string | number;
+    /** 错误消息 */
     message: string;
+    /** 错误详情 */
     details?: any;
+    /** 堆栈信息 */
     stack?: string;
+    /** 请求ID */
     requestId?: string;
 }

package/http-client/interfaces/api-client-config.interface.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthType = void 0;
+/**
+ * 鉴权类型枚举
+ */
 var AuthType;
 (function (AuthType) {
     AuthType["NONE"] = "none";