create-dp-koa 1.0.0

package/template/src/annotations/processors/ConfigManagementProcessor.ts

@@ -0,0 +1,369 @@
+/**
+ * 企业级配置管理注解处理器
+ * 提供动态配置、环境变量管理和配置验证
+ */
+
+import { Context } from 'koa';
+import { AnnotationProcessor } from '@src/framework/decorator/processor/AnnotationProcessor';
+import { logger } from '@src/framework/utils/logger';
+import { getRuntimeEnvironmentLabel } from '@src/framework/utils/function';
+
+export interface ConfigManagementConfig {
+    configKey?: string;
+    defaultValue?: any;
+    required?: boolean;
+    validationRules?: ValidationRule[];
+    refreshInterval?: number;
+    environment?: 'development' | 'staging' | 'production';
+    fallbackConfig?: Record<string, any>;
+}
+
+export interface ValidationRule {
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'email' | 'url';
+    min?: number;
+    max?: number;
+    pattern?: RegExp;
+    custom?: (value: any) => boolean;
+    message?: string;
+}
+
+export interface ConfigValue {
+    key: string;
+    value: any;
+    source: 'environment' | 'database' | 'file' | 'default';
+    lastUpdated: Date;
+    environment: string;
+    validated: boolean;
+}
+
+export class ConfigManagementProcessor implements AnnotationProcessor {
+    readonly name = 'ConfigManagement';
+    readonly priority = 4;
+
+    private configCache: Map<string, ConfigValue> = new Map();
+    private validationRules: Map<string, ValidationRule[]> = new Map();
+    private refreshTimers: Map<string, NodeJS.Timeout> = new Map();
+    private configRefreshInterval: NodeJS.Timeout | null = null; // 存储定时器引用
+
+    constructor() {
+        this.loadEnvironmentConfigs();
+        this.startConfigRefresh();
+    }
+
+    async process(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        annotationData: ConfigManagementConfig,
+        callParams: any[]
+    ): Promise<boolean> {
+        const config = annotationData || {};
+        
+        if (!config.configKey) return true;
+
+        try {
+            // 获取配置值
+            const configValue = await this.getConfigValue(config.configKey, config);
+            
+            // 验证配置
+            if (config.validationRules) {
+                const isValid = this.validateConfig(config.configKey, configValue.value, config.validationRules);
+                if (!isValid) {
+                    logger.error(`[${this.name}] 配置验证失败: ${config.configKey}`);
+                    ctx.status = 500;
+                    ctx.body = { error: 'Configuration validation failed' };
+                    return false;
+                }
+            }
+
+            // 将配置注入到上下文
+            ctx.state.config = ctx.state.config || {};
+            ctx.state.config[config.configKey] = configValue.value;
+
+            logger.debug(`[${this.name}] 配置加载成功: ${config.configKey}`, {
+                value: this.sanitizeValue(configValue.value),
+                source: configValue.source
+            });
+
+        } catch (error) {
+            logger.error(`[${this.name}] 配置加载失败: ${config.configKey}`, error as Error);
+            
+            if (config.required) {
+                ctx.status = 500;
+                ctx.body = { error: 'Required configuration missing' };
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    private async getConfigValue(key: string, config: ConfigManagementConfig): Promise<ConfigValue> {
+        // 检查缓存
+        const cached = this.configCache.get(key);
+        if (cached && this.isCacheValid(cached)) {
+            return cached;
+        }
+
+        let value: any;
+        let source: ConfigValue['source'] = 'default';
+
+        // 1. 尝试从环境变量获取
+        const envValue = process.env[key.toUpperCase()];
+        if (envValue !== undefined) {
+            value = this.parseValue(envValue);
+            source = 'environment';
+        }
+        // 2. 尝试从数据库获取
+        else if (await this.hasDatabaseConfig(key)) {
+            value = await this.getDatabaseConfig(key);
+            source = 'database';
+        }
+        // 3. 尝试从配置文件获取
+        else if (await this.hasFileConfig(key)) {
+            value = await this.getFileConfig(key);
+            source = 'file';
+        }
+        // 4. 使用默认值
+        else {
+            value = config.defaultValue;
+            source = 'default';
+        }
+
+        const configValue: ConfigValue = {
+            key,
+            value,
+            source,
+            lastUpdated: new Date(),
+            environment: config.environment || getRuntimeEnvironmentLabel(),
+            validated: false
+        };
+
+        // 缓存配置
+        this.configCache.set(key, configValue);
+
+        return configValue;
+    }
+
+    private parseValue(value: string): any {
+        // 尝试解析 JSON
+        try {
+            return JSON.parse(value);
+        } catch {
+            // 尝试解析布尔值
+            if (value.toLowerCase() === 'true') return true;
+            if (value.toLowerCase() === 'false') return false;
+            
+            // 尝试解析数字
+            const num = Number(value);
+            if (!isNaN(num)) return num;
+            
+            // 返回字符串
+            return value;
+        }
+    }
+
+    private validateConfig(key: string, value: any, rules: ValidationRule[]): boolean {
+        for (const rule of rules) {
+            if (!this.validateRule(value, rule)) {
+                logger.warn(`[${this.name}] 配置验证失败: ${key}`, {
+                    value: this.sanitizeValue(value),
+                    rule: rule.type,
+                    message: rule.message
+                });
+                return false;
+            }
+        }
+        return true;
+    }
+
+    private validateRule(value: any, rule: ValidationRule): boolean {
+        switch (rule.type) {
+            case 'string':
+                if (typeof value !== 'string') return false;
+                if (rule.min && value.length < rule.min) return false;
+                if (rule.max && value.length > rule.max) return false;
+                if (rule.pattern && !rule.pattern.test(value)) return false;
+                break;
+
+            case 'number':
+                if (typeof value !== 'number') return false;
+                if (rule.min && value < rule.min) return false;
+                if (rule.max && value > rule.max) return false;
+                break;
+
+            case 'boolean':
+                if (typeof value !== 'boolean') return false;
+                break;
+
+            case 'array':
+                if (!Array.isArray(value)) return false;
+                if (rule.min && value.length < rule.min) return false;
+                if (rule.max && value.length > rule.max) return false;
+                break;
+
+            case 'object':
+                if (typeof value !== 'object' || value === null) return false;
+                break;
+
+            case 'email':
+                if (typeof value !== 'string' || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) return false;
+                break;
+
+            case 'url':
+                if (typeof value !== 'string' || !/^https?:\/\/.+/.test(value)) return false;
+                break;
+        }
+
+        // 自定义验证
+        if (rule.custom && !rule.custom(value)) return false;
+
+        return true;
+    }
+
+    private async hasDatabaseConfig(key: string): Promise<boolean> {
+        // 这里应该实现数据库配置检查
+        return false;
+    }
+
+    private async getDatabaseConfig(key: string): Promise<any> {
+        // 这里应该实现数据库配置获取
+        return null;
+    }
+
+    private async hasFileConfig(key: string): Promise<boolean> {
+        // 这里应该实现文件配置检查
+        return false;
+    }
+
+    private async getFileConfig(key: string): Promise<any> {
+        // 这里应该实现文件配置获取
+        return null;
+    }
+
+    private isCacheValid(configValue: ConfigValue): boolean {
+        const maxAge = 5 * 60 * 1000; // 5分钟
+        return Date.now() - configValue.lastUpdated.getTime() < maxAge;
+    }
+
+    private sanitizeValue(value: any): any {
+        if (typeof value === 'string' && value.length > 100) {
+            return value.substring(0, 100) + '...';
+        }
+        return value;
+    }
+
+    private loadEnvironmentConfigs(): void {
+        // 加载环境变量配置
+        Object.keys(process.env).forEach(key => {
+            if (key.startsWith('CONFIG_')) {
+                const configKey = key.substring(7).toLowerCase();
+                const value = this.parseValue(process.env[key]!);
+                
+                this.configCache.set(configKey, {
+                    key: configKey,
+                    value,
+                    source: 'environment',
+                    lastUpdated: new Date(),
+                    environment: getRuntimeEnvironmentLabel(),
+                    validated: false
+                });
+            }
+        });
+    }
+
+    private startConfigRefresh(): void {
+        // 如果已有定时器，先清除
+        if (this.configRefreshInterval) {
+            clearInterval(this.configRefreshInterval);
+        }
+        
+        // 定期刷新配置
+        this.configRefreshInterval = setInterval(() => {
+            this.refreshConfigs();
+        }, 60000); // 每分钟刷新一次
+    }
+
+    /**
+     * 停止配置刷新定时器
+     * 防止内存泄露
+     */
+    stopConfigRefresh(): void {
+        if (this.configRefreshInterval) {
+            clearInterval(this.configRefreshInterval);
+            this.configRefreshInterval = null;
+            logger.info(`[${this.name}] 配置刷新定时器已停止`);
+        }
+    }
+
+    /**
+     * 清理所有定时器
+     */
+    cleanup(): void {
+        // 清理主刷新定时器
+        this.stopConfigRefresh();
+        
+        // 清理所有独立的刷新定时器
+        this.refreshTimers.forEach((timer) => {
+            clearInterval(timer);
+        });
+        this.refreshTimers.clear();
+        
+        // 清理缓存
+        this.configCache.clear();
+        this.validationRules.clear();
+        
+        logger.info(`[${this.name}] 所有资源已清理`);
+    }
+
+    private async refreshConfigs(): Promise<void> {
+        const keys = Array.from(this.configCache.keys());
+        
+        for (const key of keys) {
+            try {
+                const cached = this.configCache.get(key)!;
+                if (cached.source === 'environment') {
+                    // 环境变量配置不需要刷新
+                    continue;
+                }
+
+                // 重新加载配置
+                const newValue = await this.getConfigValue(key, {});
+                if (JSON.stringify(newValue.value) !== JSON.stringify(cached.value)) {
+                    logger.info(`[${this.name}] 配置已更新: ${key}`);
+                }
+            } catch (error) {
+                logger.error(`[${this.name}] 配置刷新失败: ${key}`, error as Error);
+            }
+        }
+    }
+
+    /**
+     * 获取所有配置
+     */
+    getAllConfigs(): ConfigValue[] {
+        return Array.from(this.configCache.values());
+    }
+
+    /**
+     * 获取指定配置
+     */
+    getConfig(key: string): ConfigValue | undefined {
+        return this.configCache.get(key);
+    }
+
+    /**
+     * 设置配置验证规则
+     */
+    setValidationRules(key: string, rules: ValidationRule[]): void {
+        this.validationRules.set(key, rules);
+    }
+
+    /**
+     * 清理配置缓存
+     */
+    clearCache(): void {
+        this.configCache.clear();
+        logger.info(`[${this.name}] 配置缓存已清理`);
+    }
+}

package/template/src/annotations/processors/DistributedTracingProcessor.ts

@@ -0,0 +1,288 @@
+/**
+ * 企业级分布式追踪注解处理器
+ * 提供跨服务的请求追踪和性能分析
+ */
+
+import { Context } from 'koa';
+import { AnnotationProcessor } from '@src/framework/decorator/processor/AnnotationProcessor';
+import { logger } from '@src/framework/utils/logger';
+
+export interface TracingConfig {
+    enableTracing?: boolean;
+    traceIdHeader?: string;
+    spanIdHeader?: string;
+    parentSpanIdHeader?: string;
+    samplingRate?: number;
+    exportToJaeger?: boolean;
+    exportToZipkin?: boolean;
+    customTags?: Record<string, string>;
+}
+
+export interface TraceSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    operationName: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    tags: Record<string, any>;
+    logs: TraceLog[];
+    status: 'started' | 'completed' | 'error';
+    serviceName: string;
+    componentName: string;
+}
+
+export interface TraceLog {
+    timestamp: number;
+    level: 'info' | 'warn' | 'error';
+    message: string;
+    fields?: Record<string, any>;
+}
+
+export class DistributedTracingProcessor implements AnnotationProcessor {
+    readonly name = 'DistributedTracing';
+    readonly priority = 3;
+
+    private activeSpans: Map<string, TraceSpan> = new Map();
+    private completedSpans: TraceSpan[] = [];
+    private samplingRate: number = 1.0;
+
+    constructor() {
+        // 从环境变量读取采样率
+        this.samplingRate = parseFloat(process.env.TRACING_SAMPLING_RATE || '1.0');
+    }
+
+    async process(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        annotationData: TracingConfig,
+        callParams: any[]
+    ): Promise<boolean> {
+        const config = annotationData || {};
+        
+        if (!config.enableTracing) return true;
+
+        // 决定是否采样
+        if (!this.shouldSample()) {
+            return true;
+        }
+
+        // 获取或创建追踪上下文
+        const traceContext = this.getOrCreateTraceContext(ctx, config);
+        
+        // 创建新的 Span
+        const span = this.createSpan(traceContext, controller, methodName, config);
+        
+        // 存储到上下文
+        ctx.state.traceSpan = span;
+        ctx.state.traceContext = traceContext;
+
+        // 添加追踪头到响应
+        ctx.set('X-Trace-Id', span.traceId);
+        ctx.set('X-Span-Id', span.spanId);
+
+        // 记录开始日志
+        this.addSpanLog(span, 'info', 'Span started', {
+            controller: controller.constructor.name,
+            method: methodName,
+            traceId: span.traceId,
+            spanId: span.spanId
+        });
+
+        logger.info(`[${this.name}] 开始追踪: ${span.operationName}`, {
+            traceId: span.traceId,
+            spanId: span.spanId,
+            parentSpanId: span.parentSpanId
+        });
+
+        return true;
+    }
+
+    async postProcess(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        response: any
+    ): Promise<void> {
+        const span = ctx.state.traceSpan;
+        if (!span) return;
+
+        // 完成 Span
+        span.endTime = Date.now();
+        span.duration = span.endTime - span.startTime;
+        span.status = 'completed';
+
+        // 添加响应信息到标签
+        span.tags['http.status_code'] = ctx.status;
+        span.tags['response.size'] = JSON.stringify(response).length;
+        span.tags['response.type'] = typeof response;
+
+        // 记录完成日志
+        this.addSpanLog(span, 'info', 'Span completed', {
+            duration: span.duration,
+            statusCode: ctx.status,
+            responseSize: span.tags['response.size']
+        });
+
+        // 移动到已完成列表
+        this.activeSpans.delete(span.spanId);
+        this.completedSpans.push(span);
+
+        // 导出到外部系统
+        await this.exportSpan(span);
+
+        logger.info(`[${this.name}] 完成追踪: ${span.operationName}`, {
+            traceId: span.traceId,
+            spanId: span.spanId,
+            duration: `${span.duration}ms`
+        });
+    }
+
+    private shouldSample(): boolean {
+        return Math.random() < this.samplingRate;
+    }
+
+    private getOrCreateTraceContext(ctx: Context, config: TracingConfig): any {
+        const traceIdHeader = config.traceIdHeader || 'X-Trace-Id';
+        const spanIdHeader = config.spanIdHeader || 'X-Span-Id';
+        const parentSpanIdHeader = config.parentSpanIdHeader || 'X-Parent-Span-Id';
+
+        // 尝试从请求头获取现有的追踪上下文
+        const traceId = ctx.get(traceIdHeader) || this.generateTraceId();
+        const parentSpanId = ctx.get(parentSpanIdHeader);
+
+        return {
+            traceId,
+            parentSpanId,
+            headers: {
+                traceIdHeader,
+                spanIdHeader,
+                parentSpanIdHeader
+            }
+        };
+    }
+
+    private createSpan(traceContext: any, controller: any, methodName: string, config: TracingConfig): TraceSpan {
+        const spanId = this.generateSpanId();
+        const operationName = `${controller.constructor.name}.${methodName}`;
+
+        const span: TraceSpan = {
+            traceId: traceContext.traceId,
+            spanId,
+            parentSpanId: traceContext.parentSpanId,
+            operationName,
+            startTime: Date.now(),
+            tags: {
+                'component': 'controller',
+                'controller.name': controller.constructor.name,
+                'method.name': methodName,
+                'service.name': process.env.SERVICE_NAME || 'koa-framework',
+                'http.method': 'GET', // 这里应该从 ctx 获取
+                'http.url': '', // 这里应该从 ctx 获取
+                ...config.customTags
+            },
+            logs: [],
+            status: 'started',
+            serviceName: process.env.SERVICE_NAME || 'koa-framework',
+            componentName: 'controller'
+        };
+
+        this.activeSpans.set(spanId, span);
+        return span;
+    }
+
+    private addSpanLog(span: TraceSpan, level: TraceLog['level'], message: string, fields?: Record<string, any>): void {
+        span.logs.push({
+            timestamp: Date.now(),
+            level,
+            message,
+            fields
+        });
+    }
+
+    private async exportSpan(span: TraceSpan): Promise<void> {
+        try {
+            // 导出到 Jaeger
+            if (process.env.JAEGER_ENDPOINT) {
+                await this.exportToJaeger(span);
+            }
+
+            // 导出到 Zipkin
+            if (process.env.ZIPKIN_ENDPOINT) {
+                await this.exportToZipkin(span);
+            }
+
+            // 导出到自定义系统
+            if (process.env.CUSTOM_TRACING_ENDPOINT) {
+                await this.exportToCustom(span);
+            }
+        } catch (error) {
+            logger.error(`[${this.name}] 导出追踪数据失败:`, error as Error);
+        }
+    }
+
+    private async exportToJaeger(span: TraceSpan): Promise<void> {
+        // 这里应该实现 Jaeger 导出逻辑
+        logger.debug(`[${this.name}] 导出到 Jaeger: ${span.traceId}`);
+    }
+
+    private async exportToZipkin(span: TraceSpan): Promise<void> {
+        // 这里应该实现 Zipkin 导出逻辑
+        logger.debug(`[${this.name}] 导出到 Zipkin: ${span.traceId}`);
+    }
+
+    private async exportToCustom(span: TraceSpan): Promise<void> {
+        // 这里应该实现自定义系统导出逻辑
+        logger.debug(`[${this.name}] 导出到自定义系统: ${span.traceId}`);
+    }
+
+    private generateTraceId(): string {
+        return Math.random().toString(36).substring(2, 15) + 
+               Math.random().toString(36).substring(2, 15);
+    }
+
+    private generateSpanId(): string {
+        return Math.random().toString(36).substring(2, 15);
+    }
+
+    /**
+     * 获取追踪统计信息
+     */
+    getTracingStats(): any {
+        const activeCount = this.activeSpans.size;
+        const completedCount = this.completedSpans.length;
+        
+        const avgDuration = completedCount > 0 
+            ? this.completedSpans.reduce((sum, span) => sum + (span.duration || 0), 0) / completedCount
+            : 0;
+
+        return {
+            activeSpans: activeCount,
+            completedSpans: completedCount,
+            averageDuration: avgDuration,
+            samplingRate: this.samplingRate
+        };
+    }
+
+    /**
+     * 获取指定追踪的所有 Span
+     */
+    getTraceSpans(traceId: string): TraceSpan[] {
+        return this.completedSpans.filter(span => span.traceId === traceId);
+    }
+
+    /**
+     * 清理过期的 Span
+     */
+    cleanupExpiredSpans(maxAge: number = 3600000): void { // 1小时
+        const cutoffTime = Date.now() - maxAge;
+        
+        this.completedSpans = this.completedSpans.filter(span => 
+            span.startTime > cutoffTime
+        );
+
+        logger.info(`[${this.name}] 清理过期 Span 完成，保留 ${this.completedSpans.length} 个 Span`);
+    }
+}