Files

T

monkeycode-ai 9c7ba42e52 feat: 创建 CodePlay 代码转换平台需求和技术设计文档

Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com>

2026-06-03 02:18:26 +00:00

8.3 KiB

Raw Permalink Blame History

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

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 警告

数据模型

// 转换请求模型
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 和认证指南

自动修复策略

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++ 各种语法特性的示例代码
边界情况和复杂场景的测试代码
已知问题的回归测试代码

验证策略

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 };
    }
}

8.3 KiB Raw Permalink Blame History