feat: 创建 CodePlay 代码转换平台需求和技术设计文档
Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com>
This commit is contained in:
monkeycode-ai
@@ -0,0 +1,262 @@
|
||||
# CodePlay 代码转换平台
|
||||
|
||||
Feature Name: codeplay-conversion-platform
|
||||
Updated: 2026-06-03
|
||||
|
||||
## Description
|
||||
|
||||
CodePlay 是一个基于 .NET 开发的多语言代码转换平台，支持 C#、Java、C++ 三种编程语言之间的双向转换。平台采用 AST（抽象语法树）解析和转换引擎，提供 Web 界面、CLI 工具和 REST API 三种访问方式。对于无法直接转换的语法，采用注释保留 + TODO 说明的策略，并通过 1-3 轮自动编译验证确保转换质量。
|
||||
|
||||
## Architecture
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph Client Layer
|
||||
Web[Web 界面]
|
||||
CLI[CLI 工具]
|
||||
API[API 客户端]
|
||||
end
|
||||
|
||||
subgraph API Gateway
|
||||
Gateway[API 网关]
|
||||
Auth[认证中间件]
|
||||
RateLimit[限流中间件]
|
||||
end
|
||||
|
||||
subgraph Core Services
|
||||
ProjectService[项目管理服务]
|
||||
ConversionService[转换服务]
|
||||
ValidationService[验证服务]
|
||||
ReportService[报告服务]
|
||||
end
|
||||
|
||||
subgraph Conversion Engine
|
||||
Parser[语言解析器]
|
||||
Transformer[代码转换器]
|
||||
Generator[代码生成器]
|
||||
end
|
||||
|
||||
subgraph Validation Engine
|
||||
Compiler[编译器接口]
|
||||
TestRunner[测试运行器]
|
||||
FixEngine[自动修复引擎]
|
||||
end
|
||||
|
||||
subgraph Storage
|
||||
ProjectDB[(项目数据库)]
|
||||
CodeStorage[代码存储]
|
||||
ConfigStorage[配置存储]
|
||||
end
|
||||
|
||||
Web --> Gateway
|
||||
CLI --> Gateway
|
||||
API --> Gateway
|
||||
Gateway --> Auth
|
||||
Gateway --> RateLimit
|
||||
Gateway --> ProjectService
|
||||
Gateway --> ConversionService
|
||||
Gateway --> ReportService
|
||||
ConversionService --> Parser
|
||||
ConversionService --> Transformer
|
||||
ConversionService --> Generator
|
||||
ConversionService --> ValidationService
|
||||
ValidationService --> Compiler
|
||||
ValidationService --> TestRunner
|
||||
ValidationService --> FixEngine
|
||||
ProjectService --> ProjectDB
|
||||
ProjectService --> CodeStorage
|
||||
ProjectService --> ConfigStorage
|
||||
```
|
||||
|
||||
## Components and Interfaces
|
||||
|
||||
### 语言解析器模块
|
||||
|
||||
| 解析器类 | 说明 | 依赖 |
|
||||
|---------|------|------|
|
||||
| CSharpParser | 解析 C# 代码并生成 AST | Microsoft.CodeAnalysis (Roslyn) |
|
||||
| JavaParser | 解析 Java 代码并生成 AST | JavaParser (第三方库) |
|
||||
| CPlusPlusParser | 解析 C++ 代码并生成 AST | clang-sharp / libclang |
|
||||
|
||||
### 代码转换器模块
|
||||
|
||||
| 转换器 | 说明 | 策略类 |
|
||||
|-------|------|-------|
|
||||
| CSharpToJavaConverter | C# → Java 转换 | CSharpJavaConversionStrategy |
|
||||
| JavaToCSharpConverter | Java → C# 转换 | JavaCSharpConversionStrategy |
|
||||
| CSharpToCPlusPlusConverter | C# → C++ 转换 | CSharpCppConversionStrategy |
|
||||
| CPlusPlusToCSharpConverter | C++ → C# 转换 | CppCSharpConversionStrategy |
|
||||
| JavaToCPlusPlusConverter | Java → C++ 转换 | JavaCppConversionStrategy |
|
||||
| CPlusPlusToJavaConverter | C++ → Java 转换 | CppJavaConversionStrategy |
|
||||
|
||||
### 不可转换语法处理
|
||||
|
||||
| 语法特性 | 源语言 | 目标语言 | 处理策略 |
|
||||
|---------|--------|---------|---------|
|
||||
| LINQ | C# | Java | 保留原代码 + TODO + Stream API 建议 |
|
||||
| async/await | C# | Java | 转换为 CompletableFuture + TODO 说明 |
|
||||
| Lambda | C# | C++ | 转换为 std::function + TODO说明 |
|
||||
| Stream API | Java | C# | 保留原代码 + TODO + LINQ 建议 |
|
||||
| 模板 | C++ | C#/Java | 转换为泛型 + TODO 说明限制 |
|
||||
| 多继承 | C++ | C#/Java | 转换为接口 + TODO 说明 |
|
||||
| 指针操作 | C++ | C#/Java | 转换为引用/unsafe + TODO 警告 |
|
||||
|
||||
### 数据模型
|
||||
|
||||
```csharp
|
||||
// 转换请求模型
|
||||
public class ConversionRequest
|
||||
{
|
||||
public string SourceCode { get; set; }
|
||||
public string SourceLanguage { get; set; } // CSharp, Java, CPlusPlus
|
||||
public string TargetLanguage { get; set; } // CSharp, Java, CPlusPlus
|
||||
public string ProjectId { get; set; }
|
||||
public int ValidationRounds { get; set; } // 1-3
|
||||
public ConversionOptions Options { get; set; }
|
||||
}
|
||||
|
||||
// 转换结果模型
|
||||
public class ConversionResult
|
||||
{
|
||||
public bool Success { get; set; }
|
||||
public string TransformedCode { get; set; }
|
||||
public ConversionReport Report { get; set; }
|
||||
public List<ConversionWarning> Warnings { get; set; }
|
||||
public ValidationSummary ValidationSummary { get; set; }
|
||||
}
|
||||
|
||||
// 转换报告
|
||||
public class ConversionReport
|
||||
{
|
||||
public int LinesConverted { get; set; }
|
||||
public int ClassesConverted { get; set; }
|
||||
public int MethodsConverted { get; set; }
|
||||
public TimeSpan Duration { get; set; }
|
||||
public List<ConversionIssue> Issues { get; set; }
|
||||
public List<TransformationLog> TransformationLog { get; set; }
|
||||
}
|
||||
|
||||
// 项目模型
|
||||
public class Project
|
||||
{
|
||||
public string Id { get; set; }
|
||||
public string Name { get; set; }
|
||||
public string SourceLanguage { get; set; }
|
||||
public string TargetLanguage { get; set; }
|
||||
public ProjectStatus Status { get; set; }
|
||||
public DateTime CreatedAt { get; set; }
|
||||
public DateTime UpdatedAt { get; set; }
|
||||
public List<ConversionTask> Tasks { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
## Correctness Properties
|
||||
|
||||
### 1. 语法一致性
|
||||
- 转换后的代码必须是目标语言的有效语法
|
||||
- 转换后的代码必须能够通过目标语言编译器编译（无语法错误）
|
||||
|
||||
### 2. 语义等价性
|
||||
- 转换前后的代码逻辑行为应保持一致
|
||||
- 变量名、类名、方法名应保持语义一致性
|
||||
- 访问修饰符应转换为目标语言的等价修饰符
|
||||
|
||||
### 3. 注释保留
|
||||
- 所有源代码注释必须保留在转换后的代码中
|
||||
- 文档注释应转换为目标语言的文档格式
|
||||
- C# XML Doc → Java JavaDoc
|
||||
- Java JavaDoc → C# XML Doc
|
||||
- C++ Doxygen → 目标语言文档格式
|
||||
|
||||
### 4. TODO 完整性
|
||||
- 任何不可直接转换的语法必须添加 TODO 注释
|
||||
- TODO 必须包含：
|
||||
- 原语法说明
|
||||
- 为什么无法直接转换
|
||||
- 推荐的替代方案
|
||||
- 参考代码位置
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 错误分类
|
||||
|
||||
| 错误类型 | 错误码 | 处理策略 |
|
||||
|---------|-------|---------|
|
||||
| 语法错误 | ERR_PARSE_001 | 返回解析错误位置和详情 |
|
||||
| 不支持的语言对 | ERR_LANG_001 | 返回支持的语言列表 |
|
||||
| 转换超时 | ERR_TIMEOUT_001 | 返回已转换部分并建议分批处理 |
|
||||
| 编译验证失败 | ERR_VALIDATE_001 | 执行自动修复，3 轮失败后标记人工检查 |
|
||||
| 资源不足 | ERR_RESOURCE_001 | 加入队列并通知预计等待时间 |
|
||||
| API 认证失败 | ERR_AUTH_001 | 返回 401 和认证指南 |
|
||||
|
||||
### 自动修复策略
|
||||
|
||||
```csharp
|
||||
public class AutoFixStrategy
|
||||
{
|
||||
// 第 1 轮：常见导入/using 语句修复
|
||||
public Task<FixResult> FixRound1(CompilationError error);
|
||||
|
||||
// 第 2 轮：类型映射修复
|
||||
public Task<FixResult> FixRound2(CompilationError error);
|
||||
|
||||
// 第 3 轮：API 调用替换
|
||||
public Task<FixResult> FixRound3(CompilationError error);
|
||||
}
|
||||
```
|
||||
|
||||
## Test Strategy
|
||||
|
||||
### 单元测试
|
||||
|
||||
- 每个转换器的独立单元测试
|
||||
- 语法解析器的单元测试
|
||||
- 不可转换语法处理的单元测试
|
||||
|
||||
### 集成测试
|
||||
|
||||
- 端到端转换流程测试
|
||||
- 多轮验证流程测试
|
||||
- API 接口集成测试
|
||||
|
||||
### 测试用例库
|
||||
|
||||
建立测试用例库，包含：
|
||||
- C#、Java、C++ 各种语法特性的示例代码
|
||||
- 边界情况和复杂场景的测试代码
|
||||
- 已知问题的回归测试代码
|
||||
|
||||
### 验证策略
|
||||
|
||||
```csharp
|
||||
public class ValidationPipeline
|
||||
{
|
||||
public async Task<ValidationResult> Validate(
|
||||
string code,
|
||||
string language,
|
||||
int maxRounds = 3)
|
||||
{
|
||||
for (int round = 1; round <= maxRounds; round++)
|
||||
{
|
||||
var result = await CompileAndTest(code, language);
|
||||
if (result.Success)
|
||||
return result;
|
||||
|
||||
var fix = await AutoFix(result.Errors, round);
|
||||
if (!fix.CanFix)
|
||||
break;
|
||||
|
||||
code = fix.FixedCode;
|
||||
}
|
||||
return new ValidationResult { NeedsManualReview = true };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
[^1]: (Microsoft Roslyn) - C# 编译器平台 [.NET Documentation](https://docs.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/)
|
||||
[^2]: (JavaParser) - Java 代码解析库 [https://javaparser.org/](https://javaparser.org/)
|
||||
[^3]: (clang-sharp) - C++ Clang 绑定 [https://github.com/SimonFussel/clang-sharp](https://github.com/SimonFussel/clang-sharp)
|
||||
[^4]: (com.aspose.ms.jdk.NetFramework) - Java 版 .NET Framework 兼容库 [Aspose 文档](https://docs.aspose.com/)
|
||||
[^5]: (ANTLR) - 语言解析器生成工具 [https://www.antlr.org/](https://www.antlr.org/)
|
||||
Reference in New Issue
Block a user