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

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

@@ -1,23 +1,63 @@
 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

@@ -22,16 +22,24 @@ exports.PaymentHttpService = exports.GitHubHttpService = void 0;
 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 +52,9 @@ let GitHubHttpService = class GitHubHttpService {
             });
         });
     }
+    /**
+     * 获取用户仓库 - 使用代理
+     */
     getUserRepositories(username) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.httpClient.get(`/users/${username}/repos`, {
@@ -55,6 +66,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 +79,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 +99,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,27 +115,22 @@ __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)({
         failureThreshold: 3,
         recoveryTimeoutMs: 30000,
     }),
-    (0, decorators_1.HttpCacheable)({
-        ttl: 300000,
-        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),
@@ -121,12 +139,6 @@ __decorate([
 ], GitHubHttpService.prototype, "getUser", null);
 __decorate([
     (0, decorators_1.HttpRetry)({ retries: 3 }),
-    (0, decorators_1.HttpCacheable)({
-        ttl: 600000,
-        layers: ['memory', 'redis'],
-        namespace: 'github-search',
-        condition: (args) => args[0].length > 2,
-    }),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [String, String, String]),
     __metadata("design:returntype", Promise)
@@ -137,10 +149,6 @@ __decorate([
         port: 8080,
         protocol: 'http',
     }),
-    (0, decorators_1.HttpCacheable)({
-        ttl: 120000,
-        namespace: 'github-repos',
-    }),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [String]),
     __metadata("design:returntype", Promise)
@@ -161,39 +169,14 @@ __decorate([
         failureThreshold: 5,
         recoveryTimeoutMs: 60000,
     }),
-    (0, decorators_1.HttpCacheable)({
-        ttl: 900000,
-        namespace: 'github-contributors',
-    }),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [String, String]),
     __metadata("design:returntype", Promise)
 ], GitHubHttpService.prototype, "getRepositoryContributors", null);
-__decorate([
-    (0, decorators_1.HttpCacheable)({
-        ttl: 120000,
-        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,
-    }),
-    __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, String, Object]),
-    __metadata("design:returntype", Promise)
-], GitHubHttpService.prototype, "getRepositoryDetails", null);
 exports.GitHubHttpService = GitHubHttpService = __decorate([
     (0, decorators_1.HttpClient)({
         baseURL: 'https://api.github.com',
         timeout: 10000,
-        cache: {
-            enabled: true,
-            defaultTtl: 300000,
-            cacheableMethods: ['GET', 'HEAD'],
-            cacheableStatusCodes: [200, 304],
-            options: {
-                layers: [cache_options_interface_1.CacheLayer.MEMORY, cache_options_interface_1.CacheLayer.REDIS],
-            },
-        },
         logging: {
             enabled: true,
             logRequests: true,
@@ -209,10 +192,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 +214,9 @@ let PaymentHttpService = class PaymentHttpService {
             });
         });
     }
+    /**
+     * 查询支付状态
+     */
     getPaymentStatus(paymentId, apiKey) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.httpClient.get(`/payments/${paymentId}`, {
@@ -233,6 +226,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 +239,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 +259,7 @@ let PaymentHttpService = class PaymentHttpService {
                 });
             }
             finally {
+                // 清理调用信息
                 CallStackExtractor.clearCallInfo();
             }
         });
@@ -279,21 +280,12 @@ __decorate([
     __metadata("design:paramtypes", [Object, String]),
     __metadata("design:returntype", Promise)
 ], PaymentHttpService.prototype, "createPayment", null);
-__decorate([
-    (0, decorators_1.HttpCacheable)({
-        ttl: 30000,
-        layers: ['redis'],
-        namespace: 'payment-status',
-    }),
-    __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, String]),
-    __metadata("design:returntype", Promise)
-], PaymentHttpService.prototype, "getPaymentStatus", null);
 __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 +294,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 +305,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>;
 }

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

@@ -24,6 +24,10 @@ const common_1 = require("@nestjs/common");
 const http_client_service_1 = require("../services/http-client.service");
 const http_log_query_service_1 = require("../services/http-log-query.service");
 const http_replay_service_1 = require("../services/http-replay.service");
+/**
+ * 使用等待锁的认证示例
+ * 演示如何在原有的HTTP客户端中使用等待锁机制
+ */
 let AuthWithWaitingLockExample = AuthWithWaitingLockExample_1 = class AuthWithWaitingLockExample {
     constructor(httpClient, logQueryService, replayService) {
         this.httpClient = httpClient;
@@ -31,6 +35,10 @@ let AuthWithWaitingLockExample = AuthWithWaitingLockExample_1 = class AuthWithWa
         this.replayService = replayService;
         this.logger = new common_1.Logger(AuthWithWaitingLockExample_1.name);
     }
+    /**
+     * 示例1: 基本的带等待锁的认证请求
+     * 演示如何使用authRequest方法确保只有一个进程获取token
+     */
     basicAuthWithLock() {
         return __awaiter(this, void 0, void 0, function* () {
             this.logger.log('=== 示例1: 基本带等待锁的认证请求 ===');
@@ -41,18 +49,21 @@ let AuthWithWaitingLockExample = AuthWithWaitingLockExample_1 = class AuthWithWa
                     Accept: 'application/vnd.github.v3+json',
                 },
             };
+            // Token提供函数
             const tokenProvider = () => __awaiter(this, void 0, void 0, function* () {
                 this.logger.log('开始获取GitHub访问令牌...');
+                // 模拟token获取过程
                 yield new Promise((resolve) => setTimeout(resolve, 1000));
                 const token = `ghp_${Math.random().toString(36).substring(2, 15)}${Date.now()}`;
                 this.logger.log(`成功获取令牌: ${token.substring(0, 20)}...`);
                 return token;
             });
             try {
+                // 使用等待锁执行认证请求
                 const response = yield this.httpClient.authRequest(requestConfig, tokenProvider, {
                     lockKey: 'github-token-refresh',
-                    lockTimeout: 30000,
-                    waitTimeout: 60000,
+                    lockTimeout: 30000, // 30秒锁超时
+                    waitTimeout: 60000, // 60秒等待超时
                     enableRetry: true,
                 });
                 this.logger.log('认证请求成功完成');
@@ -64,6 +75,10 @@ let AuthWithWaitingLockExample = AuthWithWaitingLockExample_1 = class AuthWithWa
             }
         });
     }
+    /**
+     * 示例2: 批量带等待锁的认证请求
+     * 演示如何在批量操作中共享token，避免重复认证
+     */
     batchAuthWithLock() {
         return __awaiter(this, void 0, void 0, function* () {
             this.logger.log('=== 示例2: 批量带等待锁的认证请求 ===');
@@ -90,6 +105,7 @@ let AuthWithWaitingLockExample = AuthWithWaitingLockExample_1 = class AuthWithWa
                     key: 'user-followers',
                 },
             ];
+            // Token提供函数
             const tokenProvider = () => __awaiter(this, void 0, void 0, function* () {
                 this.logger.log('开始获取批量操作的GitHub访问令牌...');
                 yield new Promise((resolve) => setTimeout(resolve, 1500));
@@ -99,11 +115,12 @@ let AuthWithWaitingLockExample = AuthWithWaitingLockExample_1 = class AuthWithWa
             });
             try {
                 const startTime = Date.now();
+                // 使用批量认证请求，所有请求共享同一个token
                 const results = yield this.httpClient.authBatchRequest(requests, tokenProvider, {
                     lockKey: 'github-batch-token-refresh',
-                    lockTimeout: 60000,
-                    waitTimeout: 120000,
-                    maxConcurrency: 3,
+                    lockTimeout: 60000, // 60秒锁超时
+                    waitTimeout: 120000, // 2分钟等待超时
+                    maxConcurrency: 3, // 最大并发数
                 });
                 const endTime = Date.now();
                 const duration = endTime - startTime;
@@ -125,10 +142,15 @@ let AuthWithWaitingLockExample = AuthWithWaitingLockExample_1 = class AuthWithWa
             }
         });
     }
+    /**
+     * 示例3: 从HTTP日志生成curl命令
+     * 演示如何从已有的HTTP日志生成可执行的curl命令
+     */
     generateCurlFromLogs() {
         return __awaiter(this, void 0, void 0, function* () {
             this.logger.log('=== 示例3: 从HTTP日志生成curl命令 ===');
             try {
+                // 查询最近的日志
                 const recentLogs = yield this.logQueryService.findLogs({
                     limit: 5,
                     sortBy: 'createdAt',
@@ -139,6 +161,7 @@ let AuthWithWaitingLockExample = AuthWithWaitingLockExample_1 = class AuthWithWa
                     return;
                 }
                 this.logger.log(`找到 ${recentLogs.logs.length} 条最近的HTTP日志`);
+                // 为每条日志生成curl命令
                 for (const log of recentLogs.logs) {
                     const curlCommand = yield this.logQueryService.generateCurlFromLog(log.id);
                     if (curlCommand) {
@@ -148,6 +171,7 @@ ${curlCommand}
           `);
                     }
                 }
+                // 批量生成curl命令
                 const batchCurlCommands = yield this.logQueryService.generateBatchCurlCommands({
                     limit: 3,
                     method: 'GET',
@@ -159,11 +183,16 @@ ${curlCommand}
             }
         });
     }
+    /**
+     * 示例4: 请求重放功能
+     * 演示如何重放已有的HTTP请求
+     */
     demonstrateRequestReplay() {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c;
             this.logger.log('=== 示例4: 请求重放功能 ===');
             try {
+                // 查询一个成功的请求进行重放
                 const successfulLogs = yield this.logQueryService.findLogs({
                     limit: 1,
                     success: true,
@@ -177,6 +206,7 @@ ${curlCommand}
                 }
                 const logToReplay = successfulLogs.logs[0];
                 this.logger.log(`准备重放请求: ${logToReplay.method} ${logToReplay.url}`);
+                // 重放请求
                 const replayResult = yield this.replayService.replayByLogId(logToReplay.id, {
                     overrideHeaders: false,
                     additionalHeaders: {
@@ -206,11 +236,16 @@ ${curlCommand}
             }
         });
     }
+    /**
+     * 示例5: 批量重放和比较
+     * 演示如何批量重放请求并比较结果
+     */
     batchReplayAndCompare() {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c;
             this.logger.log('=== 示例5: 批量重放和比较 ===');
             try {
+                // 查询最近的3个GET请求进行批量重放
                 const batchReplayResult = yield this.replayService.batchReplayByQuery({
                     method: 'GET',
                     limit: 3,
@@ -234,6 +269,7 @@ ${curlCommand}
 │ 平均响应时间    │ ${batchReplayResult.averageResponseTime.toFixed(1).toString().padStart(7)}ms │
 └─────────────────┴──────────┘
       `);
+                // 详细比较每个重放结果
                 for (let i = 0; i < Math.min(batchReplayResult.results.length, 3); i++) {
                     const result = batchReplayResult.results[i];
                     if (result.originalLog.id) {
@@ -262,12 +298,18 @@ ${curlCommand}
             }
         });
     }
+    /**
+     * 示例6: 综合演示 - 等待锁 + curl生成 + 请求重放
+     * 演示完整的工作流程
+     */
     comprehensiveDemo() {
         return __awaiter(this, void 0, void 0, function* () {
             this.logger.log('=== 示例6: 综合演示 ===');
             try {
+                // 1. 执行带等待锁的认证请求
                 this.logger.log('步骤1: 执行带等待锁的认证请求');
                 const authResponse = yield this.basicAuthWithLock();
+                // 2. 查询刚才的请求日志
                 this.logger.log('\n步骤2: 查询请求日志');
                 const recentLogs = yield this.logQueryService.findLogs({
                     limit: 1,
@@ -276,12 +318,14 @@ ${curlCommand}
                 });
                 if (recentLogs.logs.length > 0) {
                     const log = recentLogs.logs[0];
+                    // 3. 生成curl命令
                     this.logger.log('\n步骤3: 生成curl命令');
                     const curlCommand = yield this.logQueryService.generateCurlFromLog(log.id);
                     if (curlCommand) {
                         this.logger.log('生成的curl命令:');
                         this.logger.log(curlCommand);
                     }
+                    // 4. 重放请求
                     this.logger.log('\n步骤4: 重放请求');
                     const replayResult = yield this.replayService.replayByLogId(log.id, {
                         additionalHeaders: {
@@ -304,6 +348,9 @@ ${curlCommand}
             }
         });
     }
+    /**
+     * 运行所有示例
+     */
     runAllExamples() {
         return __awaiter(this, void 0, void 0, function* () {
             this.logger.log('开始运行HTTP客户端等待锁和请求重放示例...\n');