create-dp-koa 1.0.0

package/template/src/framework/decorator/swagger.ts

@@ -0,0 +1,150 @@
+/**
+ * Swagger装饰器 - 用于在Controller层生成API文档
+ */
+
+/**
+ * API文档基本配置装饰器
+ */
+export function Api(
+    config: {
+        tags?: string[];
+        summary?: string;
+        description?: string;
+        operationId?: string;
+    } = {}
+): MethodDecorator {
+    return (target: any, methodName: string | symbol) => {
+        if (!target.$_SwaggerMethods) {
+            target.$_SwaggerMethods = new Map();
+        }
+        
+        const methodMetadata = {
+            tags: config.tags || [],
+            summary: config.summary || '',
+            description: config.description || '',
+            operationId: config.operationId || methodName.toString(),
+        };
+        
+        target.$_SwaggerMethods.set(methodName.toString(), methodMetadata);
+    };
+}
+
+/**
+ * API参数装饰器
+ */
+export function ApiParam(
+    config: {
+        name: string;
+        in: 'path' | 'query' | 'header' | 'cookie';
+        description?: string;
+        required?: boolean;
+        schema?: any;
+        example?: any;
+    }
+): ParameterDecorator {
+    return (target: any, propertyKey: string | symbol | undefined, parameterIndex: number) => {
+        if (!target.$_SwaggerParams) {
+            target.$_SwaggerParams = new Map();
+        }
+        
+        const methodName = propertyKey?.toString() || '';
+        if (!target.$_SwaggerParams.has(methodName)) {
+            target.$_SwaggerParams.set(methodName, []);
+        }
+        
+        const params = target.$_SwaggerParams.get(methodName);
+        params.push({
+            ...config,
+            parameterIndex,
+        });
+    };
+}
+
+/**
+ * API请求体装饰器
+ */
+export function ApiBody(
+    config: {
+        description?: string;
+        required?: boolean;
+        schema: any;
+        examples?: Record<string, any>;
+    }
+): MethodDecorator {
+    return (target: any, methodName: string | symbol) => {
+        if (!target.$_SwaggerBodies) {
+            target.$_SwaggerBodies = new Map();
+        }
+        
+        target.$_SwaggerBodies.set(methodName.toString(), config);
+    };
+}
+
+/**
+ * API响应装饰器
+ */
+export function ApiResponse(
+    config: {
+        status: number;
+        description: string;
+        schema?: any;
+        examples?: Record<string, any>;
+    }
+): MethodDecorator {
+    return (target: any, methodName: string | symbol) => {
+        if (!target.$_SwaggerResponses) {
+            target.$_SwaggerResponses = new Map();
+        }
+        
+        const methodNameStr = methodName.toString();
+        if (!target.$_SwaggerResponses.has(methodNameStr)) {
+            target.$_SwaggerResponses.set(methodNameStr, []);
+        }
+        
+        const responses = target.$_SwaggerResponses.get(methodNameStr);
+        responses.push(config);
+    };
+}
+
+/**
+ * API标签装饰器（用于Controller类）
+ */
+export function ApiTags(...tags: string[]): ClassDecorator {
+    return (target: any) => {
+        target.$_SwaggerTags = tags;
+    };
+}
+
+/**
+ * API操作装饰器（用于Controller类）
+ */
+export function ApiOperation(
+    config: {
+        summary?: string;
+        description?: string;
+        operationId?: string;
+    } = {}
+): MethodDecorator {
+    return (target: any, methodName: string | symbol) => {
+        if (!target.$_SwaggerOperations) {
+            target.$_SwaggerOperations = new Map();
+        }
+        
+        target.$_SwaggerOperations.set(methodName.toString(), config);
+    };
+}
+
+/**
+ * 获取Swagger元数据
+ */
+export function getSwaggerMetadata(target: any) {
+    return {
+        tags: target.$_SwaggerTags || [],
+        methods: target.$_SwaggerMethods || new Map(),
+        params: target.$_SwaggerParams || new Map(),
+        bodies: target.$_SwaggerBodies || new Map(),
+        responses: target.$_SwaggerResponses || new Map(),
+        operations: target.$_SwaggerOperations || new Map(),
+    };
+}
+

package/template/src/framework/interceptors/AdvancedServiceCallInterceptor.ts

@@ -0,0 +1,375 @@
+/**
+ * 高级Service调用拦截器
+ * 支持性能监控、缓存、重试等功能
+ */
+
+import { logger } from '@src/framework/utils/logger';
+import { ServiceCallInterceptor, ServiceCallInfo, ServiceCallPhase } from './ServiceCallInterceptor';
+
+/**
+ * 拦截器配置选项
+ */
+export interface InterceptorOptions {
+    enablePerformanceMonitoring?: boolean;
+    enableCaching?: boolean;
+    enableRetry?: boolean;
+    enableCircuitBreaker?: boolean;
+    cacheTTL?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+    circuitBreakerThreshold?: number;
+    slowCallThreshold?: number;
+}
+
+/**
+ * 缓存项
+ */
+interface CacheItem {
+    key: string;
+    value: any;
+    timestamp: number;
+    ttl: number;
+}
+
+/**
+ * 熔断器状态
+ */
+enum CircuitBreakerState {
+    CLOSED = 'CLOSED',
+    OPEN = 'OPEN',
+    HALF_OPEN = 'HALF_OPEN'
+}
+
+/**
+ * 高级Service调用拦截器
+ */
+export class AdvancedServiceCallInterceptor {
+    private static instance: AdvancedServiceCallInterceptor;
+    private cache = new Map<string, CacheItem>();
+    private circuitBreakerState = new Map<string, CircuitBreakerState>();
+    private circuitBreakerFailures = new Map<string, number>();
+    private circuitBreakerLastFailure = new Map<string, number>();
+    private slowCalls = new Map<string, number>();
+    private options: InterceptorOptions;
+
+    constructor(options: InterceptorOptions = {}) {
+        this.options = {
+            enablePerformanceMonitoring: true,
+            enableCaching: false,
+            enableRetry: false,
+            enableCircuitBreaker: false,
+            cacheTTL: 300000, // 5分钟
+            maxRetries: 3,
+            retryDelay: 1000,
+            circuitBreakerThreshold: 5,
+            slowCallThreshold: 1000,
+            ...options
+        };
+    }
+
+    /**
+     * 获取单例实例
+     */
+    public static getInstance(options?: InterceptorOptions): AdvancedServiceCallInterceptor {
+        if (!AdvancedServiceCallInterceptor.instance) {
+            AdvancedServiceCallInterceptor.instance = new AdvancedServiceCallInterceptor(options);
+        }
+        return AdvancedServiceCallInterceptor.instance;
+    }
+
+    /**
+     * 创建高级拦截器函数
+     */
+    public createAdvancedInterceptor() {
+        return (params: Array<any>, instance: any, fn: Function, done: (err: any, param: any) => void) => {
+            const serviceName = instance.constructor.name;
+            const methodName = fn.name;
+            const methodKey = `${serviceName}.${methodName}`;
+            
+            // 检查熔断器状态
+            if (this.options.enableCircuitBreaker && this.isCircuitBreakerOpen(methodKey)) {
+                const error = new Error(`Circuit breaker is open for ${methodKey}`);
+                logger.warn(`熔断器开启，跳过方法调用: ${methodKey}`);
+                done(error, null);
+                return;
+            }
+
+            // 检查缓存
+            if (this.options.enableCaching) {
+                const cacheKey = this.generateCacheKey(methodKey, params);
+                const cachedResult = this.getFromCache(cacheKey);
+                if (cachedResult) {
+                    logger.info(`缓存命中: ${methodKey}`);
+                    done(null, cachedResult);
+                    return;
+                }
+            }
+
+            // 执行方法（带重试）
+            this.executeWithRetry(params, instance, fn, done, methodKey);
+        };
+    }
+
+    /**
+     * 带重试的执行方法
+     */
+    private async executeWithRetry(
+        params: Array<any>, 
+        instance: any, 
+        fn: Function, 
+        done: (err: any, param: any) => void,
+        methodKey: string
+    ) {
+        let lastError: Error | null = null;
+        const maxRetries = this.options.maxRetries || 3;
+        
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const result = await this.executeMethod(params, instance, fn, methodKey, attempt);
+                
+                // 成功时重置熔断器
+                if (this.options.enableCircuitBreaker) {
+                    this.resetCircuitBreaker(methodKey);
+                }
+                
+                // 缓存结果
+                if (this.options.enableCaching && result) {
+                    const cacheKey = this.generateCacheKey(methodKey, params);
+                    this.setCache(cacheKey, result);
+                }
+                
+                done(null, result);
+                return;
+                
+            } catch (error) {
+                lastError = error as Error;
+                
+                // 更新熔断器状态
+                if (this.options.enableCircuitBreaker) {
+                    this.recordCircuitBreakerFailure(methodKey);
+                }
+                
+                // 如果不是最后一次尝试，等待后重试
+                if (attempt < maxRetries) {
+                    const delay = this.options.retryDelay! * Math.pow(2, attempt); // 指数退避
+                    logger.warn(`方法调用失败，${delay}ms后重试 (${attempt + 1}/${maxRetries}): ${methodKey}`, 
+                        `错误: ${lastError.message}, 尝试次数: ${attempt + 1}/${maxRetries}`);
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                }
+            }
+        }
+        
+        // 所有重试都失败了
+        logger.error(`方法调用最终失败: ${methodKey}`, 
+            lastError || new Error('未知错误'), `尝试次数: ${maxRetries + 1}`);
+        done(lastError, null);
+    }
+
+    /**
+     * 执行方法
+     */
+    private async executeMethod(
+        params: Array<any>, 
+        instance: any, 
+        fn: Function, 
+        methodKey: string,
+        attempt: number
+    ): Promise<any> {
+        const startTime = Date.now();
+        
+        logger.info(`执行方法: ${methodKey} (尝试 ${attempt + 1})`, {
+            method: methodKey,
+            attempt: attempt + 1,
+            parameters: this.sanitizeParameters(params)
+        });
+
+        const result = fn.apply(instance, params);
+        
+        // 处理异步方法
+        if (result && typeof result.then === 'function') {
+            const asyncResult = await result;
+            const duration = Date.now() - startTime;
+            
+            // 性能监控
+            if (this.options.enablePerformanceMonitoring) {
+                this.recordPerformanceMetrics(methodKey, duration);
+            }
+            
+            logger.info(`方法执行成功: ${methodKey}`, {
+                method: methodKey,
+                duration: `${duration}ms`,
+                attempt: attempt + 1
+            });
+            
+            return asyncResult;
+        } else {
+            // 同步方法
+            const duration = Date.now() - startTime;
+            
+            if (this.options.enablePerformanceMonitoring) {
+                this.recordPerformanceMetrics(methodKey, duration);
+            }
+            
+            logger.info(`方法执行成功: ${methodKey}`, {
+                method: methodKey,
+                duration: `${duration}ms`,
+                attempt: attempt + 1
+            });
+            
+            return result;
+        }
+    }
+
+    /**
+     * 生成缓存键
+     */
+    private generateCacheKey(methodKey: string, params: any[]): string {
+        const paramsHash = JSON.stringify(params);
+        return `${methodKey}:${Buffer.from(paramsHash).toString('base64')}`;
+    }
+
+    /**
+     * 从缓存获取
+     */
+    private getFromCache(key: string): any {
+        const item = this.cache.get(key);
+        if (item && Date.now() - item.timestamp < item.ttl) {
+            return item.value;
+        }
+        if (item) {
+            this.cache.delete(key);
+        }
+        return null;
+    }
+
+    /**
+     * 设置缓存
+     */
+    private setCache(key: string, value: any): void {
+        this.cache.set(key, {
+            key,
+            value,
+            timestamp: Date.now(),
+            ttl: this.options.cacheTTL!
+        });
+    }
+
+    /**
+     * 检查熔断器是否开启
+     */
+    private isCircuitBreakerOpen(methodKey: string): boolean {
+        const state = this.circuitBreakerState.get(methodKey) || CircuitBreakerState.CLOSED;
+        const failures = this.circuitBreakerFailures.get(methodKey) || 0;
+        const lastFailure = this.circuitBreakerLastFailure.get(methodKey) || 0;
+        
+        if (state === CircuitBreakerState.OPEN) {
+            // 检查是否可以尝试半开状态
+            if (Date.now() - lastFailure > 60000) { // 1分钟后尝试半开
+                this.circuitBreakerState.set(methodKey, CircuitBreakerState.HALF_OPEN);
+                return false;
+            }
+            return true;
+        }
+        
+        return false;
+    }
+
+    /**
+     * 记录熔断器失败
+     */
+    private recordCircuitBreakerFailure(methodKey: string): void {
+        const failures = (this.circuitBreakerFailures.get(methodKey) || 0) + 1;
+        this.circuitBreakerFailures.set(methodKey, failures);
+        this.circuitBreakerLastFailure.set(methodKey, Date.now());
+        
+        if (failures >= this.options.circuitBreakerThreshold!) {
+            this.circuitBreakerState.set(methodKey, CircuitBreakerState.OPEN);
+            logger.warn(`熔断器开启: ${methodKey}`, {
+                failures,
+                threshold: this.options.circuitBreakerThreshold
+            });
+        }
+    }
+
+    /**
+     * 重置熔断器
+     */
+    private resetCircuitBreaker(methodKey: string): void {
+        this.circuitBreakerState.set(methodKey, CircuitBreakerState.CLOSED);
+        this.circuitBreakerFailures.set(methodKey, 0);
+    }
+
+    /**
+     * 记录性能指标
+     */
+    private recordPerformanceMetrics(methodKey: string, duration: number): void {
+        const slowCalls = this.slowCalls.get(methodKey) || 0;
+        
+        if (duration > this.options.slowCallThreshold!) {
+            this.slowCalls.set(methodKey, slowCalls + 1);
+            logger.warn(`慢调用检测: ${methodKey}`, {
+                duration: `${duration}ms`,
+                threshold: `${this.options.slowCallThreshold}ms`,
+                slowCalls: slowCalls + 1
+            });
+        }
+    }
+
+    /**
+     * 清理敏感参数
+     */
+    private sanitizeParameters(params: any[]): any[] {
+        return params.map(param => {
+            if (typeof param === 'object' && param !== null) {
+                const sanitized = { ...param };
+                if ('password' in sanitized) sanitized.password = '***';
+                if ('token' in sanitized) sanitized.token = '***';
+                if ('secret' in sanitized) sanitized.secret = '***';
+                return sanitized;
+            }
+            return param;
+        });
+    }
+
+    /**
+     * 获取拦截器状态
+     */
+    public getStatus(): any {
+        return {
+            cacheSize: this.cache.size,
+            circuitBreakerStates: Object.fromEntries(this.circuitBreakerState),
+            circuitBreakerFailures: Object.fromEntries(this.circuitBreakerFailures),
+            slowCalls: Object.fromEntries(this.slowCalls),
+            options: this.options
+        };
+    }
+
+    /**
+     * 清理缓存
+     */
+    public clearCache(): void {
+        this.cache.clear();
+        logger.info('拦截器缓存已清理');
+    }
+
+    /**
+     * 重置熔断器
+     */
+    public resetCircuitBreakers(): void {
+        this.circuitBreakerState.clear();
+        this.circuitBreakerFailures.clear();
+        this.circuitBreakerLastFailure.clear();
+        logger.info('所有熔断器已重置');
+    }
+}
+
+/**
+ * 创建高级拦截器实例
+ */
+export const advancedServiceCallInterceptor = AdvancedServiceCallInterceptor.getInstance();
+
+/**
+ * 导出高级拦截器创建函数
+ */
+export const createAdvancedServiceCallInterceptor = (options?: InterceptorOptions) => 
+    AdvancedServiceCallInterceptor.getInstance(options).createAdvancedInterceptor();