docs: 生成完整项目文档

创建以下文档: - INDEX.md - 项目索引和概览 - ARCHITECTURE.md - 系统架构设计文档 - INTERFACES.md - 接口和类型定义文档 - DEVELOPER_GUIDE.md - 开发者指南文档覆盖内容: - 项目结构和模块说明 - 技术栈和依赖 - 核心组件设计 - API 接口定义 - 数据模型 - 开发环境配置 - 代码规范 - 测试指南 - 调试技巧 - Git 工作流 Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com>
2026-06-03 04:17:14 +00:00
parent ae4de8a116
commit 80b4718568
4 changed files with 1639 additions and 0 deletions
@@ -0,0 +1,519 @@
+# CodePlay 开发者指南
+
+## 开发环境要求
+
+### 必需工具
+
+| 工具 | 版本 | 说明 |
+|------|------|------|
+| .NET SDK | 8.0+ | 开发和构建工具 |
+| IDE | 推荐 Visual Studio 2022 / Rider | C# 开发环境 |
+| Git | 任意版本 | 版本控制 |
+
+### 可选工具
+
+| 工具 | 说明 |
+|------|------|
+| Swagger UI | 访问 `http://localhost:5000/swagger` 查看 API 文档 |
+| Postman | API 测试工具 |
+
+## 快速开始
+
+### 1. 克隆仓库
+
+```bash
+cd /workspace
+```
+
+### 2. 还原依赖
+
+```bash
+dotnet restore CodePlay.sln
+```
+
+### 3. 构建项目
+
+```bash
+dotnet build CodePlay.sln
+```
+
+### 4. 运行测试
+
+```bash
+dotnet test CodePlay.Tests/CodePlay.Tests.csproj --logger "console;verbosity=normal"
+```
+
+### 5. 启动 Web API
+
+```bash
+dotnet run --project CodePlay.Web/CodePlay.Web.csproj
+```
+
+默认监听地址：
+- HTTP: `http://localhost:5000`
+- HTTPS: `https://localhost:5001`
+
+### 6. 启动 CLI（开发中）
+
+```bash
+dotnet run --project CodePlay.CLI/CodePlay.CLI.csproj -- --help
+```
+
+## 项目结构
+
+参见 [ARCHITECTURE.md](./ARCHITECTURE.md) 了解详细架构。
+
+## 代码规范
+
+### 命名约定
+
+#### C# 类和接口
+
+- **类名**: PascalCase
+- **接口名**: IPascalCase
+- **方法名**: PascalCase
+- **属性名**: PascalCase
+- **私有字段**: _camelCase
+- **局部变量**: camelCase
+- **常量**: PASCAL_CASE
+
+#### 文件和目录
+
+- **文件名**: PascalCase.cs
+- **目录名**: PascalCase
+
+### 注释规范
+
+#### 文档注释
+
+所有公共成员必须有 XML 文档注释：
+
+```csharp
+/// <summary>
+/// 方法的功能描述
+/// </summary>
+/// <param name="param">参数说明</param>
+/// <returns>返回值说明</returns>
+public string Method(string param)
+```
+
+#### 行内注释
+
+```csharp
+// 使用单行注释解释复杂的逻辑
+var result = CalculateComplexLogic(); // 这里是为什么需要这样计算
+
+/*
+多行注释用于说明代码块的整体逻辑
+*/
+```
+
+### 异常处理
+
+#### 抛出异常
+
+```csharp
+if (string.IsNullOrWhiteSpace(sourceCode))
+{
+    throw new ArgumentException("Source code is required", nameof(sourceCode));
+}
+```
+
+#### 捕获异常
+
+```csharp
+try
+{
+    // 可能抛出异常的代码
+}
+catch (Exception ex) when (!Debugger.IsAttached)
+{
+    // 记录日志
+    _logger.LogError(ex, "操作失败");
+    throw;
+}
+```
+
+### 异步编程
+
+#### 异步方法命名
+
+- 异步方法以 `Async` 结尾
+- 返回 `Task` 或 `Task<T>`
+
+```csharp
+public async Task<ConversionResult> ConvertAsync(
+    ConversionRequest request, 
+    CancellationToken cancellationToken)
+```
+
+#### 取消令牌
+
+所有异步操作都应该支持取消：
+
+```csharp
+public async Task<Result> ExecuteAsync(CancellationToken cancellationToken = default)
+{
+    await DoWorkAsync(cancellationToken);
+}
+```
+
+### 依赖注入
+
+遵循 ASP.NET Core 的依赖注入模式：
+
+```csharp
+// 注册服务
+builder.Services.AddSingleton<ConversionService>();
+builder.Services.AddScoped<IConverter, CSharpToJavaConverter>();
+
+// 注入到类
+public class MyService
+{
+    private readonly ConversionService _service;
+    
+    public MyService(ConversionService service)
+    {
+        _service = service;
+    }
+}
+```
+
+## 测试指南
+
+### 测试项目结构
+
+```
+CodePlay.Tests/
+├── Parsers/
+│   └── CSharpParserTests.cs
+└── Converters/
+    └── CSharpToJavaConverterTests.cs
+```
+
+### 单元测试最佳实践
+
+#### 测试类命名
+
+- `{被测试类}Tests` 格式
+
+#### 测试方法命名
+
+- `{方法名}_{场景}_{期望结果}` 格式
+
+```csharp
+[Fact]
+public void ParseAsync_SimpleClass_ShouldParseSuccessfully()
+```
+
+#### 使用 Arrange-Act-Assert 模式
+
+```csharp
+[Fact]
+public void Test_Method()
+{
+    // Arrange（准备）
+    var parser = new CSharpParser();
+    var code = "public class Test { }";
+    
+    // Act（执行）
+    var result = await parser.ParseAsync(code);
+    
+    // Assert（断言）
+    Assert.NotNull(result);
+    Assert.Equal(LanguageType.CSharp, result.Language);
+}
+```
+
+### 运行测试
+
+#### 运行所有测试
+
+```bash
+dotnet test
+```
+
+#### 运行特定测试类
+
+```bash
+dotnet test --filter "FullyQualifiedName~CSharpParserTests"
+```
+
+#### 查看详细信息
+
+```bash
+dotnet test --logger "console;verbosity=detailed"
+```
+
+## 调试技巧
+
+### 日志调试
+
+使用 `ILogger` 进行调试：
+
+```csharp
+_logger.LogDebug("当前状态：{State}", state);
+_logger.LogInformation("操作成功完成");
+_logger.LogWarning("潜在问题：{Issue}", issue);
+_logger.LogError(ex, "操作失败：{Error}", error);
+```
+
+### 断点调试
+
+在 IDE 中设置断点：
+1. 在代码行号左侧点击设置断点
+2. 按 F5 启动调试
+3. 使用 F10/F11 单步执行
+
+### 调试输出
+
+使用 `Debug.WriteLine` 输出调试信息：
+
+```csharp
+Debug.WriteLine($"当前节点类型：{node.Type}");
+```
+
+## 添加新的转换支持
+
+### 1. 添加语言枚举
+
+在 `Enums.cs` 中添加：
+
+```csharp
+public enum LanguageType
+{
+    // ...现有语言
+    Python = 4  // 新语言
+}
+```
+
+### 2. 实现解析器
+
+创建 `{Language}Parser.cs`：
+
+```csharp
+public class PythonParser : BaseParser
+{
+    public override LanguageType SupportedLanguage => LanguageType.Python;
+    
+    public override Task<SyntaxTree> ParseAsync(string sourceCode, CancellationToken cancellationToken)
+    {
+        // 实现解析逻辑
+    }
+}
+```
+
+### 3. 实现转换器
+
+创建 `{Source}To{Target}Converter.cs`：
+
+```csharp
+public class CSharpToPythonConverter : IConverter
+{
+    public async Task<ConversionResult> ConvertAsync(
+        SyntaxTree syntaxTree, 
+        LanguageType targetLanguage, 
+        ConversionOptions? options = null, 
+        CancellationToken cancellationToken = default)
+    {
+        // 实现转换逻辑
+    }
+}
+```
+
+### 4. 实现生成器
+
+创建 `{Language}CodeGenerator.cs`：
+
+```csharp
+public class PythonCodeGenerator : ICodeGenerator
+{
+    public string Generate(SyntaxTree syntaxTree)
+    {
+        // 实现代码生成
+    }
+}
+```
+
+### 5. 注册服务
+
+在 `ConversionService` 中注册：
+
+```csharp
+public ConversionService()
+{
+    RegisterConverter(LanguageType.CSharp, LanguageType.Python, new CSharpToPythonConverter());
+}
+```
+
+## 添加新的 API 端点
+
+### 1. 创建控制器
+
+```csharp
+[ApiController]
+[Route("api/[controller]")]
+public class ProjectController : ControllerBase
+{
+    [HttpGet("{id}")]
+    public async Task<ActionResult<Project>> GetProject(string id)
+    {
+        // 实现逻辑
+    }
+}
+```
+
+### 2. 配置路由
+
+在 `Program.cs` 中：
+
+```csharp
+app.MapControllers();
+```
+
+### 3. 添加 Swagger 文档
+
+```csharp
+builder.Services.AddSwaggerGen(c =>
+{
+    c.SwaggerDoc("v1", new OpenApiInfo
+    {
+        Title = "CodePlay API",
+        Version = "v1"
+    });
+});
+```
+
+## 常见问题
+
+### Q: 编译失败
+
+**A**: 检查 .NET SDK 版本：
+
+```bash
+dotnet --version
+```
+
+应该是 8.0 或更高版本。
+
+### Q: 测试失败
+
+**A**: 查看测试输出，确认是否是因为：
+- 依赖未还原
+- 代码变更导致测试用例失效
+- 环境问题
+
+### Q: Web API 无法启动
+
+**A**: 检查端口占用情况：
+
+```bash
+netstat -ano | findstr :5000
+```
+
+### Q: 转换器不支持某语言对
+
+**A**: 检查 `ConversionService` 中是否已注册该转换对：
+
+```csharp
+var supported = service.GetSupportedConversions();
+```
+
+## Git 工作流
+
+### 分支命名
+
+- 功能分支：`{YYMMDD}-feat-{feature-name}`
+- 修复分支：`{YYMMDD}-fix-{issue-id}`
+
+### 提交消息
+
+使用以下格式：
+
+```
+feat: 添加新功能
+fix: 修复问题
+docs: 更新文档
+test: 添加测试
+refactor: 代码重构
+chore: 日常维护
+```
+
+### 推送代码
+
+```bash
+git add .
+git commit -m "feat: 描述你的更改"
+git push origin {branch-name}
+```
+
+## 发布流程
+
+### 1. 更新版本号
+
+在所有 `.csproj` 文件中更新版本号。
+
+### 2. 生成 NuGet 包
+
+```bash
+dotnet pack CodePlay.Core/CodePlay.Core.csproj -c Release
+```
+
+### 3. 创建 Docker 镜像（Web 服务）
+
+```bash
+docker build -t codeplay-web:latest -f CodePlay.Web/Dockerfile .
+```
+
+### 4. 生成发布说明
+
+在 GitHub Releases 中创建新版本，包含：
+- 版本号
+- 更新内容
+- 已知问题
+- 升级指南
+
+## 性能优化建议
+
+1. **缓存**：缓存已解析的语法树
+2. **并行处理**：对多个文件使用并行转换
+3. **内存管理**：及时释放大对象
+4. **异步 I/O**：使用异步文件读写
+
+## 安全建议
+
+1. **输入验证**：检查所有输入参数
+2. **资源限制**：限制单次转换的代码量
+3. **超时控制**：设置操作超时时间
+4. **错误处理**：不暴露敏感信息
+
+## 资源链接
+
+- [.NET 文档](https://docs.microsoft.com/en-us/dotnet/)
+- [ASP.NET Core 文档](https://docs.microsoft.com/en-us/aspnet/core/)
+- [xUnit 测试框架](https://xunit.net/)
+- [Swagger 文档](https://swagger.io/docs/)
+
+## 贡献指南
+
+### 提交代码前检查清单
+
+- [ ] 代码通过编译
+- [ ] 所有测试通过
+- [ ] 代码格式符合规范
+- [ ] 添加了必要的注释
+- [ ] 更新了相关文档
+- [ ] 提交了任务列表（如适用）
+
+### 代码审查要点
+
+1. 功能是否正确实现
+2. 代码是否可读
+3. 是否有足够的测试覆盖
+4. 是否遵循了架构设计
+5. 是否有性能问题
+
+## 联系方式
+
+- 项目仓库：[GitHub](https://github.com/your-org/codeplay)
+- 问题反馈：[Issues](https://github.com/your-org/codeplay/issues)