monkeycode-ai
80b4718568
创建以下文档: - INDEX.md - 项目索引和概览 - ARCHITECTURE.md - 系统架构设计文档 - INTERFACES.md - 接口和类型定义文档 - DEVELOPER_GUIDE.md - 开发者指南 文档覆盖内容: - 项目结构和模块说明 - 技术栈和依赖 - 核心组件设计 - API 接口定义 - 数据模型 - 开发环境配置 - 代码规范 - 测试指南 - 调试技巧 - Git 工作流 Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com>
520 lines
9.1 KiB
Markdown
520 lines
9.1 KiB
Markdown
# 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)
|