# CodePlay 系统架构 ## 系统概览 CodePlay 采用分层架构设计，将解析、转换、生成和验证流程分离，确保系统的可扩展性和可维护性。 ## 架构图 ```mermaid graph TB subgraph "客户端层" Web[Web 界面] CLI[CLI 工具] API[API 客户端] end subgraph "API 层 - CodePlay.Web" Controllers[API 控制器] Middleware[中间件] end subgraph "核心层 - CodePlay.Core" ConversionService[转换服务] subgraph "解析器" CSharpParser[C# 解析器] JavaParser[Java 解析器] CppParser[C++ 解析器] end subgraph "转换器" CSharpJava[C#→Java] JavaCSharp[Java→C#] CSharpCpp[C#→C++] CppCSharp[C++→C#] JavaCpp[Java→C++] CppJava[C++→Java] end subgraph "生成器" JavaGen[Java 生成器] CSharpGen[C# 生成器] CppGen[C++ 生成器] end subgraph "验证器" CSharpValidator[C# 验证器] JavaValidator[Java 验证器] CppValidator[C++ 验证器] end end subgraph "数据层" Models[数据模型] Storage[存储服务] end Web --> Controllers CLI --> Controllers API --> Controllers Controllers --> ConversionService ConversionService --> CSharpParser ConversionService --> JavaParser ConversionService --> CppParser ConversionService --> CSharpJava ConversionService --> JavaCSharp ConversionService --> JavaGen ConversionService --> CSharpValidator ConversionService --> JavaValidator ``` ## 技术栈 ### 后端框架 | 组件 | 技术选型 | 说明 | |------|---------|------| | 主要语言 | C# | .NET 8.0 | | Web 框架 | ASP.NET Core | Web API + MVC | | 测试框架 | xUnit | 单元测试和集成测试 | ### 核心依赖 | 库 | 版本 | 用途 | |---|------|------| | Microsoft.CodeAnalysis.CSharp (Roslyn) | 4.8.0 | C# 代码解析 | | TreeSitter | 1.0.0 | 多语言解析支持 | ### 解析器技术 | 语言 | 解析器 | 状态 | |------|--------|------| | C# | Roslyn | ✅ 已实现 | | Java | TreeSitter/Text Processing | 🔄 计划中 | | C++ | TreeSitter/libclang | 🔄 计划中 | ## 目录结构 ``` /workspace/ ├── CodePlay.sln # 解决方案文件 ├── CodePlay.Core/ # 核心类库 │ ├── Common/ # 公共类型 │ │ └── Enums.cs # 枚举定义 │ ├── Models/ # 数据模型 │ │ ├── ConversionModels.cs # 转换相关模型 │ │ └── ProjectModels.cs # 项目相关模型 │ ├── Interfaces/ # 接口定义 │ │ └── IInterfaces.cs # 核心接口 │ ├── Parsers/ # 解析器 │ │ ├── BaseParser.cs # 解析器基类 │ │ └── CSharpParser.cs # C# 解析器 │ ├── Converters/ # 转换器 │ │ ├── CSharpToJavaConverter.cs │ │ ├── CSharpToJavaStrategy.cs │ │ └── JavaCodeGenerator.cs │ └── Services/ # 服务层 │ └── ConversionService.cs ├── CodePlay.Web/ # Web API 项目 │ ├── Controllers/ # API 控制器 │ │ ├── ConversionController.cs │ │ └── WeatherForecastController.cs │ └── Program.cs # 入口文件 ├── CodePlay.CLI/ # CLI 工具 │ ├── Commands/ # 命令定义 │ └── Program.cs # 入口文件 └── CodePlay.Tests/ # 测试项目 ├── Parsers/ # 解析器测试 │ └── CSharpParserTests.cs └── Converters/ # 转换器测试 └── CSharpToJavaConverterTests.cs ``` ## 核心组件说明 ### 1. 解析器（Parsers） 负责将源代码解析为抽象语法树（AST）。 **接口**：`IParser` ```csharp public interface IParser { Task ParseAsync(string sourceCode, CancellationToken cancellationToken = default); } ``` **实现**： - `CSharpParser` - 基于 Roslyn 实现 C# 代码解析 - 支持提取注释、文档字符串、类、方法、属性等 ### 2. 转换器（Converters） 负责将源语言的 AST 转换为目标语言的 AST。 **接口**：`IConverter` ```csharp public interface IConverter { Task ConvertAsync( SyntaxTree syntaxTree, LanguageType targetLanguage, ConversionOptions? options = null, CancellationToken cancellationToken = default); } ``` **实现**： - `CSharpToJavaConverter` - C# → Java 转换 - 使用策略模式：`CSharpToJavaStrategy` ### 3. 代码生成器（Generators） 负责从 AST 生成目标语言的源代码。 **接口**：`ICodeGenerator` ```csharp public interface ICodeGenerator { string Generate(SyntaxTree syntaxTree); } ``` **实现**： - `JavaCodeGenerator` - Java 代码生成 - 支持格式化、缩进处理、文档生成 ### 4. 转换服务（ConversionService） 提供统一的转换入口，协调解析、转换、生成和验证流程。 ```csharp public class ConversionService { public async Task ConvertAsync( ConversionRequest request, CancellationToken cancellationToken = default); } ``` ## 数据流 ### 转换流程 ``` 1. 接收请求 (ConversionRequest) ↓ 2. 解析源代码 → SyntaxTree ↓ 3. 转换 AST → Converted SyntaxTree ↓ 4. 生成代码 → Target Code ↓ 5. 编译验证 → ValidationResult ↓ 6. 返回结果 (ConversionResult) ``` ### 核心数据模型 **ConversionRequest** - 转换请求 ```csharp - SourceCode: string - SourceLanguage: LanguageType - TargetLanguage: LanguageType - ValidationRounds: int (1-3) - Options: ConversionOptions ``` **ConversionResult** - 转换结果 ```csharp - Success: bool - TransformedCode: string - Report: ConversionReport - Warnings: List - ValidationSummary: ValidationSummary ``` **SyntaxTree** - 语法树 ```csharp - Language: LanguageType - Root: SyntaxNode - Comments: List - Documentation: List ``` ## API 设计 ### REST API 端点 **POST /api/conversion** - 执行代码转换 请求示例： ```json { "sourceCode": "public class Test { }", "sourceLanguage": 1, "targetLanguage": 2, "validationRounds": 2 } ``` 响应示例： ```json { "success": true, "transformedCode": "public class Test { }", "report": { "linesConverted": 1, "classesConverted": 1, "methodsConverted": 0 } } ``` **GET /api/conversion/supported** - 获取支持的转换列表 **GET /api/conversion/supported/{source}/{target}** - 检查是否支持指定转换 ## 扩展性设计 ### 添加新的语言支持 1. 在 `LanguageType` 枚举中添加新语言 2. 实现 `IParser` 接口创建新解析器 3. 实现 `ICodeGenerator` 接口创建新生成器 4. 实现 `IConversionStrategy` 接口创建转换策略 5. 在 `ConversionService` 中注册 ### 添加新的转换对 1. 创建新的 `IConverter` 实现 2. 创建对应的 `IConversionStrategy` 实现 3. 在 `ConversionService` 构造函数中注册 ## 验证流程 ### 编译验证器（Compiler Validator） **接口**：`ICompilerValidator` ```csharp public interface ICompilerValidator { Task ValidateAsync( string code, LanguageType language, CancellationToken cancellationToken = default); } ``` ### 自动修复引擎（Auto Fix Engine） **接口**：`IAutoFixEngine` ```csharp public interface IAutoFixEngine { Task FixAsync( string code, List errors, int round, CancellationToken cancellationToken = default); } ``` **修复轮次策略**： 1. 第 1 轮：修复导入/using 语句 2. 第 2 轮：修复类型映射 3. 第 3 轮：修复 API 调用 ## 配置管理 ### 转换选项（ConversionOptions） ```csharp - KeepComments: bool - KeepDocStrings: bool - KeepFormatting: bool - IndentSize: int - UseTabs: bool - EnableAutoFix: bool ``` ## 错误处理 ### 错误分类 | 类型 | 错误码前缀 | 说明 | |------|----------|------| | 解析错误 | ERR_PARSE_* | 源代码语法错误 | | 转换错误 | ERR_CONVERT_* | 转换过程错误 | | 验证错误 | ERR_VALIDATE_* | 编译验证失败 | | 系统错误 | ERR_SYSTEM_* | 内部系统错误 | ## 日志系统 使用结构化日志记录关键操作： - 转换开始/结束 - 验证结果 - 错误详情 - 性能指标 ## 安全考虑 - 输入验证：检查源代码长度、语言类型 - 资源限制：限制单次转换的最大代码量 - 超时控制：设置转换和验证的超时时间 - 错误信息：不暴露内部实现细节