create-dp-koa 1.1.1 → 1.1.3

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

@@ -1,612 +0,0 @@
-/**
- * Swagger注解处理器
- * 负责处理Swagger相关的注解，包括元数据收集、验证和规范生成
- */
-
-import { logger } from '@src/framework/utils/logger';
-import { getSwaggerMetadata } from '@src/framework/decorator/swagger';
-
-/**
- * Swagger注解处理器接口
- */
-export interface SwaggerProcessor {
-    /**
-     * 处理控制器的Swagger注解
-     */
-    processController(target: any): SwaggerControllerMetadata;
-    
-    /**
-     * 处理方法级别的Swagger注解
-     */
-    processMethod(target: any, methodName: string): SwaggerMethodMetadata;
-    
-    /**
-     * 验证Swagger注解的完整性
-     */
-    validateSwaggerAnnotations(target: any): ValidationResult;
-    
-    /**
-     * 生成OpenAPI规范
-     */
-    generateOpenAPISpec(controllers: any[]): OpenAPISpec;
-}
-
-/**
- * Swagger控制器元数据
- */
-export interface SwaggerControllerMetadata {
-    tags: string[];
-    description?: string;
-    basePath?: string;
-    methods: Map<string, SwaggerMethodMetadata>;
-}
-
-/**
- * Swagger方法元数据
- */
-export interface SwaggerMethodMetadata {
-    operationId: string;
-    summary: string;
-    description: string;
-    tags: string[];
-    parameters: SwaggerParameter[];
-    requestBody?: SwaggerRequestBody;
-    responses: SwaggerResponse[];
-    deprecated?: boolean;
-    security?: SwaggerSecurity[];
-}
-
-/**
- * Swagger参数定义
- */
-export interface SwaggerParameter {
-    name: string;
-    in: 'path' | 'query' | 'header' | 'cookie';
-    description?: string;
-    required: boolean;
-    schema: any;
-    example?: any;
-}
-
-/**
- * Swagger请求体定义
- */
-export interface SwaggerRequestBody {
-    description?: string;
-    required: boolean;
-    content: {
-        [mediaType: string]: {
-            schema: any;
-            examples?: Record<string, any>;
-        };
-    };
-}
-
-/**
- * Swagger响应定义
- */
-export interface SwaggerResponse {
-    status: number;
-    description: string;
-    content?: {
-        [mediaType: string]: {
-            schema: any;
-            examples?: Record<string, any>;
-        };
-    };
-}
-
-/**
- * Swagger安全定义
- */
-export interface SwaggerSecurity {
-    name: string;
-    scopes?: string[];
-}
-
-/**
- * 验证结果
- */
-export interface ValidationResult {
-    isValid: boolean;
-    errors: string[];
-    warnings: string[];
-}
-
-/**
- * OpenAPI规范
- */
-export interface OpenAPISpec {
-    openapi: string;
-    info: {
-        title: string;
-        version: string;
-        description?: string;
-    };
-    servers: Array<{
-        url: string;
-        description?: string;
-    }>;
-    paths: Record<string, any>;
-    components?: {
-        schemas?: Record<string, any>;
-        securitySchemes?: Record<string, any>;
-    };
-}
-
-/**
- * Swagger注解处理器实现
- */
-class SwaggerProcessorImpl implements SwaggerProcessor {
-    
-    /**
-     * 处理控制器的Swagger注解
-     */
-    processController(target: any): SwaggerControllerMetadata {
-        try {
-            const swaggerMetadata = getSwaggerMetadata(target);
-            
-            const controllerMetadata: SwaggerControllerMetadata = {
-                tags: swaggerMetadata.tags || [],
-                methods: new Map()
-            };
-            
-            // 处理所有方法的Swagger注解
-            const httpMethods = this.getHttpMethods(target);
-            httpMethods.forEach(methodName => {
-                const methodMetadata = this.processMethod(target, methodName);
-                controllerMetadata.methods.set(methodName, methodMetadata);
-            });
-            
-            logger.debug(`处理控制器 ${target.name} 的Swagger注解完成`);
-            return controllerMetadata;
-            
-        } catch (error) {
-            logger.error(`处理控制器 ${target.name} 的Swagger注解失败:`, error as Error);
-            throw error;
-        }
-    }
-    
-    /**
-     * 处理方法级别的Swagger注解
-     */
-    processMethod(target: any, methodName: string): SwaggerMethodMetadata {
-        try {
-            const swaggerMetadata = getSwaggerMetadata(target);
-            
-            // 获取方法的基本信息
-            const methodInfo = swaggerMetadata.methods.get(methodName) || {};
-            const params = swaggerMetadata.params.get(methodName) || [];
-            const body = swaggerMetadata.bodies.get(methodName);
-            const responses = swaggerMetadata.responses.get(methodName) || [];
-            
-            // 自动推断路径参数
-            const autoInferredParams = this.autoInferParameters(target, methodName);
-            const allParams = [...this.processParameters(params), ...autoInferredParams];
-            
-            const methodMetadata: SwaggerMethodMetadata = {
-                operationId: methodInfo.operationId || methodName,
-                summary: methodInfo.summary || this.generateDefaultSummary(methodName),
-                description: methodInfo.description || this.generateDefaultDescription(methodName),
-                tags: methodInfo.tags || [],
-                parameters: allParams,
-                responses: this.processResponses(responses)
-            };
-            
-            // 处理请求体
-            if (body) {
-                methodMetadata.requestBody = this.processRequestBody(body);
-            }
-            
-            logger.debug(`处理方法 ${methodName} 的Swagger注解完成`);
-            return methodMetadata;
-            
-        } catch (error) {
-            logger.error(`处理方法 ${methodName} 的Swagger注解失败:`, error as Error);
-            throw error;
-        }
-    }
-    
-    /**
-     * 验证Swagger注解的完整性
-     */
-    validateSwaggerAnnotations(target: any): ValidationResult {
-        const errors: string[] = [];
-        const warnings: string[] = [];
-        
-        try {
-            const swaggerMetadata = getSwaggerMetadata(target);
-            const httpMethods = this.getHttpMethods(target);
-            
-            // 验证每个方法的注解
-            httpMethods.forEach(methodName => {
-                const methodInfo = swaggerMetadata.methods.get(methodName);
-                const responses = swaggerMetadata.responses.get(methodName) || [];
-                
-                // 检查是否有基本的方法信息
-                if (!methodInfo) {
-                    warnings.push(`方法 ${methodName} 缺少 @Api 注解`);
-                } else {
-                    // 检查summary
-                    if (!methodInfo.summary) {
-                        warnings.push(`方法 ${methodName} 缺少 summary 描述`);
-                    }
-                    
-                    // 检查description
-                    if (!methodInfo.description) {
-                        warnings.push(`方法 ${methodName} 缺少 description 描述`);
-                    }
-                }
-                
-                // 检查响应定义
-                if (responses.length === 0) {
-                    warnings.push(`方法 ${methodName} 缺少 @ApiResponse 注解`);
-                } else {
-                    // 检查是否有200响应
-                    const has200Response = responses.some((r: any) => r.status === 200);
-                    if (!has200Response) {
-                        warnings.push(`方法 ${methodName} 缺少200状态码的响应定义`);
-                    }
-                }
-            });
-            
-            // 检查控制器标签
-            if (!swaggerMetadata.tags || swaggerMetadata.tags.length === 0) {
-                warnings.push(`控制器 ${target.name} 缺少 @ApiTags 注解`);
-            }
-            
-            logger.debug(`验证控制器 ${target.name} 的Swagger注解完成`);
-            
-            return {
-                isValid: errors.length === 0,
-                errors,
-                warnings
-            };
-            
-        } catch (error) {
-            logger.error(`验证控制器 ${target.name} 的Swagger注解失败:`, error as Error);
-            return {
-                isValid: false,
-                errors: [`验证失败: ${(error as Error).message}`],
-                warnings: []
-            };
-        }
-    }
-    
-    /**
-     * 生成OpenAPI规范
-     */
-    generateOpenAPISpec(controllers: any[]): OpenAPISpec {
-        try {
-            const spec: OpenAPISpec = {
-                openapi: '3.0.0',
-                info: {
-                    title: 'DP Koa Framework API',
-                    version: '1.0.0',
-                    description: '基于Koa的企业级框架API文档'
-                },
-                servers: [
-                    {
-                        url: 'http://localhost:3000',
-                        description: '开发环境'
-                    }
-                ],
-                paths: {},
-                components: {
-                    schemas: {},
-                    securitySchemes: {}
-                }
-            };
-            
-            // 处理每个控制器
-            controllers.forEach(controller => {
-                const controllerMetadata = this.processController(controller);
-                
-                // 获取控制器的路由信息
-                const httpMethods = this.getHttpMethods(controller);
-                
-                httpMethods.forEach(methodName => {
-                    const methodMetadata = controllerMetadata.methods.get(methodName);
-                    if (methodMetadata) {
-                        // 获取路由路径
-                        const routePath = this.getRoutePath(controller, methodName);
-                        if (routePath) {
-                            const swaggerPath = routePath.replace(/:(\w+)/g, '{$1}');
-                            const httpMethod = this.getHttpMethod(controller, methodName);
-                            
-                            if (!spec.paths[swaggerPath]) {
-                                spec.paths[swaggerPath] = {};
-                            }
-                            
-                            spec.paths[swaggerPath][httpMethod] = {
-                                operationId: methodMetadata.operationId,
-                                summary: methodMetadata.summary,
-                                description: methodMetadata.description,
-                                tags: methodMetadata.tags,
-                                parameters: methodMetadata.parameters,
-                                responses: this.convertResponsesToOpenAPI(methodMetadata.responses)
-                            };
-                            
-                            if (methodMetadata.requestBody) {
-                                spec.paths[swaggerPath][httpMethod].requestBody = methodMetadata.requestBody;
-                            }
-                        }
-                    }
-                });
-            });
-            
-            logger.info(`生成OpenAPI规范完成，包含 ${Object.keys(spec.paths).length} 个路径`);
-            return spec;
-            
-        } catch (error) {
-            logger.error('生成OpenAPI规范失败:', error as Error);
-            throw error;
-        }
-    }
-    
-    /**
-     * 处理参数
-     */
-    private processParameters(params: any[]): SwaggerParameter[] {
-        return params.map(param => ({
-            name: param.name,
-            in: param.in,
-            description: param.description,
-            required: param.required || false,
-            schema: param.schema || { type: 'string' },
-            example: param.example
-        }));
-    }
-    
-    /**
-     * 自动推断路径参数
-     */
-    private autoInferParameters(controller: any, methodName: string): SwaggerParameter[] {
-        const parameters: SwaggerParameter[] = [];
-        
-        try {
-            // 获取方法的URL路径
-            const urlPath = this.getMethodUrlPath(controller, methodName);
-            if (urlPath) {
-                // 提取路径参数 (:paramName)
-                const pathParamMatches = urlPath.match(/:(\w+)/g);
-                if (pathParamMatches) {
-                    pathParamMatches.forEach(paramMatch => {
-                        const paramName = paramMatch.substring(1); // 移除冒号
-                        
-                        // 检查是否已经通过@ApiParam定义了
-                        const swaggerMetadata = getSwaggerMetadata(controller);
-                        const existingParams = swaggerMetadata.params.get(methodName) || [];
-                        const alreadyDefined = existingParams.some((p: any) => p.name === paramName && p.in === 'path');
-                        
-                        if (!alreadyDefined) {
-                            parameters.push({
-                                name: paramName,
-                                in: 'path',
-                                description: this.generateParameterDescription(paramName),
-                                required: true,
-                                schema: { type: 'string' }
-                            });
-                        }
-                    });
-                }
-            }
-            
-            logger.debug(`为方法 ${methodName} 自动推断出 ${parameters.length} 个路径参数`);
-            return parameters;
-            
-        } catch (error) {
-            logger.warn(`自动推断方法 ${methodName} 的参数失败:`, error as Error);
-            return [];
-        }
-    }
-    
-    /**
-     * 获取方法的URL路径
-     */
-    private getMethodUrlPath(controller: any, methodName: string): string | null {
-        // 检查GET方法
-        if (controller.$_GetMethods) {
-            const getMethods = Array.from(controller.$_GetMethods) as Array<{methodName: string, url: string}>;
-            const method = getMethods.find(m => m.methodName === methodName);
-            if (method) return method.url;
-        }
-        
-        // 检查POST方法
-        if (controller.$_PostMethods) {
-            const postMethods = Array.from(controller.$_PostMethods) as Array<{methodName: string, url: string}>;
-            const method = postMethods.find(m => m.methodName === methodName);
-            if (method) return method.url;
-        }
-        
-        // 检查PUT方法
-        if (controller.$_PutMethods) {
-            const putMethods = Array.from(controller.$_PutMethods) as Array<{methodName: string, url: string}>;
-            const method = putMethods.find(m => m.methodName === methodName);
-            if (method) return method.url;
-        }
-        
-        // 检查DELETE方法
-        if (controller.$_DelMethods) {
-            const delMethods = Array.from(controller.$_DelMethods) as Array<{methodName: string, url: string}>;
-            const method = delMethods.find(m => m.methodName === methodName);
-            if (method) return method.url;
-        }
-        
-        return null;
-    }
-    
-    /**
-     * 生成参数描述
-     */
-    private generateParameterDescription(paramName: string): string {
-        const descriptions: Record<string, string> = {
-            'id': 'ID',
-            'userId': '用户ID',
-            'productId': '产品ID',
-            'orderId': '订单ID',
-            'categoryId': '分类ID',
-            'page': '页码',
-            'size': '每页数量',
-            'limit': '限制数量',
-            'offset': '偏移量'
-        };
-        
-        return descriptions[paramName] || `${paramName}参数`;
-    }
-    
-    /**
-     * 处理请求体
-     */
-    private processRequestBody(body: any): SwaggerRequestBody {
-        return {
-            description: body.description,
-            required: body.required || false,
-            content: {
-                'application/json': {
-                    schema: body.schema,
-                    examples: body.examples
-                }
-            }
-        };
-    }
-    
-    /**
-     * 处理响应
-     */
-    private processResponses(responses: any[]): SwaggerResponse[] {
-        return responses.map(response => ({
-            status: response.status,
-            description: response.description,
-            content: response.schema ? {
-                'application/json': {
-                    schema: response.schema,
-                    examples: response.examples
-                }
-            } : undefined
-        }));
-    }
-    
-    /**
-     * 转换响应为OpenAPI格式
-     */
-    private convertResponsesToOpenAPI(responses: SwaggerResponse[]): Record<string, any> {
-        const openAPIResponses: Record<string, any> = {};
-        
-        responses.forEach(response => {
-            openAPIResponses[response.status.toString()] = {
-                description: response.description,
-                content: response.content
-            };
-        });
-        
-        return openAPIResponses;
-    }
-    
-    /**
-     * 获取HTTP方法
-     */
-    private getHttpMethods(target: any): string[] {
-        const methods: string[] = [];
-        
-        if (target.$_GetMethods) {
-            const getMethods = Array.from(target.$_GetMethods) as Array<{methodName: string}>;
-            methods.push(...getMethods.map(m => m.methodName));
-        }
-        
-        if (target.$_PostMethods) {
-            const postMethods = Array.from(target.$_PostMethods) as Array<{methodName: string}>;
-            methods.push(...postMethods.map(m => m.methodName));
-        }
-        
-        if (target.$_PutMethods) {
-            const putMethods = Array.from(target.$_PutMethods) as Array<{methodName: string}>;
-            methods.push(...putMethods.map(m => m.methodName));
-        }
-        
-        if (target.$_DelMethods) {
-            const delMethods = Array.from(target.$_DelMethods) as Array<{methodName: string}>;
-            methods.push(...delMethods.map(m => m.methodName));
-        }
-        
-        return methods;
-    }
-    
-    /**
-     * 获取路由路径
-     */
-    private getRoutePath(target: any, methodName: string): string | null {
-        // 这里需要根据实际的路由注册逻辑来获取路径
-        // 暂时返回null，需要与路由系统集成
-        return null;
-    }
-    
-    /**
-     * 获取HTTP方法
-     */
-    private getHttpMethod(target: any, methodName: string): string {
-        if (target.$_GetMethods) {
-            const getMethods = Array.from(target.$_GetMethods) as Array<{methodName: string}>;
-            if (getMethods.some(m => m.methodName === methodName)) return 'get';
-        }
-        
-        if (target.$_PostMethods) {
-            const postMethods = Array.from(target.$_PostMethods) as Array<{methodName: string}>;
-            if (postMethods.some(m => m.methodName === methodName)) return 'post';
-        }
-        
-        if (target.$_PutMethods) {
-            const putMethods = Array.from(target.$_PutMethods) as Array<{methodName: string}>;
-            if (putMethods.some(m => m.methodName === methodName)) return 'put';
-        }
-        
-        if (target.$_DelMethods) {
-            const delMethods = Array.from(target.$_DelMethods) as Array<{methodName: string}>;
-            if (delMethods.some(m => m.methodName === methodName)) return 'delete';
-        }
-        
-        return 'get'; // 默认
-    }
-    
-    /**
-     * 生成默认摘要
-     */
-    private generateDefaultSummary(methodName: string): string {
-        const methodMap: Record<string, string> = {
-            'get': '获取',
-            'post': '创建',
-            'put': '更新',
-            'delete': '删除'
-        };
-        
-        const httpMethod = this.getHttpMethod({}, methodName);
-        const action = methodMap[httpMethod] || '操作';
-        
-        return `${action}${methodName}`;
-    }
-    
-    /**
-     * 生成默认描述
-     */
-    private generateDefaultDescription(methodName: string): string {
-        const httpMethod = this.getHttpMethod({}, methodName);
-        const descriptions: Record<string, string> = {
-            'get': '获取数据',
-            'post': '创建数据',
-            'put': '更新数据',
-            'delete': '删除数据'
-        };
-        
-        return descriptions[httpMethod] || 'API操作';
-    }
-}
-
-/**
- * 创建Swagger处理器实例
- */
-export const swaggerProcessor = new SwaggerProcessorImpl();
-
-/**
- * 导出Swagger处理器
- */
-export { SwaggerProcessorImpl };

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

@@ -1,10 +0,0 @@
-/**
- * 注解处理器导出文件
- */
-
-export { PerformanceMonitorProcessor } from './PerformanceMonitorProcessor';
-export { EnterprisePerformanceProcessor } from './EnterprisePerformanceProcessor';
-export { SecurityAuditProcessor } from './SecurityAuditProcessor';
-export { DistributedTracingProcessor } from './DistributedTracingProcessor';
-export { ConfigManagementProcessor } from './ConfigManagementProcessor';
-export { SwaggerProcessor, swaggerProcessor } from './SwaggerProcessor';