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

package/http-client/decorators/http-client.decorators.js

@@ -5,6 +5,7 @@ require("reflect-metadata");
 const common_1 = require("@nestjs/common");
 const cache_options_interface_1 = require("../../cache/interfaces/cache-options.interface");
 const call_stack_extractor_util_1 = require("../utils/call-stack-extractor.util");
+// 装饰器元数据键
 exports.HTTP_CLIENT_OPTIONS_KEY = 'http_client_options';
 exports.RETRY_OPTIONS_KEY = 'http_retry_options';
 exports.CIRCUIT_BREAKER_OPTIONS_KEY = 'http_circuit_breaker_options';
@@ -13,12 +14,20 @@ exports.LOGGING_OPTIONS_KEY = 'http_logging_options';
 exports.TIMEOUT_OPTIONS_KEY = 'http_timeout_options';
 exports.PROXY_OPTIONS_KEY = 'http_proxy_options';
 exports.CALL_INFO_KEY = 'http_call_info';
+/**
+ * HTTP客户端装饰器
+ * 类似Spring Boot的@RestClient注解
+ */
 const HttpClient = (options = {}) => {
     return (target) => {
         (0, common_1.SetMetadata)(exports.HTTP_CLIENT_OPTIONS_KEY, options)(target);
     };
 };
 exports.HttpClient = HttpClient;
+/**
+ * 重试装饰器
+ * 基于axios-retry库
+ */
 const HttpRetry = (options = {}) => {
     return (target, propertyKey, descriptor) => {
         const retryOptions = {
@@ -27,10 +36,11 @@ const HttpRetry = (options = {}) => {
             retryDelay: options.retryDelay || ((retryCount) => Math.pow(2, retryCount) * 1000),
             retryCondition: options.retryCondition ||
                 ((error) => {
+                    // 默认重试条件：网络错误、超时、5xx错误、429错误
                     if (!error.response)
-                        return true;
+                        return true; // 网络错误
                     const status = error.response.status;
-                    return status >= 500 || status === 429;
+                    return status >= 500 || status === 429; // 5xx错误或429限流
                 }),
             shouldResetTimeout: options.shouldResetTimeout !== false,
             onRetry: options.onRetry,
@@ -40,6 +50,10 @@ const HttpRetry = (options = {}) => {
     };
 };
 exports.HttpRetry = HttpRetry;
+/**
+ * 熔断器装饰器
+ * 类似Spring Cloud CircuitBreaker的@CircuitBreaker注解
+ */
 const HttpCircuitBreaker = (options = {}) => {
     return (target, propertyKey, descriptor) => {
         const circuitBreakerOptions = {
@@ -55,12 +69,16 @@ const HttpCircuitBreaker = (options = {}) => {
     };
 };
 exports.HttpCircuitBreaker = HttpCircuitBreaker;
+/**
+ * HTTP缓存装饰器
+ * 集成现有的三层缓存架构
+ */
 const HttpCacheable = (options = {}) => {
     return (target, propertyKey, descriptor) => {
         var _a;
         const cacheOptions = {
             enabled: true,
-            defaultTtl: options.ttl || 300000,
+            defaultTtl: options.ttl || 300000, // 5分钟默认
             keyGenerator: typeof options.key === 'function'
                 ? (config) => options.key(config.url, config.method, config.data, config.params)
                 : options.key
@@ -85,20 +103,24 @@ const HttpCacheable = (options = {}) => {
             cacheableMethods: ['get'],
             cacheableStatusCodes: [200, 201, 202, 204, 301, 302, 304],
         };
+        // 处理unless条件
         if (options.unless) {
             const originalMethod = descriptor.value;
             descriptor.value = function (...args) {
                 const result = originalMethod.apply(this, args);
                 if (typeof options.unless === 'string') {
+                    // 如果是字符串，作为表达式求值
                     if (evalInContext(options.unless, { result, args })) {
                         return result;
                     }
                 }
                 else if (typeof options.unless === 'function') {
+                    // 如果是函数，直接调用
                     if (options.unless(result, args)) {
                         return result;
                     }
                 }
+                // 正常缓存
                 (0, common_1.SetMetadata)(`${exports.CACHE_OPTIONS_KEY}_${propertyKey}`, cacheOptions)(originalMethod);
                 return result;
             };
@@ -110,6 +132,10 @@ const HttpCacheable = (options = {}) => {
     };
 };
 exports.HttpCacheable = HttpCacheable;
+/**
+ * 请求日志装饰器
+ * 类似Spring Boot的@LogRequest注解
+ */
 const HttpLogRequest = (options = {}) => {
     return (target, propertyKey, descriptor) => {
         var _a, _b, _c;
@@ -128,6 +154,7 @@ const HttpLogRequest = (options = {}) => {
             databaseLog: (_c = options.databaseLog) !== null && _c !== void 0 ? _c : false,
             logLevel: options.logLevel || 'info',
         };
+        // 提取调用信息
         const decoratorInfo = call_stack_extractor_util_1.CallStackExtractor.extractFromDecorator(target, propertyKey);
         const callInfo = {
             serviceClass: options.serviceClass || decoratorInfo.serviceClass,
@@ -140,6 +167,10 @@ const HttpLogRequest = (options = {}) => {
     };
 };
 exports.HttpLogRequest = HttpLogRequest;
+/**
+ * 超时装饰器
+ * 类似Spring的@Timeout注解
+ */
 const HttpTimeout = (timeoutMs) => {
     return (target, propertyKey, descriptor) => {
         (0, common_1.SetMetadata)(`${exports.TIMEOUT_OPTIONS_KEY}_${propertyKey}`, timeoutMs)(descriptor.value);
@@ -147,6 +178,9 @@ const HttpTimeout = (timeoutMs) => {
     };
 };
 exports.HttpTimeout = HttpTimeout;
+/**
+ * 代理装饰器
+ */
 const HttpUseProxy = (options) => {
     return (target, propertyKey, descriptor) => {
         (0, common_1.SetMetadata)(`${exports.PROXY_OPTIONS_KEY}_${propertyKey}`, options)(descriptor.value);
@@ -154,31 +188,61 @@ const HttpUseProxy = (options) => {
     };
 };
 exports.HttpUseProxy = HttpUseProxy;
+/**
+ * 装饰器工具函数
+ */
 class HttpDecoratorUtils {
+    /**
+     * 获取方法上的重试配置
+     */
     static getRetryOptions(target, propertyKey) {
         return Reflect.getMetadata(`${exports.RETRY_OPTIONS_KEY}_${propertyKey}`, target[propertyKey]);
     }
+    /**
+     * 获取方法上的熔断器配置
+     */
     static getCircuitBreakerOptions(target, propertyKey) {
         return Reflect.getMetadata(`${exports.CIRCUIT_BREAKER_OPTIONS_KEY}_${propertyKey}`, target[propertyKey]);
     }
+    /**
+     * 获取方法上的缓存配置
+     */
     static getCacheOptions(target, propertyKey) {
         return Reflect.getMetadata(`${exports.CACHE_OPTIONS_KEY}_${propertyKey}`, target[propertyKey]);
     }
+    /**
+     * 获取方法上的日志配置
+     */
     static getLoggingOptions(target, propertyKey) {
         return Reflect.getMetadata(`${exports.LOGGING_OPTIONS_KEY}_${propertyKey}`, target[propertyKey]);
     }
+    /**
+     * 获取方法上的超时配置
+     */
     static getTimeoutOptions(target, propertyKey) {
         return Reflect.getMetadata(`${exports.TIMEOUT_OPTIONS_KEY}_${propertyKey}`, target[propertyKey]);
     }
+    /**
+     * 获取方法上的代理配置
+     */
     static getProxyOptions(target, propertyKey) {
         return Reflect.getMetadata(`${exports.PROXY_OPTIONS_KEY}_${propertyKey}`, target[propertyKey]);
     }
+    /**
+     * 获取类上的HTTP客户端配置
+     */
     static getHttpClientOptions(target) {
         return Reflect.getMetadata(exports.HTTP_CLIENT_OPTIONS_KEY, target) || {};
     }
+    /**
+     * 获取方法上的调用信息配置
+     */
     static getCallInfoOptions(target, propertyKey) {
         return Reflect.getMetadata(`${exports.CALL_INFO_KEY}_${propertyKey}`, target[propertyKey]);
     }
+    /**
+     * 获取所有装饰器配置
+     */
     static getAllDecoratorConfigs(target, propertyKey) {
         return {
             retry: this.getRetryOptions(target, propertyKey),
@@ -193,8 +257,12 @@ class HttpDecoratorUtils {
     }
 }
 exports.HttpDecoratorUtils = HttpDecoratorUtils;
+/**
+ * 在上下文中执行表达式
+ */
 function evalInContext(expression, context) {
     try {
+        // 创建一个安全的执行环境
         const func = new Function(...Object.keys(context), `return ${expression}`);
         return func(...Object.values(context));
     }

package/http-client/entities/http-log.entity.d.ts

@@ -1,95 +1,324 @@
 import { AbstractUuidPrimaryEntity } from '../../common';
+/**
+ * HTTP请求日志实体
+ * 用于TypeORM数据库记录
+ */
 export declare class HttpLogEntity extends AbstractUuidPrimaryEntity {
+    /**
+     * 请求ID（从ContextProvider获取）
+     */
     requestId?: string;
+    /**
+     * 用户ID（从ContextProvider获取）
+     */
     userId?: string;
+    /**
+     * HTTP方法
+     */
     method: string;
+    /**
+     * 请求URL
+     */
     url: string;
+    /**
+     * 请求头信息（JSON格式）
+     */
     headers?: Record<string, string>;
+    /**
+     * 请求体内容
+     */
     body?: string;
+    /**
+     * 查询参数（JSON格式）
+     */
     params?: Record<string, any>;
+    /**
+     * HTTP状态码
+     */
     statusCode?: number;
+    /**
+     * 响应时间（毫秒）
+     */
     responseTime: number;
+    /**
+     * 尝试次数
+     */
     attemptCount: number;
+    /**
+     * 是否成功
+     */
     success: boolean;
+    /**
+     * 错误信息
+     */
     errorMessage?: string;
+    /**
+     * 错误堆栈
+     */
     errorStack?: string;
+    /**
+     * 错误代码
+     */
     errorCode?: string;
+    /**
+     * 响应头信息（JSON格式）
+     */
     responseHeaders?: Record<string, string>;
+    /**
+     * 响应体内容
+     */
     responseBody?: string;
+    /**
+     * 响应大小（字节）
+     */
     responseSize?: number;
+    /**
+     * 请求大小（字节）
+     */
     requestSize?: number;
+    /**
+     * 服务名称（用于微服务环境）
+     */
     serviceName?: string;
+    /**
+     * 自定义操作名称（用于业务标识）
+     */
     operationName?: string;
+    /**
+     * 客户端IP地址
+     */
     clientIp?: string;
+    /**
+     * 请求来源
+     */
     source?: string;
+    /**
+     * 请求标签（用于分类）
+     */
     tags?: string[];
+    /**
+     * 请求元数据（JSON格式）
+     */
     metadata?: Record<string, any>;
+    /**
+     * 重试记录（JSON格式）
+     */
     retryRecords?: RetryRecord[];
+    /**
+     * 缓存命中状态
+     */
     cacheHit?: boolean;
+    /**
+     * 熔断器状态
+     */
     circuitBreakerState?: string;
 }
+/**
+ * 重试记录接口
+ */
 export interface RetryRecord {
+    /**
+     * 重试次数
+     */
     attempt: number;
+    /**
+     * 重试时间
+     */
     timestamp: Date;
+    /**
+     * 重试原因
+     */
     reason: string;
+    /**
+     * 重试延迟（毫秒）
+     */
     delay: number;
+    /**
+     * 错误信息
+     */
     error?: {
         message: string;
         code?: string;
         statusCode?: number;
     };
+    /**
+     * 请求配置（简化版）
+     */
     requestConfig?: {
         method: string;
         url: string;
         headers: Record<string, string>;
     };
 }
+/**
+ * HTTP日志查询选项
+ */
 export interface HttpLogQueryOptions {
+    /**
+     * 请求ID
+     */
     requestId?: string;
+    /**
+     * 用户ID
+     */
     userId?: string;
+    /**
+     * HTTP方法
+     */
     method?: string | string[];
+    /**
+     * URL（支持模糊搜索）
+     */
     url?: string;
+    /**
+     * 状态码
+     */
     statusCode?: number | number[];
+    /**
+     * 是否成功
+     */
     success?: boolean;
+    /**
+     * 服务名称
+     */
     serviceName?: string;
+    /**
+     * 操作名称
+     */
     operationName?: string;
+    /**
+     * 客户端IP
+     */
     clientIp?: string;
+    /**
+     * 请求来源
+     */
     source?: string;
+    /**
+     * 标签
+     */
     tags?: string[];
+    /**
+     * 错误代码
+     */
     errorCode?: string;
+    /**
+     * 最小响应时间
+     */
     minResponseTime?: number;
+    /**
+     * 最大响应时间
+     */
     maxResponseTime?: number;
+    /**
+     * 开始时间
+     */
     startDate?: Date;
+    /**
+     * 结束时间
+     */
     endDate?: Date;
+    /**
+     * 搜索关键词
+     */
     keyword?: string;
+    /**
+     * 分页参数
+     */
     page?: number;
+    /**
+     * 每页数量
+     */
     limit?: number;
+    /**
+     * 排序字段
+     */
     sortBy?: 'createdAt' | 'responseTime' | 'statusCode' | 'url';
+    /**
+     * 排序方向
+     */
     sortOrder?: 'ASC' | 'DESC';
+    /**
+     * 是否包含详细数据
+     */
     includeDetails?: boolean;
 }
+/**
+ * HTTP日志统计结果
+ */
 export interface HttpLogStats {
+    /**
+     * 总请求数
+     */
     totalRequests: number;
+    /**
+     * 成功请求数
+     */
     successfulRequests: number;
+    /**
+     * 失败请求数
+     */
     failedRequests: number;
+    /**
+     * 成功率
+     */
     successRate: number;
+    /**
+     * 平均响应时间
+     */
     averageResponseTime: number;
+    /**
+     * 最小响应时间
+     */
     minResponseTime: number;
+    /**
+     * 最大响应时间
+     */
     maxResponseTime: number;
+    /**
+     * P50响应时间
+     */
     p50ResponseTime: number;
+    /**
+     * P95响应时间
+     */
     p95ResponseTime: number;
+    /**
+     * P99响应时间
+     */
     p99ResponseTime: number;
+    /**
+     * 按方法统计
+     */
     requestsByMethod: Record<string, number>;
+    /**
+     * 按状态码统计
+     */
     requestsByStatus: Record<string, number>;
+    /**
+     * 按服务统计
+     */
     requestsByService: Record<string, number>;
+    /**
+     * 按来源统计
+     */
     requestsBySource: Record<string, number>;
+    /**
+     * 错误统计
+     */
     errorsByCode: Record<string, number>;
+    /**
+     * 重试统计
+     */
     retryStats: {
         totalRetries: number;
         averageRetries: number;
         maxRetries: number;
         retryRate: number;
     };
+    /**
+     * 缓存统计
+     */
     cacheStats: {
         cacheHits: number;
         cacheMisses: number;

package/http-client/entities/http-log.entity.js

@@ -12,6 +12,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpLogEntity = void 0;
 const typeorm_1 = require("typeorm");
 const common_1 = require("../../common");
+/**
+ * HTTP请求日志实体
+ * 用于TypeORM数据库记录
+ */
 let HttpLogEntity = class HttpLogEntity extends common_1.AbstractUuidPrimaryEntity {
 };
 exports.HttpLogEntity = HttpLogEntity;
@@ -103,7 +107,8 @@ __decorate([
     __metadata("design:type", String)
 ], HttpLogEntity.prototype, "operationName", void 0);
 __decorate([
-    (0, typeorm_1.Column)({ type: 'varchar', length: 45, nullable: true }),
+    (0, typeorm_1.Column)({ type: 'varchar', length: 45, nullable: true }) // 支持IPv6
+    ,
     __metadata("design:type", String)
 ], HttpLogEntity.prototype, "clientIp", void 0);
 __decorate([

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

@@ -1,3 +1,6 @@
+/**
+ * HTTP客户端基础错误类
+ */
 export declare class HttpClientError extends Error {
     readonly code: string;
     readonly statusCode?: number;
@@ -5,52 +8,106 @@ export declare class HttpClientError extends Error {
     readonly config?: any;
     constructor(message: string, code?: string, statusCode?: number, response?: any, config?: any);
 }
+/**
+ * 网络错误
+ */
 export declare class NetworkError extends HttpClientError {
     constructor(message: string, config?: any);
 }
+/**
+ * 超时错误
+ */
 export declare class TimeoutError extends HttpClientError {
     constructor(message: string, config?: any);
 }
+/**
+ * 重试失败错误
+ */
 export declare class RetryExhaustedError extends HttpClientError {
     readonly attempts: number;
     readonly lastError: any;
     constructor(message: string, attempts: number, lastError: any, config?: any);
 }
+/**
+ * 熔断器开启错误
+ */
 export declare class CircuitBreakerOpenError extends HttpClientError {
     readonly circuitName: string;
     readonly failureCount: number;
     constructor(message: string, circuitName: string, failureCount: number, config?: any);
 }
+/**
+ * API认证错误
+ */
 export declare class AuthenticationError extends HttpClientError {
     constructor(message: string, statusCode?: number, response?: any, config?: any);
 }
+/**
+ * API授权错误
+ */
 export declare class AuthorizationError extends HttpClientError {
     constructor(message: string, statusCode?: number, response?: any, config?: any);
 }
+/**
+ * 限流错误
+ */
 export declare class RateLimitError extends HttpClientError {
     readonly retryAfter?: number;
     readonly limit?: number;
     readonly remaining?: number;
     constructor(message: string, statusCode?: number, response?: any, config?: any, retryAfter?: number, limit?: number, remaining?: number);
 }
+/**
+ * 服务器错误
+ */
 export declare class ServerError extends HttpClientError {
     constructor(message: string, statusCode?: number, response?: any, config?: any);
 }
+/**
+ * 响应格式错误
+ */
 export declare class ResponseFormatError extends HttpClientError {
     readonly responseData: any;
     constructor(message: string, responseData: any, config?: any);
 }
+/**
+ * API客户端配置错误
+ */
 export declare class ApiClientConfigError extends HttpClientError {
     constructor(message: string, config?: any);
 }
+/**
+ * 缓存错误
+ */
 export declare class CacheError extends HttpClientError {
     constructor(message: string, config?: any);
 }
+/**
+ * 错误工厂函数
+ */
 export declare class ErrorFactory {
+    /**
+     * 根据axios错误创建对应的HTTP客户端错误
+     */
     static fromAxiosError(error: any): HttpClientError;
+    /**
+     * 创建重试失败错误
+     */
     static createRetryExhaustedError(attempts: number, lastError: any, config?: any): RetryExhaustedError;
+    /**
+     * 创建熔断器开启错误
+     */
     static createCircuitBreakerOpenError(circuitName: string, failureCount: number, config?: any): CircuitBreakerOpenError;
+    /**
+     * 创建响应格式错误
+     */
     static createResponseFormatError(message: string, responseData: any, config?: any): ResponseFormatError;
+    /**
+     * 创建API客户端配置错误
+     */
     static createApiClientConfigError(message: string, config?: any): ApiClientConfigError;
+    /**
+     * 创建缓存错误
+     */
     static createCacheError(message: string, config?: any): CacheError;
 }