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]
15 KiB
15 KiB
Godot源代码生成器
**本文档引用的文件** - [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)目录
简介
Godot源代码生成器是GFramework框架中用于自动化生成Godot模块相关代码的工具集。该生成器基于Roslyn源代码生成技术，在编译时自动识别和处理带有特定特性的类，生成相应的Godot模块配置代码。
该生成器的主要目标是：
- 自动化模块标记：通过特性标记自动识别Godot模块
- 编译时代码生成：在编译阶段生成所需的模块配置代码
- 反射优化：减少运行时反射调用，提升性能
- 类型安全：确保生成代码的类型安全性
- 开发效率：简化Godot模块的开发和配置过程
项目结构
GFramework源代码生成器采用分层架构设计，主要包含以下核心模块：
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
图表来源
章节来源
核心组件
GodotModuleMarker标记器
GodotModuleMarker是Godot模块命名空间的占位类型，用于标识和标记Godot模块相关的代码区域。
classDiagram
class GodotModuleMarker {
<<sealed>>
+internal GodotModuleMarker()
}
note for GodotModuleMarker "用于标记Godot模块命名空间的占位类型"
图表来源
基础生成器架构
所有生成器都基于AttributeClassGeneratorBase抽象基类构建，该基类提供了统一的生成器模式：
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
图表来源
章节来源
架构概览
编译时代码生成流程
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 : 类型安全和反射优化
图表来源
Godot模块集成架构
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
图表来源
章节来源
详细组件分析
生成器初始化流程
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
图表来源
诊断和错误处理机制
classDiagram
class CommonDiagnostics {
+Diagnostic GeneratorTrace
+Trace(context, message) void
+ClassMustBePartial Location
}
class SourceProductionContext {
+ReportDiagnostic(diagnostic) void
}
CommonDiagnostics --> SourceProductionContext : "使用"
note for CommonDiagnostics "提供生成器诊断信息"
note for SourceProductionContext "报告诊断信息给编译器"
图表来源
章节来源
项目配置和构建流程
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
图表来源
章节来源
依赖关系分析
组件耦合度分析
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
图表来源
循环依赖检测
经过分析，项目结构避免了循环依赖：
- 生成器项目仅依赖抽象层，不反向依赖具体实现
- 诊断系统独立于业务逻辑
- 测试框架独立于核心功能
章节来源
性能考虑
编译时vs运行时性能对比
| 维度 | 源代码生成器 | 手写代码 |
|---|---|---|
| 编译时 | 增加编译时间（几秒） | 无需编译 |
| 运行时 | 与手写代码性能相同 | 标准性能 |
| 内存使用 | 与手写代码相同 | 标准内存使用 |
| 反射调用 | 减少或消除 | 可能较多 |
反射优化策略
flowchart TD
Before[传统反射方式] --> After[生成器优化方式]
Before --> ReflectionCalls["大量反射调用"]
ReflectionCalls --> PerformanceLoss["性能损失"]
PerformanceLoss --> MemoryOverhead["内存开销"]
After --> DirectCalls["直接方法调用"]
DirectCalls --> ZeroReflection["零反射"]
ZeroReflection --> OptimalPerformance["最佳性能"]
故障排除指南
常见问题和解决方案
1. 生成器未生效
症状：编译时没有生成预期的代码文件
排查步骤：
- 检查项目文件中的NuGet包引用
- 验证特性标记是否正确应用
- 查看生成的诊断信息
解决方案：
- 确保在项目文件中正确配置生成器引用
- 验证类必须标记为partial
- 检查特性名称是否匹配
2. 生成代码位置问题
默认输出位置：obj/Debug/net6.0/generated/
自定义配置：
<PropertyGroup>
<CompilerGeneratedFilesOutputPath>Generated</CompilerGeneratedFilesOutputPath>
</PropertyGroup>
3. 调试生成器问题
调试方法：
- 启用详细日志输出
- 检查IDE错误列表
- 查看生成的中间代码文件
章节来源
测试和验证
快照测试机制
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 : 确保生成结果一致性
图表来源
章节来源
结论
Godot源代码生成器为GFramework框架提供了强大的自动化代码生成功能。通过特性标记驱动的方式，该生成器实现了：
- 类型安全的模块识别：通过GodotModuleMarker占位类型确保模块的类型安全性
- 编译时优化：在编译阶段生成代码，消除运行时反射开销
- 灵活的扩展性：基于抽象基类的设计允许轻松扩展新的生成器
- 完善的诊断系统：提供详细的错误报告和调试信息
该生成器显著提升了Godot项目的开发效率，同时保持了代码质量和性能表现。
附录
最佳实践建议
- 特性标记规范：确保所有需要生成代码的类都正确应用特性标记
- partial类要求：生成器要求目标类必须标记为partial
- 命名约定：遵循一致的命名约定，便于代码维护
- 测试覆盖：为生成器功能编写充分的单元测试和快照测试
扩展开发指南
当需要创建自定义生成器时：
- 继承相应的基类（AttributeClassGeneratorBase或AttributeEnumGeneratorBase）
- 实现必需的抽象方法
- 在Initialize方法中配置语法提供程序
- 实现Generate方法生成具体的源代码
- 添加适当的诊断信息和错误处理