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]
333 lines
18 KiB
Markdown
333 lines
18 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.SourceGenerators.csproj](file://GFramework.SourceGenerators/GFramework.SourceGenerators.csproj)
|
||
- [GFramework.SourceGenerators.Common.csproj](file://GFramework.SourceGenerators.Common/GFramework.SourceGenerators.Common.csproj)
|
||
- [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)
|
||
- [ContextAwareAttribute.cs](file://GFramework.SourceGenerators.Abstractions/rule/ContextAwareAttribute.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)
|
||
- [godot-api.md](file://docs/api-reference/godot-api.md)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [引言](#引言)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 引言
|
||
本文件面向Godot引擎的开发者，系统性阐述“Godot源代码生成器”的设计与实现，重点覆盖以下主题：
|
||
- GodotModuleMarker的标记生成机制与作用域隔离
|
||
- 基于属性标记的Godot模块自动发现与注册流程
|
||
- Godot源代码生成器与通用生成器的差异与Godot特化能力
|
||
- 生成器配置选项、使用场景与最佳实践
|
||
- 从模块标记到完整模块类的生成流程
|
||
- 在Godot项目中的集成示例与常见问题
|
||
- 性能优化与调试技巧
|
||
|
||
## 项目结构
|
||
该仓库采用多项目分层组织，围绕“通用生成器”和“Godot特化生成器”两条主线展开：
|
||
- 通用生成器层：提供跨平台、跨框架的增量式源码生成基础设施
|
||
- Godot特化生成器层：在通用基础上，针对Godot模块系统进行定制化扩展
|
||
- 抽象与公共基础：为两套生成器提供共享的抽象类型与通用工具
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "通用生成器"
|
||
SGProj["GFramework.SourceGenerators.csproj"]
|
||
SGCommonProj["GFramework.SourceGenerators.Common.csproj"]
|
||
SGAbstProj["GFramework.SourceGenerators.Abstractions.csproj"]
|
||
end
|
||
subgraph "Godot特化生成器"
|
||
GSGProj["GFramework.Godot.SourceGenerators.csproj"]
|
||
GSGAbstProj["GFramework.Godot.SourceGenerators.Abstractions.csproj"]
|
||
GSTargets["GeWuYou.GFramework.Godot.SourceGenerators.targets"]
|
||
end
|
||
subgraph "Godot运行时"
|
||
IGodotModule["IGodotModule.cs"]
|
||
AbstractGodotModule["AbstractGodotModule.cs"]
|
||
AbstractArchitecture["AbstractArchitecture.cs"]
|
||
end
|
||
SGProj --> SGCommonProj
|
||
SGProj --> SGAbstProj
|
||
GSGProj --> GSGAbstProj
|
||
GSGProj --> SGCommonProj
|
||
GSGProj --> SGAbstProj
|
||
GSGProj --> GSTargets
|
||
IGodotModule --> AbstractGodotModule
|
||
AbstractGodotModule --> AbstractArchitecture
|
||
```
|
||
|
||
图表来源
|
||
- [GFramework.SourceGenerators.csproj](file://GFramework.SourceGenerators/GFramework.SourceGenerators.csproj#L1-L64)
|
||
- [GFramework.SourceGenerators.Common.csproj](file://GFramework.SourceGenerators.Common/GFramework.SourceGenerators.Common.csproj#L1-L39)
|
||
- [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)
|
||
- [GeWuYou.GFramework.Godot.SourceGenerators.targets](file://GFramework.Godot.SourceGenerators/GeWuYou.GFramework.Godot.SourceGenerators.targets#L1-L16)
|
||
- [IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs#L1-L27)
|
||
- [AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs#L1-L55)
|
||
- [AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs#L66-L105)
|
||
|
||
章节来源
|
||
- [GFramework.SourceGenerators.csproj](file://GFramework.SourceGenerators/GFramework.SourceGenerators.csproj#L1-L64)
|
||
- [GFramework.SourceGenerators.Common.csproj](file://GFramework.SourceGenerators.Common/GFramework.SourceGenerators.Common.csproj#L1-L39)
|
||
- [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)
|
||
- [GeWuYou.GFramework.Godot.SourceGenerators.targets](file://GFramework.Godot.SourceGenerators/GeWuYou.Godot.SourceGenerators.targets#L1-L16)
|
||
|
||
## 核心组件
|
||
- GodotModuleMarker：作为Godot模块命名空间的占位类型，用于隔离与标记Godot模块相关的生成范围，避免与其他生成器产生命名冲突或误匹配。
|
||
- 通用生成器基类：提供基于属性的增量式源码生成骨架，支持类与枚举两类目标，具备统一的候选收集、语义解析与输出注册流程。
|
||
- Godot特化生成器：在通用生成器之上，结合Godot模块接口与生命周期，实现模块类的自动发现与注册。
|
||
|
||
章节来源
|
||
- [GodotModuleMarker.cs](file://GFramework.Godot.SourceGenerators.Abstractions/GodotModuleMarker.cs#L1-L6)
|
||
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L1-L67)
|
||
- [AttributeEnumGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeEnumGeneratorBase.cs#L1-L33)
|
||
|
||
## 架构总览
|
||
Godot源代码生成器通过MSBuild targets在编译前加载Analyzer，利用Roslyn增量生成器扫描带特定属性的类/枚举，生成对应模块注册与装配代码。运行时由AbstractArchitecture负责模块生命周期管理与节点挂载。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Dev as "开发者"
|
||
participant MSBuild as "MSBuild"
|
||
participant Targets as "targets文件"
|
||
participant Analyzer as "Godot源代码生成器"
|
||
participant Compiler as "C#编译器"
|
||
participant Runtime as "Godot运行时"
|
||
Dev->>MSBuild : 触发构建
|
||
MSBuild->>Targets : 加载生成器注册项
|
||
Targets->>Analyzer : 注册Analyzer并执行
|
||
Analyzer->>Compiler : 增量扫描带属性的类型
|
||
Compiler-->>Analyzer : 返回候选类型与语义信息
|
||
Analyzer-->>Compiler : 输出生成的源代码文件
|
||
Compiler-->>Runtime : 生成可执行/程序集
|
||
Runtime->>Runtime : AbstractArchitecture安装模块
|
||
Runtime-->>Dev : 模块按阶段激活
|
||
```
|
||
|
||
图表来源
|
||
- [GeWuYou.GFramework.Godot.SourceGenerators.targets](file://GFramework.Godot.SourceGenerators/GeWuYou.Godot.SourceGenerators.targets#L1-L16)
|
||
- [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L35-L53)
|
||
- [AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs#L66-L105)
|
||
|
||
## 详细组件分析
|
||
|
||
### 组件A：GodotModuleMarker与命名空间隔离
|
||
- 作用：以内部密封类形式为Godot模块相关生成逻辑提供命名空间占位，避免与通用生成器或其他模块生成器发生命名冲突。
|
||
- 影响：确保生成器仅作用于Godot模块命名空间内的类型，提升生成范围的确定性与安全性。
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class GodotModuleMarker {
|
||
<<sealed>>
|
||
+internal
|
||
}
|
||
```
|
||
|
||
图表来源
|
||
- [GodotModuleMarker.cs](file://GFramework.Godot.SourceGenerators.Abstractions/GodotModuleMarker.cs#L1-L6)
|
||
|
||
章节来源
|
||
- [GodotModuleMarker.cs](file://GFramework.Godot.SourceGenerators.Abstractions/GodotModuleMarker.cs#L1-L6)
|
||
|
||
### 组件B：通用属性类生成器基类
|
||
- 功能：基于属性标记的增量式源码生成骨架，支持：
|
||
- 语法级候选收集：筛选包含指定属性名的类声明
|
||
- 语义级解析：获取类型符号与属性元数据
|
||
- 组合并输出：将候选与编译上下文组合，触发源码生成
|
||
- 关键点：
|
||
- 通过AttributeShortNameWithoutSuffix约定子类生成器的属性匹配规则
|
||
- 通过ResolveAttribute与Execute解耦具体生成逻辑
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["开始: 初始化生成器"]) --> CollectSyntax["收集带属性的类声明"]
|
||
CollectSyntax --> FilterCandidates["过滤候选类型"]
|
||
FilterCandidates --> Combine["与编译上下文组合"]
|
||
Combine --> ResolveAttr["解析属性元数据"]
|
||
ResolveAttr --> Generate["生成源代码输出"]
|
||
Generate --> End(["结束"])
|
||
```
|
||
|
||
图表来源
|
||
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L23-L48)
|
||
|
||
章节来源
|
||
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L1-L67)
|
||
|
||
### 组件C：通用属性枚举生成器基类
|
||
- 功能：与类生成器类似，但面向枚举声明，同样基于属性名匹配与语义解析，最终输出扩展代码。
|
||
- 适用场景：为Godot模块系统中的枚举型配置或状态提供自动生成的辅助方法或常量。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["开始: 初始化枚举生成器"]) --> CollectEnum["收集带属性的枚举声明"]
|
||
CollectEnum --> FilterEnum["过滤枚举候选"]
|
||
FilterEnum --> Combine["与编译上下文组合"]
|
||
Combine --> ResolveEnum["解析属性元数据"]
|
||
ResolveEnum --> GenerateEnum["生成枚举扩展代码"]
|
||
GenerateEnum --> End(["结束"])
|
||
```
|
||
|
||
图表来源
|
||
- [AttributeEnumGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeEnumGeneratorBase.cs#L21-L33)
|
||
|
||
章节来源
|
||
- [AttributeEnumGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeEnumGeneratorBase.cs#L1-L33)
|
||
|
||
### 组件D：Godot模块接口与抽象基类
|
||
- IGodotModule：定义Godot模块的最小接口契约，包括节点引用、附加/分离回调以及与架构的交互。
|
||
- AbstractGodotModule：提供默认空实现，便于子类按需覆盖生命周期钩子与安装逻辑。
|
||
- AbstractArchitecture：在运行时负责模块安装、阶段通知与Godot生命周期绑定（如场景树锚点）。
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class IGodotModule {
|
||
+Node Node
|
||
+OnAttach(architecture)
|
||
+OnDetach()
|
||
}
|
||
class AbstractGodotModule {
|
||
+Node Node
|
||
+Install(architecture)
|
||
+OnAttach(architecture)
|
||
+OnDetach()
|
||
+OnPhase(phase, architecture)
|
||
+OnArchitecturePhase(phase)
|
||
}
|
||
class AbstractArchitecture {
|
||
+InstallModules()
|
||
+InstallGodotModule(module)
|
||
-AttachToGodotLifecycle()
|
||
}
|
||
IGodotModule <|.. AbstractGodotModule
|
||
AbstractArchitecture --> IGodotModule : "安装/管理"
|
||
```
|
||
|
||
图表来源
|
||
- [IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs#L1-L27)
|
||
- [AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs#L1-L55)
|
||
- [AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs#L66-L105)
|
||
|
||
章节来源
|
||
- [IGodotModule.cs](file://GFramework.Godot/architecture/IGodotModule.cs#L1-L27)
|
||
- [AbstractGodotModule.cs](file://GFramework.Godot/architecture/AbstractGodotModule.cs#L1-L55)
|
||
- [AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs#L66-L105)
|
||
|
||
### 组件E：生成器打包与加载机制
|
||
- GFramework.Godot.SourceGenerators.csproj：将生成器DLL及其运行期依赖打包至analyzers目录，供MSBuild在编译前加载。
|
||
- GeWuYou.GFramework.Godot.SourceGenerators.targets：在BeforeTargets=CoreCompile阶段注入Analyzer，确保生成器参与编译。
|
||
- GFramework.SourceGenerators.csproj与GFramework.SourceGenerators.Common.csproj：通用生成器的打包与加载策略一致，体现复用性。
|
||
|
||
```mermaid
|
||
graph LR
|
||
Build["MSBuild 构建"] --> Targets["targets 文件注册 Analyzer"]
|
||
Targets --> Analyzer["加载 Godot 源代码生成器"]
|
||
Analyzer --> Output["生成器输出源代码文件"]
|
||
Output --> Compile["编译器编译"]
|
||
```
|
||
|
||
图表来源
|
||
- [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L35-L53)
|
||
- [GeWuYou.GFramework.Godot.SourceGenerators.targets](file://GFramework.Godot.SourceGenerators/GeWuYou.Godot.SourceGenerators.targets#L6-L15)
|
||
- [GFramework.SourceGenerators.csproj](file://GFramework.SourceGenerators/GFramework.SourceGenerators.csproj#L36-L55)
|
||
|
||
章节来源
|
||
- [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L1-L71)
|
||
- [GeWuYou.GFramework.Godot.SourceGenerators.targets](file://GFramework.Godot.SourceGenerators/GeWuYou.Godot.SourceGenerators.targets#L1-L16)
|
||
- [GFramework.SourceGenerators.csproj](file://GFramework.SourceGenerators/GFramework.SourceGenerators.csproj#L1-L64)
|
||
- [GFramework.SourceGenerators.Common.csproj](file://GFramework.SourceGenerators.Common/GFramework.SourceGenerators.Common.csproj#L1-L39)
|
||
|
||
## 依赖关系分析
|
||
- 生成器打包策略：生成器DLL与运行期依赖均被打包到analyzers/dotnet/cs路径，确保在编译阶段可用。
|
||
- 目标文件注入：通过targets文件在CoreCompile前注入Analyzer，保证生成器在编译早期参与。
|
||
- 项目间依赖：Godot特化生成器同时引用通用生成器公共库与抽象层，形成“通用+特化”的双层架构。
|
||
|
||
```mermaid
|
||
graph TB
|
||
GSGProj["Godot生成器项目"] --> GSGAbst["Godot生成器抽象层"]
|
||
GSGProj --> SGCommon["通用生成器公共库"]
|
||
GSGProj --> Targets["targets 注册 Analyzer"]
|
||
SGProj["通用生成器项目"] --> SGCommon
|
||
SGProj --> SGAbst
|
||
```
|
||
|
||
图表来源
|
||
- [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L29-L53)
|
||
- [GFramework.SourceGenerators.csproj](file://GFramework.SourceGenerators/GFramework.SourceGenerators.csproj#L29-L55)
|
||
- [GeWuYou.GFramework.Godot.SourceGenerators.targets](file://GFramework.Godot.SourceGenerators/GeWuYou.Godot.SourceGenerators.targets#L6-L10)
|
||
|
||
章节来源
|
||
- [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L1-L71)
|
||
- [GFramework.SourceGenerators.csproj](file://GFramework.SourceGenerators/GFramework.SourceGenerators.csproj#L1-L64)
|
||
- [GFramework.SourceGenerators.Common.csproj](file://GFramework.SourceGenerators.Common/GFramework.SourceGenerators.Common.csproj#L1-L39)
|
||
- [GeWuYou.GFramework.Godot.SourceGenerators.targets](file://GFramework.Godot.SourceGenerators/GeWuYou.Godot.SourceGenerators.targets#L1-L16)
|
||
|
||
## 性能考虑
|
||
- 增量生成：基于IIncrementalGenerator，仅在属性或类型变更时重新生成，减少全量编译成本。
|
||
- 语义解析分离：先语法收集，再语义解析，避免不必要的符号查询开销。
|
||
- 生成范围控制：通过GodotModuleMarker等占位类型限定生成范围，降低无关类型扫描与生成压力。
|
||
- 依赖打包优化：将生成器与依赖打包至analyzers，避免运行时额外加载开销。
|
||
|
||
## 故障排除指南
|
||
- 生成器未生效
|
||
- 确认targets文件已被MSBuild加载（BeforeTargets=CoreCompile阶段）
|
||
- 检查analyzers目录下是否存在生成器DLL与依赖
|
||
- 生成范围不符合预期
|
||
- 检查属性名称是否与AttributeShortNameWithoutSuffix约定一致
|
||
- 确保目标类型位于Godot模块命名空间内，避免与通用生成器混淆
|
||
- 运行时模块未注册
|
||
- 确认AbstractArchitecture的InstallModules中调用了InstallGodotModule
|
||
- 检查模块是否实现IGodotModule并正确返回Node
|
||
|
||
章节来源
|
||
- [GeWuYou.GFramework.Godot.SourceGenerators.targets](file://GFramework.Godot.SourceGenerators/GeWuYou.Godot.SourceGenerators.targets#L12-L15)
|
||
- [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L35-L53)
|
||
- [AbstractArchitecture.cs](file://GFramework.Godot/architecture/AbstractArchitecture.cs#L66-L105)
|
||
|
||
## 结论
|
||
Godot源代码生成器通过“命名空间占位+增量生成+Analyzer打包”的组合，实现了Godot模块的自动发现与注册。它在通用生成器基础设施之上，提供了Godot特化的接口与生命周期集成，既保持了良好的可维护性，又满足了引擎层面的性能与稳定性要求。
|
||
|
||
## 附录
|
||
|
||
### 使用场景与最佳实践
|
||
- 场景
|
||
- 需要为Godot模块自动注册系统、工具与页面的行为
|
||
- 希望在编译期生成模块装配代码，减少运行时反射成本
|
||
- 最佳实践
|
||
- 将模块类置于Godot模块命名空间，配合GodotModuleMarker实现范围隔离
|
||
- 为模块类添加Godot特化属性，确保生成器能正确识别
|
||
- 在AbstractArchitecture的InstallModules中集中调用InstallGodotModule
|
||
|
||
章节来源
|
||
- [godot-api.md](file://docs/api-reference/godot-api.md#L70-L125)
|
||
|
||
### 配置选项与打包细节
|
||
- 生成器项目属性
|
||
- TargetFramework: netstandard2.0
|
||
- IsRoslynAnalyzer: true
|
||
- EmitCompilerGeneratedFiles: true（可选，便于调试生成代码）
|
||
- 打包策略
|
||
- 生成器DLL与依赖打包至analyzers/dotnet/cs
|
||
- targets文件随包进入build目录，确保在编译前加载
|
||
|
||
章节来源
|
||
- [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L3-L18)
|
||
- [GFramework.Godot.SourceGenerators.csproj](file://GFramework.Godot.SourceGenerators/GFramework.Godot.SourceGenerators.csproj#L35-L61)
|
||
- [GeWuYou.GFramework.Godot.SourceGenerators.targets](file://GFramework.Godot.SourceGenerators/GeWuYou.Godot.SourceGenerators.targets#L6-L10) |