codeplay/.monkeycode/docs/ARCHITECTURE.md

CodePlay 系统架构

系统概览

CodePlay 采用分层架构设计，将解析、转换、生成和验证流程分离，确保系统的可扩展性和可维护性。

架构图

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

public interface IParser
{
    Task<SyntaxTree> ParseAsync(string sourceCode, CancellationToken cancellationToken = default);
}

实现：

• CSharpParser - 基于 Roslyn 实现 C# 代码解析
• 支持提取注释、文档字符串、类、方法、属性等

2. 转换器（Converters）

负责将源语言的 AST 转换为目标语言的 AST。

接口：IConverter

public interface IConverter
{
    Task<ConversionResult> ConvertAsync(
        SyntaxTree syntaxTree, 
        LanguageType targetLanguage, 
        ConversionOptions? options = null, 
        CancellationToken cancellationToken = default);
}

实现：

• CSharpToJavaConverter - C# → Java 转换
• 使用策略模式：CSharpToJavaStrategy

3. 代码生成器（Generators）

负责从 AST 生成目标语言的源代码。

接口：ICodeGenerator

public interface ICodeGenerator
{
    string Generate(SyntaxTree syntaxTree);
}

实现：

• JavaCodeGenerator - Java 代码生成
• 支持格式化、缩进处理、文档生成

4. 转换服务（ConversionService）

提供统一的转换入口，协调解析、转换、生成和验证流程。

public class ConversionService
{
    public async Task<ConversionResult> ConvertAsync(
        ConversionRequest request, 
        CancellationToken cancellationToken = default);
}

数据流

转换流程

1. 接收请求 (ConversionRequest)
   ↓
2. 解析源代码 → SyntaxTree
   ↓
3. 转换 AST → Converted SyntaxTree
   ↓
4. 生成代码 → Target Code
   ↓
5. 编译验证 → ValidationResult
   ↓
6. 返回结果 (ConversionResult)

核心数据模型

ConversionRequest - 转换请求

- SourceCode: string
- SourceLanguage: LanguageType
- TargetLanguage: LanguageType
- ValidationRounds: int (1-3)
- Options: ConversionOptions

ConversionResult - 转换结果

- Success: bool
- TransformedCode: string
- Report: ConversionReport
- Warnings: List<ConversionWarning>
- ValidationSummary: ValidationSummary

SyntaxTree - 语法树

- Language: LanguageType
- Root: SyntaxNode
- Comments: List<SyntaxComment>
- Documentation: List<SyntaxDocumentation>

API 设计

REST API 端点

POST /api/conversion - 执行代码转换

请求示例：

{
  "sourceCode": "public class Test { }",
  "sourceLanguage": 1,
  "targetLanguage": 2,
  "validationRounds": 2
}

响应示例：

{
  "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

public interface ICompilerValidator
{
    Task<ValidationResult> ValidateAsync(
        string code, 
        LanguageType language, 
        CancellationToken cancellationToken = default);
}

自动修复引擎（Auto Fix Engine）

接口：IAutoFixEngine

public interface IAutoFixEngine
{
    Task<FixResult> FixAsync(
        string code, 
        List<CompilationError> errors, 
        int round, 
        CancellationToken cancellationToken = default);
}

修复轮次策略：

1. 第 1 轮：修复导入/using 语句
2. 第 2 轮：修复类型映射
3. 第 3 轮：修复 API 调用

配置管理

转换选项（ConversionOptions）

- KeepComments: bool
- KeepDocStrings: bool
- KeepFormatting: bool
- IndentSize: int
- UseTabs: bool
- EnableAutoFix: bool

错误处理

错误分类

类型	错误码前缀	说明
解析错误	ERR_PARSE_*	源代码语法错误
转换错误	ERR_CONVERT_*	转换过程错误
验证错误	ERR_VALIDATE_*	编译验证失败
系统错误	ERR_SYSTEM_*	内部系统错误

日志系统

使用结构化日志记录关键操作：

• 转换开始/结束
• 验证结果
• 错误详情
• 性能指标

安全考虑

• 输入验证：检查源代码长度、语言类型
• 资源限制：限制单次转换的最大代码量
• 超时控制：设置转换和验证的超时时间
• 错误信息：不暴露内部实现细节