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

package/http-client/services/logging.service.js

@@ -26,6 +26,10 @@ const http_log_entity_1 = require("../entities/http-log.entity");
 const request_id_util_1 = require("../utils/request-id.util");
 const context_extractor_util_1 = require("../utils/context-extractor.util");
 const call_stack_extractor_util_1 = require("../utils/call-stack-extractor.util");
+/**
+ * HTTP日志服务
+ * 基于Spring Boot的请求日志记录机制，集成现有的ContextProvider
+ */
 let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
     constructor(dataSource) {
         this.dataSource = dataSource;
@@ -35,7 +39,11 @@ let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
             this.initializeDatabaseLogging();
         }
     }
+    /**
+     * 记录请求开始
+     */
     logRequestStart(config, loggingOptions, requestId) {
+        // 从ContextProvider获取上下文信息
         const context = context_extractor_util_1.ContextExtractor.getHttpContext();
         const actualRequestId = requestId || context.requestId || (0, request_id_util_1.generateRequestId)();
         const { logHeaders = true, logBody = true, sanitizeHeaders = [], } = loggingOptions || {};
@@ -63,10 +71,14 @@ let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
         }
         return actualRequestId;
     }
+    /**
+     * 记录请求成功响应
+     */
     logRequestSuccess(response, startTime, requestId, loggingOptions, databaseLogging = false, retryRecords, cacheHit, circuitBreakerState, decoratorContext) {
         var _a, _b;
         const { logHeaders = true, logBody = true, sanitizeHeaders = [], } = loggingOptions || {};
         const responseTime = Date.now() - startTime;
+        // 获取当前上下文信息
         const context = context_extractor_util_1.ContextExtractor.getHttpContext();
         const logData = {
             requestId,
@@ -91,7 +103,9 @@ let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
                 this.logger.log(logMessage, logData);
                 break;
         }
+        // 数据库日志记录
         if (databaseLogging && this.logRepository) {
+            // 提取调用信息
             const callInfo = this.extractCallInfo(decoratorContext, response.config);
             this.saveToDatabase({
                 id: requestId,
@@ -126,10 +140,14 @@ let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
             });
         }
     }
+    /**
+     * 记录请求错误
+     */
     logRequestError(error, startTime, requestId, attemptCount, loggingOptions, databaseLogging = false, retryRecords, cacheHit, circuitBreakerState, decoratorContext) {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
         const { logHeaders = true, sanitizeHeaders = [] } = loggingOptions;
         const responseTime = Date.now() - startTime;
+        // 获取当前上下文信息
         const context = context_extractor_util_1.ContextExtractor.getHttpContext();
         const logData = {
             requestId,
@@ -160,7 +178,9 @@ let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
                 this.logger.error(logMessage, logData);
                 break;
         }
+        // 数据库日志记录
         if (databaseLogging && this.logRepository) {
+            // 提取调用信息
             const callInfo = this.extractCallInfo(decoratorContext, error.config);
             this.saveToDatabase({
                 id: requestId,
@@ -193,6 +213,9 @@ let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
             });
         }
     }
+    /**
+     * 查询请求日志
+     */
     findLogs(options) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.logRepository) {
@@ -243,6 +266,9 @@ let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
             return queryBuilder.getMany();
         });
     }
+    /**
+     * 获取请求统计信息
+     */
     getStatistics(options) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.logRepository) {
@@ -272,12 +298,14 @@ let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
                 .clone()
                 .select('AVG(log.responseTime)', 'avg')
                 .getRawOne();
+            // 按状态码统计
             const statusStats = yield queryBuilder
                 .clone()
                 .select('log.statusCode', 'statusCode')
                 .addSelect('COUNT(*)', 'count')
                 .groupBy('log.statusCode')
                 .getRawMany();
+            // 按方法统计
             const methodStats = yield queryBuilder
                 .clone()
                 .select('log.method', 'method')
@@ -301,6 +329,9 @@ let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
             };
         });
     }
+    /**
+     * 初始化数据库日志记录
+     */
     initializeDatabaseLogging() {
         return __awaiter(this, void 0, void 0, function* () {
             try {
@@ -312,7 +343,11 @@ let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
             }
         });
     }
+    /**
+     * 提取调用信息
+     */
     extractCallInfo(decoratorContext, config) {
+        // 优先使用装饰器配置的调用信息
         if (decoratorContext) {
             const decoratorInfo = call_stack_extractor_util_1.CallStackExtractor.extractFromDecorator(decoratorContext.target, decoratorContext.propertyKey);
             if (decoratorInfo.serviceClass && decoratorInfo.methodName) {
@@ -321,18 +356,21 @@ let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
                 };
             }
         }
+        // 然后尝试手动设置的调用信息
         const manualInfo = call_stack_extractor_util_1.CallStackExtractor.getManualCallInfo();
         if (manualInfo) {
             return {
                 operationName: manualInfo.operationName,
             };
         }
+        // 最后尝试从调用栈自动提取
         const stackInfo = call_stack_extractor_util_1.CallStackExtractor.getCallInfo();
         if (stackInfo.serviceClass && stackInfo.methodName) {
             return {
                 operationName: stackInfo.operationName,
             };
         }
+        // 如果都无法获取，根据URL生成操作名称
         if (config === null || config === void 0 ? void 0 : config.url) {
             const pathParts = config.url
                 .split('/')
@@ -346,6 +384,9 @@ let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
         }
         return {};
     }
+    /**
+     * 保存到数据库
+     */
     saveToDatabase(logEntity) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.logRepository)
@@ -358,6 +399,9 @@ let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
             }
         });
     }
+    /**
+     * 转换请求体为字符串
+     */
     sanitizeBodyAsString(data) {
         if (!data)
             return undefined;
@@ -369,6 +413,9 @@ let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
             ? jsonString.substring(0, 5000) + '...'
             : jsonString;
     }
+    /**
+     * 清理敏感头信息
+     */
     sanitizeHeaders(headers, sanitizeHeaders) {
         if (!headers)
             return {};
@@ -395,6 +442,9 @@ let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
         });
         return sanitized;
     }
+    /**
+     * 清理敏感请求体信息
+     */
     sanitizeBody(body) {
         if (!body)
             return undefined;
@@ -425,6 +475,9 @@ let HttpLoggingService = HttpLoggingService_1 = class HttpLoggingService {
         }
         return body;
     }
+    /**
+     * 递归清理对象中的敏感字段
+     */
     sanitizeObject(obj, sensitiveFields) {
         if (typeof obj !== 'object' || obj === null)
             return;

package/http-client/utils/call-stack-extractor.util.d.ts

@@ -1,29 +1,66 @@
+/**
+ * 调用栈提取工具
+ * 用于自动提取HTTP请求的调用服务和方法信息
+ */
 export declare class CallStackExtractor {
+    /**
+     * 从调用栈中提取服务和方法信息
+     */
     static extractCallInfo(): {
         serviceClass?: string;
         methodName?: string;
         operationName?: string;
     };
+    /**
+     * 手动设置调用信息（当自动检测失败时）
+     */
     static setCallInfo(serviceClass: string, methodName: string, operationName?: string): void;
+    /**
+     * 获取手动设置的调用信息
+     */
     static getManualCallInfo(): {
         serviceClass?: string;
         methodName?: string;
         operationName?: string;
     } | null;
+    /**
+     * 清理手动设置的调用信息
+     */
     static clearCallInfo(): void;
+    /**
+     * 获取调用信息（优先使用手动设置的信息）
+     */
     static getCallInfo(): {
         serviceClass?: string;
         methodName?: string;
         operationName?: string;
     };
+    /**
+     * 从装饰器中提取调用信息
+     */
     static extractFromDecorator(target: any, propertyKey: string): {
         serviceClass?: string;
         methodName?: string;
         operationName?: string;
     };
+    /**
+     * 生成操作名称
+     */
     static generateOperationName(serviceClass?: string, methodName?: string, config?: any): string;
+    /**
+     * 格式化服务类名
+     */
     static formatServiceClass(serviceClass?: string): string;
+    /**
+     * 格式化方法名
+     */
     static formatMethodName(methodName?: string): string;
+    /**
+     * 解析调用栈行
+     */
     private static parseStackLine;
+    /**
+     * 判断是否为内部调用
+     */
     private static isInternalCall;
 }

package/http-client/utils/call-stack-extractor.util.js

@@ -1,18 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CallStackExtractor = void 0;
+/**
+ * 调用栈提取工具
+ * 用于自动提取HTTP请求的调用服务和方法信息
+ */
 class CallStackExtractor {
+    /**
+     * 从调用栈中提取服务和方法信息
+     */
     static extractCallInfo() {
         const stack = new Error().stack;
         if (!stack) {
             return {};
         }
         const lines = stack.split('\n');
+        // 跳过当前函数和HTTP客户端内部调用
         const httpClientIndex = lines.findIndex((line) => line.includes('http-client.service.ts') ||
             line.includes('HttpClientService'));
         if (httpClientIndex === -1) {
             return {};
         }
+        // 查找实际的业务调用
         for (let i = httpClientIndex + 1; i < lines.length; i++) {
             const line = lines[i];
             const callInfo = this.parseStackLine(line);
@@ -22,7 +31,11 @@ class CallStackExtractor {
         }
         return {};
     }
+    /**
+     * 手动设置调用信息（当自动检测失败时）
+     */
     static setCallInfo(serviceClass, methodName, operationName) {
+        // 存储到当前上下文中
         if (typeof global !== 'undefined') {
             global.httpCallContext = {
                 serviceClass,
@@ -32,9 +45,13 @@ class CallStackExtractor {
             };
         }
     }
+    /**
+     * 获取手动设置的调用信息
+     */
     static getManualCallInfo() {
         if (typeof global !== 'undefined' && global.httpCallContext) {
             const context = global.httpCallContext;
+            // 清理过期的上下文（超过1秒）
             if (Date.now() - context.timestamp < 1000) {
                 return {
                     serviceClass: context.serviceClass,
@@ -46,18 +63,29 @@ class CallStackExtractor {
         }
         return null;
     }
+    /**
+     * 清理手动设置的调用信息
+     */
     static clearCallInfo() {
         if (typeof global !== 'undefined' && global.httpCallContext) {
             delete global.httpCallContext;
         }
     }
+    /**
+     * 获取调用信息（优先使用手动设置的信息）
+     */
     static getCallInfo() {
+        // 首先尝试获取手动设置的信息
         const manualInfo = this.getManualCallInfo();
         if (manualInfo) {
             return manualInfo;
         }
+        // 然后尝试从调用栈中自动提取
         return this.extractCallInfo();
     }
+    /**
+     * 从装饰器中提取调用信息
+     */
     static extractFromDecorator(target, propertyKey) {
         var _a;
         const serviceClass = (_a = target.constructor) === null || _a === void 0 ? void 0 : _a.name;
@@ -70,13 +98,18 @@ class CallStackExtractor {
                 : undefined,
         };
     }
+    /**
+     * 生成操作名称
+     */
     static generateOperationName(serviceClass, methodName, config) {
         if (!serviceClass || !methodName) {
             return 'Unknown';
         }
+        // 根据URL生成操作名称
         let operationName = `${serviceClass}.${methodName}`;
         if (config === null || config === void 0 ? void 0 : config.url) {
             const url = config.url;
+            // 提取URL中的关键路径部分
             const pathParts = url
                 .split('/')
                 .filter((part) => part && !part.includes('{'));
@@ -89,20 +122,32 @@ class CallStackExtractor {
         }
         return operationName;
     }
+    /**
+     * 格式化服务类名
+     */
     static formatServiceClass(serviceClass) {
         if (!serviceClass)
             return 'Unknown';
+        // 移除常见的后缀
         return serviceClass.replace(/Service|Controller|Provider|Handler$/, '');
     }
+    /**
+     * 格式化方法名
+     */
     static formatMethodName(methodName) {
         if (!methodName)
             return 'unknown';
+        // 将驼峰命名转换为更友好的格式
         return methodName
             .replace(/([A-Z])/g, ' $1')
             .replace(/^./, (str) => str.toUpperCase())
             .trim();
     }
+    /**
+     * 解析调用栈行
+     */
     static parseStackLine(line) {
+        // 匹配格式：at ClassName.methodName (/path/to/file.js:line:column)
         const match = line.match(/at\s+([^.]+)\.([^(]+)\s*\(/);
         if (!match) {
             return null;
@@ -114,6 +159,9 @@ class CallStackExtractor {
             operationName: `${serviceClass}.${methodName}`,
         };
     }
+    /**
+     * 判断是否为内部调用
+     */
     static isInternalCall(serviceClass) {
         if (!serviceClass)
             return true;

package/http-client/utils/context-extractor.util.d.ts

@@ -1,4 +1,11 @@
+/**
+ * 上下文信息提取器
+ * 从ContextProvider获取请求相关的上下文信息
+ */
 export declare class ContextExtractor {
+    /**
+     * 获取完整的HTTP请求上下文
+     */
     static getHttpContext(): {
         requestId?: string;
         userId?: string;
@@ -8,14 +15,41 @@ export declare class ContextExtractor {
         metadata?: Record<string, any>;
         tags?: string[];
     };
+    /**
+     * 获取请求ID
+     */
     static getRequestId(): string | undefined;
+    /**
+     * 获取用户ID
+     */
     static getUserId(): string | undefined;
+    /**
+     * 获取客户端IP
+     */
     static getClientIp(): string | undefined;
+    /**
+     * 获取用户代理
+     */
     static getUserAgent(): string | undefined;
+    /**
+     * 获取服务名称
+     */
     static getServiceName(): string | undefined;
+    /**
+     * 获取元数据
+     */
     static getMetadata(): Record<string, any> | undefined;
+    /**
+     * 获取标签
+     */
     static getTags(): string[];
+    /**
+     * 添加标签到上下文
+     */
     static addTag(tag: string): void;
+    /**
+     * 获取上下文摘要
+     */
     static getContextSummary(): {
         requestId?: string;
         userId?: string;
@@ -24,13 +58,22 @@ export declare class ContextExtractor {
         hasUser: boolean;
         requestSource: string;
     };
+    /**
+     * 获取请求来源信息
+     */
     static getRequestSource(): {
         source: 'internal' | 'external' | 'unknown';
         ip?: string;
         userAgent?: string;
         service?: string;
     };
+    /**
+     * 判断是否为内部请求
+     */
     static isInternalRequest(): boolean;
+    /**
+     * 获取安全上下文
+     */
     static getSecurityContext(): {
         isAuthenticated: boolean;
         userId?: string;
@@ -39,6 +82,12 @@ export declare class ContextExtractor {
         permissions: string[];
         securityLevel: 'low' | 'medium' | 'high';
     };
+    /**
+     * 生成Span ID
+     */
     private static generateSpanId;
+    /**
+     * 检查172.x.x.x是否为内网IP (172.16.0.0 - 172.31.255.255)
+     */
     private static isInternal172IP;
 }

package/http-client/utils/context-extractor.util.js

@@ -2,7 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContextExtractor = void 0;
 const providers_1 = require("../../providers");
+/**
+ * 上下文信息提取器
+ * 从ContextProvider获取请求相关的上下文信息
+ */
 class ContextExtractor {
+    /**
+     * 获取完整的HTTP请求上下文
+     */
     static getHttpContext() {
         try {
             const requestId = providers_1.ContextProvider.getRequestId();
@@ -21,11 +28,15 @@ class ContextExtractor {
             };
         }
         catch (_a) {
+            // If no context is available, return empty context
             return {
                 tags: [],
             };
         }
     }
+    /**
+     * 获取请求ID
+     */
     static getRequestId() {
         try {
             return providers_1.ContextProvider.getRequestId();
@@ -34,6 +45,9 @@ class ContextExtractor {
             return undefined;
         }
     }
+    /**
+     * 获取用户ID
+     */
     static getUserId() {
         try {
             const authUser = providers_1.ContextProvider.getAuthUser();
@@ -43,6 +57,9 @@ class ContextExtractor {
             return undefined;
         }
     }
+    /**
+     * 获取客户端IP
+     */
     static getClientIp() {
         try {
             const router = providers_1.ContextProvider.getRouter();
@@ -52,6 +69,9 @@ class ContextExtractor {
             return undefined;
         }
     }
+    /**
+     * 获取用户代理
+     */
     static getUserAgent() {
         try {
             const router = providers_1.ContextProvider.getRouter();
@@ -61,6 +81,9 @@ class ContextExtractor {
             return undefined;
         }
     }
+    /**
+     * 获取服务名称
+     */
     static getServiceName() {
         try {
             const authUser = providers_1.ContextProvider.getAuthUser();
@@ -70,6 +93,9 @@ class ContextExtractor {
             return undefined;
         }
     }
+    /**
+     * 获取元数据
+     */
     static getMetadata() {
         try {
             const authUser = providers_1.ContextProvider.getAuthUser();
@@ -83,6 +109,9 @@ class ContextExtractor {
             return undefined;
         }
     }
+    /**
+     * 获取标签
+     */
     static getTags() {
         try {
             const context = this.getHttpContext();
@@ -92,6 +121,9 @@ class ContextExtractor {
             return [];
         }
     }
+    /**
+     * 添加标签到上下文
+     */
     static addTag(tag) {
         try {
             const context = this.getHttpContext();
@@ -102,8 +134,12 @@ class ContextExtractor {
             }
         }
         catch (_a) {
+            // Silently fail if context is not available
         }
     }
+    /**
+     * 获取上下文摘要
+     */
     static getContextSummary() {
         const context = this.getHttpContext();
         return {
@@ -115,11 +151,15 @@ class ContextExtractor {
             requestSource: this.getRequestSource().source,
         };
     }
+    /**
+     * 获取请求来源信息
+     */
     static getRequestSource() {
         const context = this.getHttpContext();
         if (!context.clientIp) {
             return { source: 'unknown' };
         }
+        // Check if it's an internal IP
         const internalIPs = ['::1', '127.0.0.1', 'localhost'];
         const isInternal = internalIPs.includes(context.clientIp) ||
             context.clientIp.startsWith('192.168.') ||
@@ -133,10 +173,16 @@ class ContextExtractor {
             service: context.appId,
         };
     }
+    /**
+     * 判断是否为内部请求
+     */
     static isInternalRequest() {
         const requestSource = this.getRequestSource();
         return requestSource.source === 'internal';
     }
+    /**
+     * 获取安全上下文
+     */
     static getSecurityContext() {
         try {
             const authUser = providers_1.ContextProvider.getAuthUser();
@@ -157,9 +203,15 @@ class ContextExtractor {
             };
         }
     }
+    /**
+     * 生成Span ID
+     */
     static generateSpanId() {
         return Math.random().toString(36).substring(2, 15);
     }
+    /**
+     * 检查172.x.x.x是否为内网IP (172.16.0.0 - 172.31.255.255)
+     */
     static isInternal172IP(ip) {
         if (!ip.startsWith('172.'))
             return false;

package/http-client/utils/curl-generator.util.d.ts

@@ -1,9 +1,30 @@
 import { AxiosRequestConfig, AxiosResponse } from 'axios';
+/**
+ * HTTP请求curl命令生成器
+ */
 export declare class CurlGenerator {
+    /**
+     * 生成curl命令
+     */
     static generateCurlCommand(config: AxiosRequestConfig, response?: AxiosResponse): string;
+    /**
+     * 生成简化的curl命令（用于日志记录）
+     */
     static generateSimplifiedCurl(config: AxiosRequestConfig): string;
+    /**
+     * 生成用于调试的详细curl命令
+     */
     static generateDebugCurl(config: AxiosRequestConfig, response?: AxiosResponse): string;
+    /**
+     * 从curl命令解析请求配置
+     */
     static parseCurlCommand(curlCommand: string): Partial<AxiosRequestConfig>;
+    /**
+     * 构建完整URL
+     */
     private static buildUrl;
+    /**
+     * 过滤敏感头信息
+     */
     private static sanitizeHeaderValue;
 }