mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-03-25 21:34:28 +08:00
a79f02c987
- 新增 Core API 参考文档，涵盖架构与模块、数据模型与系统、命令与查询等核心组件 - 添加事件系统接口详细文档，包括 IEvent、IEventBus、IUnRegister 等接口说明 - 提供完整的 API 使用示例路径、最佳实践与性能建议 - 包含架构图、依赖关系图与故障排查指南 - 添加测试用例参考与扩展方法说明 - [skip ci]
433 lines
15 KiB
Markdown
433 lines
15 KiB
Markdown
# Godot源代码生成器
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [GodotModuleMarker.cs](file://GFramework.Godot.SourceGenerators.Abstractions/GodotModuleMarker.cs)
|
||
- [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj)
|
||
- [GeWuYou.GFramework.Godot.SourceGenerators.targets](file://GFramework.Godot.SourceGenerators/GeWuYou.GFramework.Godot.SourceGenerators.targets)
|
||
- [GFramework.Godot.SourceGenerators.Abstractions.csproj](file://GFramework.Godot.SourceGenerators.Abstractions/GFramework.Godot.SourceGenerators.Abstractions.csproj)
|
||
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs)
|
||
- [AttributeEnumGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeEnumGeneratorBase.cs)
|
||
- [CommonDiagnostics.cs](file://GFramework.SourceGenerators.Common/diagnostics/CommonDiagnostics.cs)
|
||
- [IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs)
|
||
- [AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs)
|
||
- [AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs)
|
||
- [README.md](file://GFramework.SourceGenerators/README.md)
|
||
- [GeneratorTest.cs](file://GFramework.SourceGenerators.Tests/core/GeneratorTest.cs)
|
||
- [GeneratorSnapshotTest.cs](file://GFramework.SourceGenerators.Tests/core/GeneratorSnapshotTest.cs)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构概览](#架构概览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
|
||
Godot源代码生成器是GFramework框架中用于自动化生成Godot模块相关代码的工具集。该生成器基于Roslyn源代码生成技术，在编译时自动识别和处理带有特定特性的类，生成相应的Godot模块配置代码。
|
||
|
||
该生成器的主要目标是：
|
||
- **自动化模块标记**：通过特性标记自动识别Godot模块
|
||
- **编译时代码生成**：在编译阶段生成所需的模块配置代码
|
||
- **反射优化**：减少运行时反射调用，提升性能
|
||
- **类型安全**：确保生成代码的类型安全性
|
||
- **开发效率**：简化Godot模块的开发和配置过程
|
||
|
||
## 项目结构
|
||
|
||
GFramework源代码生成器采用分层架构设计，主要包含以下核心模块：
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "生成器核心层"
|
||
SG[GFramework.Godot.SourceGenerators]
|
||
SGA[GFramework.Godot.SourceGenerators.Abstractions]
|
||
end
|
||
subgraph "通用生成器基础"
|
||
SGC[GFramework.SourceGenerators.Common]
|
||
SGCA[GFramework.SourceGenerators.Abstractions]
|
||
end
|
||
subgraph "Godot集成层"
|
||
GG[GFramework.Godot]
|
||
GGA[GFramework.Godot.Abstractions]
|
||
end
|
||
subgraph "测试层"
|
||
GST[GFramework.SourceGenerators.Tests]
|
||
end
|
||
SG --> SGC
|
||
SG --> SGA
|
||
SGA --> SGCA
|
||
SGC --> SGCA
|
||
GG --> SG
|
||
GST --> SG
|
||
```
|
||
|
||
**图表来源**
|
||
- [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L1-L71)
|
||
- [GFramework.Godot.SourceGenerators.Abstractions.csproj](file://GFramework.Godot.SourceGenerators.Abstractions/GFramework.Godot.SourceGenerators.Abstractions.csproj#L1-L32)
|
||
|
||
**章节来源**
|
||
- [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L1-L71)
|
||
- [GFramework.Godot.SourceGenerators.Abstractions.csproj](file://GFramework.Godot.SourceGenerators.Abstractions/GFramework.Godot.SourceGenerators.Abstractions.csproj#L1-L32)
|
||
|
||
## 核心组件
|
||
|
||
### GodotModuleMarker标记器
|
||
|
||
GodotModuleMarker是Godot模块命名空间的占位类型，用于标识和标记Godot模块相关的代码区域。
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class GodotModuleMarker {
|
||
<<sealed>>
|
||
+internal GodotModuleMarker()
|
||
}
|
||
note for GodotModuleMarker "用于标记Godot模块命名空间的占位类型"
|
||
```
|
||
|
||
**图表来源**
|
||
- [GodotModuleMarker.cs](file://GFramework.Godot.SourceGenerators.Abstractions/GodotModuleMarker.cs#L1-L6)
|
||
|
||
### 基础生成器架构
|
||
|
||
所有生成器都基于AttributeClassGeneratorBase抽象基类构建，该基类提供了统一的生成器模式：
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class AttributeClassGeneratorBase {
|
||
<<abstract>>
|
||
#string AttributeShortNameWithoutSuffix
|
||
+Initialize(context) void
|
||
#ResolveAttribute(compilation, symbol) AttributeData
|
||
#Execute(context, compilation, classDecl, symbol) void
|
||
#ValidateSymbol(context, compilation, syntax, symbol, attr) bool
|
||
#Generate(context, compilation, symbol, attr) string
|
||
#GetHintName(symbol) string
|
||
#ReportClassMustBePartial(context, syntax, symbol) void
|
||
}
|
||
class AttributeEnumGeneratorBase {
|
||
<<abstract>>
|
||
#string AttributeShortNameWithoutSuffix
|
||
+Initialize(context) void
|
||
#ResolveAttribute(compilation, symbol) AttributeData
|
||
#ValidateSymbol(context, compilation, syntax, symbol, attr) bool
|
||
#Generate(symbol, attr) string
|
||
#GetHintName(symbol) string
|
||
}
|
||
AttributeClassGeneratorBase <|-- AttributeEnumGeneratorBase
|
||
```
|
||
|
||
**图表来源**
|
||
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L1-L175)
|
||
- [AttributeEnumGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeEnumGeneratorBase.cs#L1-L104)
|
||
|
||
**章节来源**
|
||
- [GodotModuleMarker.cs](file://GFramework.Godot.SourceGenerators.Abstractions/GodotModuleMarker.cs#L1-L6)
|
||
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L1-L175)
|
||
- [AttributeEnumGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeEnumGeneratorBase.cs#L1-L104)
|
||
|
||
## 架构概览
|
||
|
||
### 编译时代码生成流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Dev as 开发者代码
|
||
participant Analyzer as Roslyn分析器
|
||
participant Generator as 源代码生成器
|
||
participant Compiler as C#编译器
|
||
participant Output as 生成的代码
|
||
Dev->>Analyzer : 编译项目
|
||
Analyzer->>Generator : 发现特性标记
|
||
Generator->>Generator : 解析语义模型
|
||
Generator->>Output : 生成源代码文件
|
||
Output->>Compiler : 参与编译过程
|
||
Compiler->>Dev : 生成可执行程序
|
||
Note over Generator,Output : 在编译时执行
|
||
Note over Dev,Compiler : 类型安全和反射优化
|
||
```
|
||
|
||
**图表来源**
|
||
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L23-L47)
|
||
- [GFramework.Godot.SourceGenerators.targets](file://GFramework.Godot.SourceGenerators/GeWuYou.GFramework.Godot.SourceGenerators.targets#L6-L10)
|
||
|
||
### Godot模块集成架构
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph "Godot模块层"
|
||
AM[AbstractGodotModule]
|
||
IM[IGodotModule]
|
||
end
|
||
subgraph "生成器层"
|
||
GM[GodotModuleMarker]
|
||
AG[AttributeClassGeneratorBase]
|
||
end
|
||
subgraph "架构层"
|
||
AA[AbstractArchitecture]
|
||
AC[Architecture]
|
||
end
|
||
AM --> IM
|
||
GM --> AG
|
||
AA --> AM
|
||
AC --> AA
|
||
```
|
||
|
||
**图表来源**
|
||
- [AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs#L1-L55)
|
||
- [IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs#L1-L27)
|
||
- [AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs#L94-L105)
|
||
|
||
**章节来源**
|
||
- [AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs#L1-L55)
|
||
- [IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs#L1-L27)
|
||
- [AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs#L94-L105)
|
||
|
||
## 详细组件分析
|
||
|
||
### 生成器初始化流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start([开始初始化]) --> CreateSyntaxProvider["创建语法提供程序"]
|
||
CreateSyntaxProvider --> FilterClasses["过滤带有特性的类"]
|
||
FilterClasses --> CombineCompilation["合并编译信息"]
|
||
CombineCompilation --> RegisterOutput["注册源码输出"]
|
||
RegisterOutput --> End([完成初始化])
|
||
FilterClasses --> CheckPartial{"类是否为partial?"}
|
||
CheckPartial --> |否| ReportError["报告错误"]
|
||
CheckPartial --> |是| ValidateSymbol["验证符号"]
|
||
ValidateSymbol --> GenerateCode["生成代码"]
|
||
GenerateCode --> AddSource["添加到源码输出"]
|
||
ReportError --> End
|
||
AddSource --> End
|
||
```
|
||
|
||
**图表来源**
|
||
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L23-L47)
|
||
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L67-L113)
|
||
|
||
### 诊断和错误处理机制
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class CommonDiagnostics {
|
||
+Diagnostic GeneratorTrace
|
||
+Trace(context, message) void
|
||
+ClassMustBePartial Location
|
||
}
|
||
class SourceProductionContext {
|
||
+ReportDiagnostic(diagnostic) void
|
||
}
|
||
CommonDiagnostics --> SourceProductionContext : "使用"
|
||
note for CommonDiagnostics "提供生成器诊断信息"
|
||
note for SourceProductionContext "报告诊断信息给编译器"
|
||
```
|
||
|
||
**图表来源**
|
||
- [CommonDiagnostics.cs](file://GFramework.SourceGenerators.Common/diagnostics/CommonDiagnostics.cs#L41-L60)
|
||
|
||
**章节来源**
|
||
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L67-L113)
|
||
- [CommonDiagnostics.cs](file://GFramework.SourceGenerators.Common/diagnostics/CommonDiagnostics.cs#L41-L60)
|
||
|
||
### 项目配置和构建流程
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph "项目配置"
|
||
CSProj[GFramework.Godot.SourceGenerators.csproj]
|
||
Targets[GeWuYou.GFramework.Godot.SourceGenerators.targets]
|
||
end
|
||
subgraph "构建过程"
|
||
Analyzer[Analyzer注册]
|
||
Dependencies[依赖管理]
|
||
Packaging[包打包]
|
||
end
|
||
subgraph "输出结果"
|
||
Generated[生成的代码]
|
||
Runtime[运行时DLL]
|
||
end
|
||
CSProj --> Analyzer
|
||
CSProj --> Dependencies
|
||
CSProj --> Packaging
|
||
Targets --> Analyzer
|
||
Analyzer --> Generated
|
||
Dependencies --> Runtime
|
||
```
|
||
|
||
**图表来源**
|
||
- [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L35-L53)
|
||
- [GeWuYou.GFramework.Godot.SourceGenerators.targets](file://GFramework.Godot.SourceGenerators/GeWuYou.GFramework.Godot.SourceGenerators.targets#L6-L10)
|
||
|
||
**章节来源**
|
||
- [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L1-L71)
|
||
- [GeWuYou.GFramework.Godot.SourceGenerators.targets](file://GFramework.Godot.SourceGenerators/GeWuYou.GFramework.Godot.SourceGenerators.targets#L1-L16)
|
||
|
||
## 依赖关系分析
|
||
|
||
### 组件耦合度分析
|
||
|
||
```mermaid
|
||
graph TD
|
||
subgraph "外部依赖"
|
||
Roslyn[Microsoft.CodeAnalysis]
|
||
NetStandard[.NET Standard 2.0]
|
||
end
|
||
subgraph "内部组件"
|
||
Generator[源代码生成器]
|
||
Abstractions[抽象层]
|
||
Diagnostics[诊断系统]
|
||
Tests[测试框架]
|
||
end
|
||
subgraph "Godot集成"
|
||
GodotAPI[Godot API]
|
||
Modules[Godot模块]
|
||
end
|
||
Roslyn --> Generator
|
||
NetStandard --> Generator
|
||
Generator --> Abstractions
|
||
Generator --> Diagnostics
|
||
Generator --> Tests
|
||
GodotAPI --> Modules
|
||
Abstractions --> Modules
|
||
```
|
||
|
||
**图表来源**
|
||
- [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L21-L33)
|
||
- [GFramework.SourceGenerators.Common.csproj](file://GFramework.SourceGenerators.Common/GFramework.SourceGenerators.Common.csproj)
|
||
|
||
### 循环依赖检测
|
||
|
||
经过分析，项目结构避免了循环依赖：
|
||
- 生成器项目仅依赖抽象层，不反向依赖具体实现
|
||
- 诊断系统独立于业务逻辑
|
||
- 测试框架独立于核心功能
|
||
|
||
**章节来源**
|
||
- [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L29-L33)
|
||
- [GFramework.Godot.SourceGenerators.Abstractions.csproj](file://GFramework.Godot.SourceGenerators.Abstractions/GFramework.Godot.SourceGenerators.Abstractions.csproj#L1-L32)
|
||
|
||
## 性能考虑
|
||
|
||
### 编译时vs运行时性能对比
|
||
|
||
| 维度 | 源代码生成器 | 手写代码 |
|
||
|------|-------------|----------|
|
||
| **编译时** | 增加编译时间（几秒） | 无需编译 |
|
||
| **运行时** | 与手写代码性能相同 | 标准性能 |
|
||
| **内存使用** | 与手写代码相同 | 标准内存使用 |
|
||
| **反射调用** | 减少或消除 | 可能较多 |
|
||
|
||
### 反射优化策略
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Before[传统反射方式] --> After[生成器优化方式]
|
||
Before --> ReflectionCalls["大量反射调用"]
|
||
ReflectionCalls --> PerformanceLoss["性能损失"]
|
||
PerformanceLoss --> MemoryOverhead["内存开销"]
|
||
After --> DirectCalls["直接方法调用"]
|
||
DirectCalls --> ZeroReflection["零反射"]
|
||
ZeroReflection --> OptimalPerformance["最佳性能"]
|
||
```
|
||
|
||
## 故障排除指南
|
||
|
||
### 常见问题和解决方案
|
||
|
||
#### 1. 生成器未生效
|
||
|
||
**症状**：编译时没有生成预期的代码文件
|
||
|
||
**排查步骤**：
|
||
1. 检查项目文件中的NuGet包引用
|
||
2. 验证特性标记是否正确应用
|
||
3. 查看生成的诊断信息
|
||
|
||
**解决方案**：
|
||
- 确保在项目文件中正确配置生成器引用
|
||
- 验证类必须标记为partial
|
||
- 检查特性名称是否匹配
|
||
|
||
#### 2. 生成代码位置问题
|
||
|
||
**默认输出位置**：`obj/Debug/net6.0/generated/`
|
||
|
||
**自定义配置**：
|
||
```xml
|
||
<PropertyGroup>
|
||
<CompilerGeneratedFilesOutputPath>Generated</CompilerGeneratedFilesOutputPath>
|
||
</PropertyGroup>
|
||
```
|
||
|
||
#### 3. 调试生成器问题
|
||
|
||
**调试方法**：
|
||
1. 启用详细日志输出
|
||
2. 检查IDE错误列表
|
||
3. 查看生成的中间代码文件
|
||
|
||
**章节来源**
|
||
- [README.md](file://GFramework.SourceGenerators/README.md#L914-L971)
|
||
|
||
### 测试和验证
|
||
|
||
#### 快照测试机制
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Test as 测试代码
|
||
participant Generator as 生成器
|
||
participant Snapshot as 快照文件
|
||
participant Validator as 验证器
|
||
Test->>Generator : 执行生成器
|
||
Generator->>Snapshot : 生成代码文件
|
||
Test->>Validator : 比较快照
|
||
Validator->>Test : 返回验证结果
|
||
Note over Test,Validator : 确保生成结果一致性
|
||
```
|
||
|
||
**图表来源**
|
||
- [GeneratorSnapshotTest.cs](file://GFramework.SourceGenerators.Tests/core/GeneratorSnapshotTest.cs#L1-L43)
|
||
|
||
**章节来源**
|
||
- [GeneratorTest.cs](file://GFramework.SourceGenerators.Tests/core/GeneratorTest.cs#L1-L39)
|
||
- [GeneratorSnapshotTest.cs](file://GFramework.SourceGenerators.Tests/core/GeneratorSnapshotTest.cs#L1-L43)
|
||
|
||
## 结论
|
||
|
||
Godot源代码生成器为GFramework框架提供了强大的自动化代码生成功能。通过特性标记驱动的方式，该生成器实现了：
|
||
|
||
1. **类型安全的模块识别**：通过GodotModuleMarker占位类型确保模块的类型安全性
|
||
2. **编译时优化**：在编译阶段生成代码，消除运行时反射开销
|
||
3. **灵活的扩展性**：基于抽象基类的设计允许轻松扩展新的生成器
|
||
4. **完善的诊断系统**：提供详细的错误报告和调试信息
|
||
|
||
该生成器显著提升了Godot项目的开发效率，同时保持了代码质量和性能表现。
|
||
|
||
## 附录
|
||
|
||
### 最佳实践建议
|
||
|
||
1. **特性标记规范**：确保所有需要生成代码的类都正确应用特性标记
|
||
2. **partial类要求**：生成器要求目标类必须标记为partial
|
||
3. **命名约定**：遵循一致的命名约定，便于代码维护
|
||
4. **测试覆盖**：为生成器功能编写充分的单元测试和快照测试
|
||
|
||
### 扩展开发指南
|
||
|
||
当需要创建自定义生成器时：
|
||
|
||
1. 继承相应的基类（AttributeClassGeneratorBase或AttributeEnumGeneratorBase）
|
||
2. 实现必需的抽象方法
|
||
3. 在Initialize方法中配置语法提供程序
|
||
4. 实现Generate方法生成具体的源代码
|
||
5. 添加适当的诊断信息和错误处理 |