create-dp-koa 1.0.0

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

@@ -0,0 +1,612 @@
+/**
+ * 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

@@ -0,0 +1,10 @@
+/**
+ * 注解处理器导出文件
+ */
+
+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';