@nest-omni/core 4.1.3-1 → 4.1.3-10

package/http-client/errors/http-client.errors.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ErrorFactory = exports.CacheError = exports.ApiClientConfigError = exports.ResponseFormatError = exports.ServerError = exports.RateLimitError = exports.AuthorizationError = exports.AuthenticationError = exports.CircuitBreakerOpenError = exports.RetryExhaustedError = exports.TimeoutError = exports.NetworkError = exports.HttpClientError = void 0;
+/**
+ * HTTP客户端基础错误类
+ */
 class HttpClientError extends Error {
     constructor(message, code = 'HTTP_CLIENT_ERROR', statusCode, response, config) {
         super(message);
@@ -13,6 +16,9 @@ class HttpClientError extends Error {
     }
 }
 exports.HttpClientError = HttpClientError;
+/**
+ * 网络错误
+ */
 class NetworkError extends HttpClientError {
     constructor(message, config) {
         super(message, 'NETWORK_ERROR', undefined, undefined, config);
@@ -20,6 +26,9 @@ class NetworkError extends HttpClientError {
     }
 }
 exports.NetworkError = NetworkError;
+/**
+ * 超时错误
+ */
 class TimeoutError extends HttpClientError {
     constructor(message, config) {
         super(message, 'TIMEOUT_ERROR', undefined, undefined, config);
@@ -27,6 +36,9 @@ class TimeoutError extends HttpClientError {
     }
 }
 exports.TimeoutError = TimeoutError;
+/**
+ * 重试失败错误
+ */
 class RetryExhaustedError extends HttpClientError {
     constructor(message, attempts, lastError, config) {
         super(message, 'RETRY_EXHAUSTED', undefined, undefined, config);
@@ -36,6 +48,9 @@ class RetryExhaustedError extends HttpClientError {
     }
 }
 exports.RetryExhaustedError = RetryExhaustedError;
+/**
+ * 熔断器开启错误
+ */
 class CircuitBreakerOpenError extends HttpClientError {
     constructor(message, circuitName, failureCount, config) {
         super(message, 'CIRCUIT_BREAKER_OPEN', 503, undefined, config);
@@ -45,6 +60,9 @@ class CircuitBreakerOpenError extends HttpClientError {
     }
 }
 exports.CircuitBreakerOpenError = CircuitBreakerOpenError;
+/**
+ * API认证错误
+ */
 class AuthenticationError extends HttpClientError {
     constructor(message, statusCode = 401, response, config) {
         super(message, 'AUTHENTICATION_ERROR', statusCode, response, config);
@@ -52,6 +70,9 @@ class AuthenticationError extends HttpClientError {
     }
 }
 exports.AuthenticationError = AuthenticationError;
+/**
+ * API授权错误
+ */
 class AuthorizationError extends HttpClientError {
     constructor(message, statusCode = 403, response, config) {
         super(message, 'AUTHORIZATION_ERROR', statusCode, response, config);
@@ -59,6 +80,9 @@ class AuthorizationError extends HttpClientError {
     }
 }
 exports.AuthorizationError = AuthorizationError;
+/**
+ * 限流错误
+ */
 class RateLimitError extends HttpClientError {
     constructor(message, statusCode = 429, response, config, retryAfter, limit, remaining) {
         super(message, 'RATE_LIMIT_ERROR', statusCode, response, config);
@@ -69,6 +93,9 @@ class RateLimitError extends HttpClientError {
     }
 }
 exports.RateLimitError = RateLimitError;
+/**
+ * 服务器错误
+ */
 class ServerError extends HttpClientError {
     constructor(message, statusCode = 500, response, config) {
         super(message, 'SERVER_ERROR', statusCode, response, config);
@@ -76,6 +103,9 @@ class ServerError extends HttpClientError {
     }
 }
 exports.ServerError = ServerError;
+/**
+ * 响应格式错误
+ */
 class ResponseFormatError extends HttpClientError {
     constructor(message, responseData, config) {
         super(message, 'RESPONSE_FORMAT_ERROR', undefined, undefined, config);
@@ -84,6 +114,9 @@ class ResponseFormatError extends HttpClientError {
     }
 }
 exports.ResponseFormatError = ResponseFormatError;
+/**
+ * API客户端配置错误
+ */
 class ApiClientConfigError extends HttpClientError {
     constructor(message, config) {
         super(message, 'API_CLIENT_CONFIG_ERROR', 500, undefined, config);
@@ -91,6 +124,9 @@ class ApiClientConfigError extends HttpClientError {
     }
 }
 exports.ApiClientConfigError = ApiClientConfigError;
+/**
+ * 缓存错误
+ */
 class CacheError extends HttpClientError {
     constructor(message, config) {
         super(message, 'CACHE_ERROR', undefined, undefined, config);
@@ -98,11 +134,18 @@ class CacheError extends HttpClientError {
     }
 }
 exports.CacheError = CacheError;
+/**
+ * 错误工厂函数
+ */
 class ErrorFactory {
+    /**
+     * 根据axios错误创建对应的HTTP客户端错误
+     */
     static fromAxiosError(error) {
         const config = error.config;
         const response = error.response;
         const message = error.message || 'Unknown error';
+        // 网络错误
         if (!error.response) {
             if (error.code === 'ECONNABORTED') {
                 return new TimeoutError(`Request timeout: ${message}`, config);
@@ -130,18 +173,33 @@ class ErrorFactory {
                 return new HttpClientError((responseData === null || responseData === void 0 ? void 0 : responseData.message) || `HTTP error (${statusCode})`, 'HTTP_ERROR', statusCode, response, config);
         }
     }
+    /**
+     * 创建重试失败错误
+     */
     static createRetryExhaustedError(attempts, lastError, config) {
         return new RetryExhaustedError(`Retry failed after ${attempts} attempts. Last error: ${lastError.message}`, attempts, lastError, config);
     }
+    /**
+     * 创建熔断器开启错误
+     */
     static createCircuitBreakerOpenError(circuitName, failureCount, config) {
         return new CircuitBreakerOpenError(`Circuit breaker '${circuitName}' is open after ${failureCount} failures`, circuitName, failureCount, config);
     }
+    /**
+     * 创建响应格式错误
+     */
     static createResponseFormatError(message, responseData, config) {
         return new ResponseFormatError(message, responseData, config);
     }
+    /**
+     * 创建API客户端配置错误
+     */
     static createApiClientConfigError(message, config) {
         return new ApiClientConfigError(message, config);
     }
+    /**
+     * 创建缓存错误
+     */
     static createCacheError(message, config) {
         return new CacheError(message, config);
     }

package/http-client/examples/advanced-usage.example.d.ts

@@ -1,23 +1,64 @@
 import { HttpClientService } from '../services/http-client.service';
+/**
+ * 高级使用示例 - GitHub API客户端
+ * 集成现有的三层缓存架构
+ */
 export declare class GitHubHttpService {
     private httpClient;
     constructor(httpClient: HttpClientService);
+    /**
+     * 获取用户信息 - 带重试、熔断器、缓存和日志
+     */
     getUser(username: string): Promise<any>;
+    /**
+     * 搜索仓库 - 带重试和缓存
+     */
     searchRepositories(query: string, sort?: string, order?: string): Promise<any>;
+    /**
+     * 获取用户仓库 - 使用代理
+     */
     getUserRepositories(username: string): Promise<any>;
+    /**
+     * 创建仓库 - 带详细日志
+     */
     createRepository(repoData: any, token: string): Promise<any>;
+    /**
+     * 获取仓库贡献者 - 熔断器保护
+     */
     getRepositoryContributors(owner: string, repo: string): Promise<any>;
+    /**
+     * 批量获取用户信息 - 并行请求
+     */
     getMultipleUsers(usernames: string[]): Promise<any[]>;
+    /**
+     * 条件缓存示例
+     */
     getRepositoryDetails(owner: string, repo: string, options?: {
         public?: boolean;
     }): Promise<any>;
 }
+/**
+ * 支付服务示例 - 高安全性要求
+ * 使用Redis锁定确保并发安全
+ */
 export declare class PaymentHttpService {
     private httpClient;
     constructor(httpClient: HttpClientService);
+    /**
+     * 创建支付 - 严格的安全控制
+     */
     createPayment(paymentData: any, apiKey: string): Promise<any>;
+    /**
+     * 查询支付状态 - 可缓存
+     */
     getPaymentStatus(paymentId: string, apiKey: string): Promise<any>;
+    /**
+     * 退款操作 - 重试机制
+     */
     refundPayment(paymentId: string, refundData: any, apiKey: string): Promise<any>;
+    /**
+     * 动态调用示例 - 手动设置调用信息
+     */
     callExternalApi(url: string, method?: string, data?: any): Promise<any>;
     private generateIdempotencyKey;
 }

package/http-client/examples/advanced-usage.example.js

@@ -23,15 +23,25 @@ const common_1 = require("@nestjs/common");
 const decorators_1 = require("../decorators");
 const http_client_service_1 = require("../services/http-client.service");
 const cache_options_interface_1 = require("../../cache/interfaces/cache-options.interface");
+/**
+ * 高级使用示例 - GitHub API客户端
+ * 集成现有的三层缓存架构
+ */
 let GitHubHttpService = class GitHubHttpService {
     constructor(httpClient) {
         this.httpClient = httpClient;
     }
+    /**
+     * 获取用户信息 - 带重试、熔断器、缓存和日志
+     */
     getUser(username) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.httpClient.get(`/users/${username}`);
         });
     }
+    /**
+     * 搜索仓库 - 带重试和缓存
+     */
     searchRepositories(query_1) {
         return __awaiter(this, arguments, void 0, function* (query, sort = 'stars', order = 'desc') {
             return this.httpClient.get('/search/repositories', {
@@ -44,6 +54,9 @@ let GitHubHttpService = class GitHubHttpService {
             });
         });
     }
+    /**
+     * 获取用户仓库 - 使用代理
+     */
     getUserRepositories(username) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.httpClient.get(`/users/${username}/repos`, {
@@ -55,6 +68,9 @@ let GitHubHttpService = class GitHubHttpService {
             });
         });
     }
+    /**
+     * 创建仓库 - 带详细日志
+     */
     createRepository(repoData, token) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.httpClient.post('/user/repos', repoData, {
@@ -65,11 +81,17 @@ let GitHubHttpService = class GitHubHttpService {
             });
         });
     }
+    /**
+     * 获取仓库贡献者 - 熔断器保护
+     */
     getRepositoryContributors(owner, repo) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.httpClient.get(`/repos/${owner}/${repo}/contributors`);
         });
     }
+    /**
+     * 批量获取用户信息 - 并行请求
+     */
     getMultipleUsers(usernames) {
         return __awaiter(this, void 0, void 0, function* () {
             const promises = usernames.map((username) => this.getUser(username).catch((error) => {
@@ -79,6 +101,9 @@ let GitHubHttpService = class GitHubHttpService {
             return Promise.all(promises);
         });
     }
+    /**
+     * 条件缓存示例
+     */
     getRepositoryDetails(owner, repo, options) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.httpClient.get(`/repos/${owner}/${repo}`);
@@ -92,9 +117,9 @@ __decorate([
         retryDelay: (retryCount) => Math.pow(2, retryCount) * 1000,
         retryCondition: (error) => {
             if (!error.response)
-                return true;
+                return true; // 网络错误
             const status = error.response.status;
-            return status >= 500 || status === 429;
+            return status >= 500 || status === 429; // 5xx错误或429限流
         },
     }),
     (0, decorators_1.HttpCircuitBreaker)({
@@ -102,17 +127,17 @@ __decorate([
         recoveryTimeoutMs: 30000,
     }),
     (0, decorators_1.HttpCacheable)({
-        ttl: 300000,
-        layers: ['cls', 'memory', 'redis'],
+        ttl: 300000, // 5分钟缓存
+        layers: ['cls', 'memory', 'redis'], // 使用三层缓存
         namespace: 'github',
     }),
     (0, decorators_1.HttpLogRequest)({
         databaseLog: true,
         logHeaders: true,
         logBody: false,
-        serviceClass: 'GitHubHttpService',
-        methodName: 'getUser',
-        operationName: 'github.getUser',
+        serviceClass: 'GitHubHttpService', // 自定义服务类名
+        methodName: 'getUser', // 自定义方法名
+        operationName: 'github.getUser', // 自定义操作名
     }),
     (0, decorators_1.HttpTimeout)(15000),
     __metadata("design:type", Function),
@@ -122,10 +147,10 @@ __decorate([
 __decorate([
     (0, decorators_1.HttpRetry)({ retries: 3 }),
     (0, decorators_1.HttpCacheable)({
-        ttl: 600000,
-        layers: ['memory', 'redis'],
+        ttl: 600000, // 10分钟缓存
+        layers: ['memory', 'redis'], // 仅使用内存和Redis缓存
         namespace: 'github-search',
-        condition: (args) => args[0].length > 2,
+        condition: (args) => args[0].length > 2, // 只缓存搜索词长度大于2的请求
     }),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [String, String, String]),
@@ -138,7 +163,7 @@ __decorate([
         protocol: 'http',
     }),
     (0, decorators_1.HttpCacheable)({
-        ttl: 120000,
+        ttl: 120000, // 2分钟缓存
         namespace: 'github-repos',
     }),
     __metadata("design:type", Function),
@@ -162,7 +187,7 @@ __decorate([
         recoveryTimeoutMs: 60000,
     }),
     (0, decorators_1.HttpCacheable)({
-        ttl: 900000,
+        ttl: 900000, // 15分钟缓存
         namespace: 'github-contributors',
     }),
     __metadata("design:type", Function),
@@ -171,11 +196,11 @@ __decorate([
 ], GitHubHttpService.prototype, "getRepositoryContributors", null);
 __decorate([
     (0, decorators_1.HttpCacheable)({
-        ttl: 120000,
-        layers: ['memory'],
+        ttl: 120000, // 2分钟缓存
+        layers: ['memory'], // 仅内存缓存
         namespace: 'github-repo-details',
-        condition: (args) => { var _a; return ((_a = args[2]) === null || _a === void 0 ? void 0 : _a.public) === true; },
-        unless: (result, args) => (result === null || result === void 0 ? void 0 : result.archived) === true,
+        condition: (args) => { var _a; return ((_a = args[2]) === null || _a === void 0 ? void 0 : _a.public) === true; }, // 只缓存公开仓库
+        unless: (result, args) => (result === null || result === void 0 ? void 0 : result.archived) === true, // 不缓存已归档的仓库
     }),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [String, String, Object]),
@@ -191,7 +216,7 @@ exports.GitHubHttpService = GitHubHttpService = __decorate([
             cacheableMethods: ['GET', 'HEAD'],
             cacheableStatusCodes: [200, 304],
             options: {
-                layers: [cache_options_interface_1.CacheLayer.MEMORY, cache_options_interface_1.CacheLayer.REDIS],
+                layers: [cache_options_interface_1.CacheLayer.MEMORY, cache_options_interface_1.CacheLayer.REDIS], // 使用现有的三层缓存
             },
         },
         logging: {
@@ -209,10 +234,17 @@ exports.GitHubHttpService = GitHubHttpService = __decorate([
     (0, common_1.Injectable)(),
     __metadata("design:paramtypes", [http_client_service_1.HttpClientService])
 ], GitHubHttpService);
+/**
+ * 支付服务示例 - 高安全性要求
+ * 使用Redis锁定确保并发安全
+ */
 let PaymentHttpService = class PaymentHttpService {
     constructor(httpClient) {
         this.httpClient = httpClient;
     }
+    /**
+     * 创建支付 - 严格的安全控制
+     */
     createPayment(paymentData, apiKey) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.httpClient.post('/payments', paymentData, {
@@ -224,6 +256,9 @@ let PaymentHttpService = class PaymentHttpService {
             });
         });
     }
+    /**
+     * 查询支付状态 - 可缓存
+     */
     getPaymentStatus(paymentId, apiKey) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.httpClient.get(`/payments/${paymentId}`, {
@@ -233,6 +268,9 @@ let PaymentHttpService = class PaymentHttpService {
             });
         });
     }
+    /**
+     * 退款操作 - 重试机制
+     */
     refundPayment(paymentId, refundData, apiKey) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.httpClient.post(`/payments/${paymentId}/refund`, refundData, {
@@ -243,8 +281,12 @@ let PaymentHttpService = class PaymentHttpService {
             });
         });
     }
+    /**
+     * 动态调用示例 - 手动设置调用信息
+     */
     callExternalApi(url_1) {
         return __awaiter(this, arguments, void 0, function* (url, method = 'GET', data) {
+            // 手动设置调用信息
             const { CallStackExtractor } = require('../utils');
             CallStackExtractor.setCallInfo('PaymentHttpService', 'callExternalApi', `payment.${method.toLowerCase()}`);
             try {
@@ -259,6 +301,7 @@ let PaymentHttpService = class PaymentHttpService {
                 });
             }
             finally {
+                // 清理调用信息
                 CallStackExtractor.clearCallInfo();
             }
         });
@@ -281,8 +324,8 @@ __decorate([
 ], PaymentHttpService.prototype, "createPayment", null);
 __decorate([
     (0, decorators_1.HttpCacheable)({
-        ttl: 30000,
-        layers: ['redis'],
+        ttl: 30000, // 30秒缓存
+        layers: ['redis'], // 仅Redis缓存，确保多实例共享
         namespace: 'payment-status',
     }),
     __metadata("design:type", Function),
@@ -292,8 +335,9 @@ __decorate([
 __decorate([
     (0, decorators_1.HttpRetry)({
         retries: 2,
-        retryDelay: (retryCount) => retryCount * 2000,
+        retryDelay: (retryCount) => retryCount * 2000, // 线性退避
         retryCondition: (error) => {
+            // 只对网络错误和5xx错误重试，4xx错误不重试
             if (!error.response)
                 return true;
             return error.response.status >= 500;
@@ -302,7 +346,7 @@ __decorate([
     (0, decorators_1.HttpLogRequest)({
         logHeaders: false,
         logBody: false,
-        databaseLog: true,
+        databaseLog: true, // 退款操作需要记录到数据库
     }),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [String, Object, String]),
@@ -313,15 +357,15 @@ exports.PaymentHttpService = PaymentHttpService = __decorate([
         baseURL: 'https://api.payment-provider.com',
         timeout: 15000,
         retry: {
-            enabled: false,
+            enabled: false, // 支付操作不自动重试
         },
         logging: {
             enabled: true,
             logRequests: true,
             logResponses: true,
             logErrors: true,
-            logHeaders: false,
-            logBody: false,
+            logHeaders: false, // 不记录敏感头信息
+            logBody: false, // 不记录支付数据
             maxBodyLength: 1000,
             sanitizeHeaders: ['authorization', 'x-api-key', 'x-client-secret'],
             logLevel: 'info',

package/http-client/examples/auth-with-waiting-lock.example.d.ts

@@ -1,17 +1,48 @@
 import { HttpClientService } from '../services/http-client.service';
 import { HttpLogQueryService } from '../services/http-log-query.service';
 import { HttpReplayService } from '../services/http-replay.service';
+/**
+ * 使用等待锁的认证示例
+ * 演示如何在原有的HTTP客户端中使用等待锁机制
+ */
 export declare class AuthWithWaitingLockExample {
     private readonly httpClient;
     private readonly logQueryService;
     private readonly replayService;
     private readonly logger;
     constructor(httpClient: HttpClientService, logQueryService: HttpLogQueryService, replayService: HttpReplayService);
+    /**
+     * 示例1: 基本的带等待锁的认证请求
+     * 演示如何使用authRequest方法确保只有一个进程获取token
+     */
     basicAuthWithLock(): Promise<any>;
+    /**
+     * 示例2: 批量带等待锁的认证请求
+     * 演示如何在批量操作中共享token，避免重复认证
+     */
     batchAuthWithLock(): Promise<any[]>;
+    /**
+     * 示例3: 从HTTP日志生成curl命令
+     * 演示如何从已有的HTTP日志生成可执行的curl命令
+     */
     generateCurlFromLogs(): Promise<void>;
+    /**
+     * 示例4: 请求重放功能
+     * 演示如何重放已有的HTTP请求
+     */
     demonstrateRequestReplay(): Promise<void>;
+    /**
+     * 示例5: 批量重放和比较
+     * 演示如何批量重放请求并比较结果
+     */
     batchReplayAndCompare(): Promise<void>;
+    /**
+     * 示例6: 综合演示 - 等待锁 + curl生成 + 请求重放
+     * 演示完整的工作流程
+     */
     comprehensiveDemo(): Promise<void>;
+    /**
+     * 运行所有示例
+     */
     runAllExamples(): Promise<void>;
 }