codeplay/.monkeycode/docs/DEVELOPER_GUIDE.md

CodePlay 开发者指南

开发环境要求

必需工具

工具	版本	说明
.NET SDK	8.0+	开发和构建工具
IDE	推荐 Visual Studio 2022 / Rider	C# 开发环境
Git	任意版本	版本控制

可选工具

工具	说明
Swagger UI	访问 http://localhost:5000/swagger 查看 API 文档
Postman	API 测试工具

快速开始

1. 克隆仓库

cd /workspace

2. 还原依赖

dotnet restore CodePlay.sln

3. 构建项目

dotnet build CodePlay.sln

4. 运行测试

dotnet test CodePlay.Tests/CodePlay.Tests.csproj --logger "console;verbosity=normal"

5. 启动 Web API

dotnet run --project CodePlay.Web/CodePlay.Web.csproj

默认监听地址：

• HTTP: http://localhost:5000
• HTTPS: https://localhost:5001

6. 启动 CLI（开发中）

dotnet run --project CodePlay.CLI/CodePlay.CLI.csproj -- --help

项目结构

参见 ARCHITECTURE.md 了解详细架构。

代码规范

命名约定

C# 类和接口

• 类名: PascalCase
• 接口名: IPascalCase
• 方法名: PascalCase
• 属性名: PascalCase
• 私有字段: _camelCase
• 局部变量: camelCase
• 常量: PASCAL_CASE

文件和目录

• 文件名: PascalCase.cs
• 目录名: PascalCase

注释规范

文档注释

所有公共成员必须有 XML 文档注释：

/// <summary>
/// 方法的功能描述
/// </summary>
/// <param name="param">参数说明</param>
/// <returns>返回值说明</returns>
public string Method(string param)

行内注释

// 使用单行注释解释复杂的逻辑
var result = CalculateComplexLogic(); // 这里是为什么需要这样计算

/*
多行注释用于说明代码块的整体逻辑
*/

异常处理

抛出异常

if (string.IsNullOrWhiteSpace(sourceCode))
{
    throw new ArgumentException("Source code is required", nameof(sourceCode));
}

捕获异常

try
{
    // 可能抛出异常的代码
}
catch (Exception ex) when (!Debugger.IsAttached)
{
    // 记录日志
    _logger.LogError(ex, "操作失败");
    throw;
}

异步编程

异步方法命名

• 异步方法以 Async 结尾
• 返回 Task 或 Task<T>

public async Task<ConversionResult> ConvertAsync(
    ConversionRequest request, 
    CancellationToken cancellationToken)

取消令牌

所有异步操作都应该支持取消：

public async Task<Result> ExecuteAsync(CancellationToken cancellationToken = default)
{
    await DoWorkAsync(cancellationToken);
}

依赖注入

遵循 ASP.NET Core 的依赖注入模式：

// 注册服务
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 格式

测试方法命名

• {方法名}_{场景}_{期望结果} 格式

[Fact]
public void ParseAsync_SimpleClass_ShouldParseSuccessfully()

使用 Arrange-Act-Assert 模式

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

运行测试

运行所有测试

dotnet test

运行特定测试类

dotnet test --filter "FullyQualifiedName~CSharpParserTests"

查看详细信息

dotnet test --logger "console;verbosity=detailed"

调试技巧

日志调试

使用 ILogger 进行调试：

_logger.LogDebug("当前状态：{State}", state);
_logger.LogInformation("操作成功完成");
_logger.LogWarning("潜在问题：{Issue}", issue);
_logger.LogError(ex, "操作失败：{Error}", error);

断点调试

在 IDE 中设置断点：

1. 在代码行号左侧点击设置断点
2. 按 F5 启动调试
3. 使用 F10/F11 单步执行

调试输出

使用 Debug.WriteLine 输出调试信息：

Debug.WriteLine($"当前节点类型：{node.Type}");

添加新的转换支持

1. 添加语言枚举

在 Enums.cs 中添加：

public enum LanguageType
{
    // ...现有语言
    Python = 4  // 新语言
}

2. 实现解析器

创建 {Language}Parser.cs：

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：

public class CSharpToPythonConverter : IConverter
{
    public async Task<ConversionResult> ConvertAsync(
        SyntaxTree syntaxTree, 
        LanguageType targetLanguage, 
        ConversionOptions? options = null, 
        CancellationToken cancellationToken = default)
    {
        // 实现转换逻辑
    }
}

4. 实现生成器

创建 {Language}CodeGenerator.cs：

public class PythonCodeGenerator : ICodeGenerator
{
    public string Generate(SyntaxTree syntaxTree)
    {
        // 实现代码生成
    }
}

5. 注册服务

在 ConversionService 中注册：

public ConversionService()
{
    RegisterConverter(LanguageType.CSharp, LanguageType.Python, new CSharpToPythonConverter());
}

添加新的 API 端点

1. 创建控制器

[ApiController]
[Route("api/[controller]")]
public class ProjectController : ControllerBase
{
    [HttpGet("{id}")]
    public async Task<ActionResult<Project>> GetProject(string id)
    {
        // 实现逻辑
    }
}

2. 配置路由

在 Program.cs 中：

app.MapControllers();

3. 添加 Swagger 文档

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "CodePlay API",
        Version = "v1"
    });
});

常见问题

Q: 编译失败

A: 检查 .NET SDK 版本：

dotnet --version

应该是 8.0 或更高版本。

Q: 测试失败

A: 查看测试输出，确认是否是因为：

• 依赖未还原
• 代码变更导致测试用例失效
• 环境问题

Q: Web API 无法启动

A: 检查端口占用情况：

netstat -ano | findstr :5000

Q: 转换器不支持某语言对

A: 检查 ConversionService 中是否已注册该转换对：

var supported = service.GetSupportedConversions();

Git 工作流

分支命名

• 功能分支：{YYMMDD}-feat-{feature-name}
• 修复分支：{YYMMDD}-fix-{issue-id}

提交消息

使用以下格式：

feat: 添加新功能
fix: 修复问题
docs: 更新文档
test: 添加测试
refactor: 代码重构
chore: 日常维护

推送代码

git add .
git commit -m "feat: 描述你的更改"
git push origin {branch-name}

发布流程

1. 更新版本号

在所有 .csproj 文件中更新版本号。

2. 生成 NuGet 包

dotnet pack CodePlay.Core/CodePlay.Core.csproj -c Release

3. 创建 Docker 镜像（Web 服务）

docker build -t codeplay-web:latest -f CodePlay.Web/Dockerfile .

4. 生成发布说明

在 GitHub Releases 中创建新版本，包含：

• 版本号
• 更新内容
• 已知问题
• 升级指南

性能优化建议

1. 缓存：缓存已解析的语法树
2. 并行处理：对多个文件使用并行转换
3. 内存管理：及时释放大对象
4. 异步 I/O：使用异步文件读写

安全建议

1. 输入验证：检查所有输入参数
2. 资源限制：限制单次转换的代码量
3. 超时控制：设置操作超时时间
4. 错误处理：不暴露敏感信息

资源链接

• .NET 文档
• ASP.NET Core 文档
• xUnit 测试框架
• Swagger 文档

贡献指南

提交代码前检查清单

• 代码通过编译
• 所有测试通过
• 代码格式符合规范
• 添加了必要的注释
• 更新了相关文档
• 提交了任务列表（如适用）

代码审查要点

1. 功能是否正确实现
2. 代码是否可读
3. 是否有足够的测试覆盖
4. 是否遵循了架构设计
5. 是否有性能问题

联系方式

• 项目仓库：GitHub
• 问题反馈：Issues