docs: 生成完整项目文档
创建以下文档: - INDEX.md - 项目索引和概览 - ARCHITECTURE.md - 系统架构设计文档 - INTERFACES.md - 接口和类型定义文档 - DEVELOPER_GUIDE.md - 开发者指南 文档覆盖内容: - 项目结构和模块说明 - 技术栈和依赖 - 核心组件设计 - API 接口定义 - 数据模型 - 开发环境配置 - 代码规范 - 测试指南 - 调试技巧 - Git 工作流 Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com>
This commit is contained in:
monkeycode-ai
@@ -0,0 +1,373 @@
|
||||
# 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<SyntaxTree> ParseAsync(string sourceCode, CancellationToken cancellationToken = default);
|
||||
}
|
||||
```
|
||||
|
||||
**实现**：
|
||||
- `CSharpParser` - 基于 Roslyn 实现 C# 代码解析
|
||||
- 支持提取注释、文档字符串、类、方法、属性等
|
||||
|
||||
### 2. 转换器（Converters）
|
||||
|
||||
负责将源语言的 AST 转换为目标语言的 AST。
|
||||
|
||||
**接口**：`IConverter`
|
||||
|
||||
```csharp
|
||||
public interface IConverter
|
||||
{
|
||||
Task<ConversionResult> 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<ConversionResult> 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<ConversionWarning>
|
||||
- ValidationSummary: ValidationSummary
|
||||
```
|
||||
|
||||
**SyntaxTree** - 语法树
|
||||
```csharp
|
||||
- Language: LanguageType
|
||||
- Root: SyntaxNode
|
||||
- Comments: List<SyntaxComment>
|
||||
- Documentation: List<SyntaxDocumentation>
|
||||
```
|
||||
|
||||
## 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<ValidationResult> ValidateAsync(
|
||||
string code,
|
||||
LanguageType language,
|
||||
CancellationToken cancellationToken = default);
|
||||
}
|
||||
```
|
||||
|
||||
### 自动修复引擎（Auto Fix Engine）
|
||||
|
||||
**接口**：`IAutoFixEngine`
|
||||
|
||||
```csharp
|
||||
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）
|
||||
|
||||
```csharp
|
||||
- KeepComments: bool
|
||||
- KeepDocStrings: bool
|
||||
- KeepFormatting: bool
|
||||
- IndentSize: int
|
||||
- UseTabs: bool
|
||||
- EnableAutoFix: bool
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 错误分类
|
||||
|
||||
| 类型 | 错误码前缀 | 说明 |
|
||||
|------|----------|------|
|
||||
| 解析错误 | ERR_PARSE_* | 源代码语法错误 |
|
||||
| 转换错误 | ERR_CONVERT_* | 转换过程错误 |
|
||||
| 验证错误 | ERR_VALIDATE_* | 编译验证失败 |
|
||||
| 系统错误 | ERR_SYSTEM_* | 内部系统错误 |
|
||||
|
||||
## 日志系统
|
||||
|
||||
使用结构化日志记录关键操作：
|
||||
|
||||
- 转换开始/结束
|
||||
- 验证结果
|
||||
- 错误详情
|
||||
- 性能指标
|
||||
|
||||
## 安全考虑
|
||||
|
||||
- 输入验证：检查源代码长度、语言类型
|
||||
- 资源限制：限制单次转换的最大代码量
|
||||
- 超时控制：设置转换和验证的超时时间
|
||||
- 错误信息：不暴露内部实现细节
|
||||
Reference in New Issue
Block a user