# 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)