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]
20 KiB
20 KiB
上下文感知生成器
**本文档引用的文件** - [ContextAwareGenerator.cs](file://GFramework.SourceGenerators/rule/ContextAwareGenerator.cs) - [ContextAwareAttribute.cs](file://GFramework.SourceGenerators.Abstractions/rule/ContextAwareAttribute.cs) - [IContextAware.cs](file://GFramework.Core.Abstractions/rule/IContextAware.cs) - [ContextAwareDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/ContextAwareDiagnostic.cs) - [ContextAwareBase.cs](file://GFramework.Core/rule/ContextAwareBase.cs) - [GameContext.cs](file://GFramework.Core/architecture/GameContext.cs) - [IArchitectureContext.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureContext.cs) - [ContextAwareExtensions.cs](file://GFramework.Core/extensions/ContextAwareExtensions.cs) - [ContextAwareStateBase.cs](file://GFramework.Core/state/ContextAwareStateBase.cs) - [MetadataAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/MetadataAttributeClassGeneratorBase.cs) - [PathContests.cs](file://GFramework.SourceGenerators.Common/constants/PathContests.cs) - [ContextAwareGeneratorSnapshotTests.cs](file://GFramework.SourceGenerators.Tests/rule/ContextAwareGeneratorSnapshotTests.cs) - [ContextAwareTests.cs](file://GFramework.Core.Tests/rule/ContextAwareTests.cs)目录
简介
本文件面向“上下文感知生成器”的技术文档，系统阐述 ContextAwareGenerator 的工作原理与使用方法，涵盖以下要点：
- ContextAwareAttribute 属性的使用方法与约束
- IContextAware 接口的自动生成与显式接口实现
- 上下文访问方法的实现与懒加载策略
- 诊断系统的工作机制（ContextAwareDiagnostic）
- 生成器如何为标记了 ContextAware 属性的类自动实现 IContextAware
- 生成代码结构与接口实现细节
- 与架构系统的集成方式与最佳实践
- 常见问题与调试技巧
项目结构
围绕上下文感知生成器的关键文件分布如下：
- 源代码生成器：GFramework.SourceGenerators/rule/ContextAwareGenerator.cs
- 属性定义：GFramework.SourceGenerators.Abstractions/rule/ContextAwareAttribute.cs
- 接口定义：GFramework.Core.Abstractions/rule/IContextAware.cs
- 诊断规则：GFramework.SourceGenerators/diagnostics/ContextAwareDiagnostic.cs
- 基类实现：GFramework.Core/rule/ContextAwareBase.cs
- 架构上下文：GFramework.Core/architecture/GameContext.cs
- 上下文接口：GFramework.Core.Abstractions/architecture/IArchitectureContext.cs
- 扩展方法：GFramework.Core/extensions/ContextAwareExtensions.cs
- 状态基类：GFramework.Core/state/ContextAwareStateBase.cs
- 生成器基类：GFramework.SourceGenerators.Common/generator/MetadataAttributeClassGeneratorBase.cs
- 路径常量：GFramework.SourceGenerators.Common/constants/PathContests.cs
- 快照测试：GFramework.SourceGenerators.Tests/rule/ContextAwareGeneratorSnapshotTests.cs
- 单元测试：GFramework.Core.Tests/rule/ContextAwareTests.cs
graph TB
subgraph "源代码生成器层"
GEN["ContextAwareGenerator<br/>生成器"]
BASE["MetadataAttributeClassGeneratorBase<br/>元数据属性类生成器基类"]
ATTR["ContextAwareAttribute<br/>特性"]
DIAG["ContextAwareDiagnostic<br/>诊断规则"]
PATH["PathContests<br/>路径常量"]
end
subgraph "核心抽象层"
ICA["IContextAware<br/>上下文感知接口"]
IAC["IArchitectureContext<br/>架构上下文接口"]
end
subgraph "核心实现层"
CABS["ContextAwareBase<br/>基类实现"]
GC["GameContext<br/>架构上下文管理"]
EXT["ContextAwareExtensions<br/>扩展方法"]
STATE["ContextAwareStateBase<br/>状态基类"]
end
GEN --> BASE
GEN --> ATTR
GEN --> DIAG
GEN --> PATH
GEN --> ICA
GEN --> IAC
CABS --> ICA
EXT --> ICA
EXT --> IAC
GC --> IAC
STATE --> ICA
图表来源
- ContextAwareGenerator.cs
- MetadataAttributeClassGeneratorBase.cs
- ContextAwareAttribute.cs
- ContextAwareDiagnostic.cs
- PathContests.cs
- IContextAware.cs
- IArchitectureContext.cs
- ContextAwareBase.cs
- GameContext.cs
- ContextAwareExtensions.cs
- ContextAwareStateBase.cs
章节来源
- ContextAwareGenerator.cs
- ContextAwareAttribute.cs
- IContextAware.cs
- ContextAwareDiagnostic.cs
- ContextAwareBase.cs
- GameContext.cs
- IArchitectureContext.cs
- ContextAwareExtensions.cs
- ContextAwareStateBase.cs
- MetadataAttributeClassGeneratorBase.cs
- PathContests.cs
核心组件
- ContextAwareGenerator：基于特性元数据扫描并为标记了 ContextAware 的类自动生成 IContextAware 接口实现，包含 Context 属性与显式接口实现。
- ContextAwareAttribute：仅作用于类的特性标记，指示该类需要自动生成上下文感知实现。
- IContextAware：定义 SetContext 与 GetContext 两个核心方法，提供上下文注入与访问能力。
- ContextAwareDiagnostic：提供错误诊断规则，如 ContextAware 仅能用于类等。
- ContextAwareBase：框架提供的基类实现，包含 Context 属性、显式接口实现与 OnContextReady 回调。
- GameContext：静态上下文管理器，提供架构上下文的注册、获取与查询能力。
- IArchitectureContext：架构上下文接口，提供系统、模型、工具、命令、查询、事件等访问能力。
- ContextAwareExtensions：为 IContextAware 提供扩展方法，简化对上下文内服务的访问。
- ContextAwareStateBase：同时实现 IState 与 IContextAware 的状态基类。
章节来源
- ContextAwareGenerator.cs
- ContextAwareAttribute.cs
- IContextAware.cs
- ContextAwareDiagnostic.cs
- ContextAwareBase.cs
- GameContext.cs
- IArchitectureContext.cs
- ContextAwareExtensions.cs
- ContextAwareStateBase.cs
架构总览
上下文感知生成器的整体工作流如下：
- 编译阶段：Roslyn 分析源码，识别标记了 ContextAware 特性的类
- 生成阶段：ContextAwareGenerator 基于 MetadataAttributeClassGeneratorBase 解析特性元数据，校验类的合法性（partial、class），生成实现 IContextAware 的部分类
- 运行阶段：类通过 Context 属性或显式接口方法访问 IArchitectureContext；GameContext 提供上下文注册与获取；扩展方法简化对系统、模型、工具、命令、查询、事件的访问
sequenceDiagram
participant Dev as "开发者"
participant Roslyn as "编译器/源生成器"
participant Gen as "ContextAwareGenerator"
participant Base as "MetadataAttributeClassGeneratorBase"
participant Attr as "ContextAwareAttribute"
participant Intf as "IContextAware"
participant Impl as "生成的部分类"
participant Ctx as "GameContext"
Dev->>Roslyn : 添加 [ContextAware] 到类
Roslyn->>Gen : 触发源代码生成
Gen->>Base : 继承元数据解析
Gen->>Attr : 解析特性元数据
Gen->>Impl : 生成实现 IContextAware 的部分类
Impl->>Intf : 显式接口实现 SetContext/GetContext
Impl->>Ctx : 懒加载获取 IArchitectureContext
Dev-->>Impl : 使用 Context 访问架构服务
图表来源
- ContextAwareGenerator.cs
- MetadataAttributeClassGeneratorBase.cs
- ContextAwareAttribute.cs
- IContextAware.cs
- GameContext.cs
详细组件分析
ContextAwareGenerator 工作原理
- 特性解析：通过 MetadataAttributeClassGeneratorBase 的 ResolveAttribute 基于元数据名称解析 ContextAwareAttribute
- 符号验证：ValidateSymbol 校验类必须为 partial class，否则报告诊断错误
- 代码生成：Generate 输出部分类，显式实现 IContextAware，并生成 Context 属性与方法体
- 方法体生成：针对 SetContext/GetContext 生成具体逻辑，其他方法默认抛出未实现异常
classDiagram
class ContextAwareGenerator {
+AttributeMetadataName : string
+AttributeShortNameWithoutSuffix : string
+ValidateSymbol(...)
+Generate(...)
+GetHintName(symbol) string
-GenerateContextProperty(sb)
-GenerateInterfaceImplementations(sb, interfaceSymbol)
-GenerateMethod(sb, interfaceName, method)
-GenerateMethodBody(sb, method)
}
class MetadataAttributeClassGeneratorBase {
#AttributeMetadataName : string
#ResolveAttribute(compilation, symbol) AttributeData
}
class ContextAwareAttribute {
<<sealed>>
}
class IContextAware {
+SetContext(context)
+GetContext() IArchitectureContext
}
ContextAwareGenerator --|> MetadataAttributeClassGeneratorBase
ContextAwareGenerator --> ContextAwareAttribute : "解析元数据"
ContextAwareGenerator --> IContextAware : "生成显式实现"
图表来源
- ContextAwareGenerator.cs
- MetadataAttributeClassGeneratorBase.cs
- ContextAwareAttribute.cs
- IContextAware.cs
章节来源
Context 属性与上下文解析逻辑
- Context 属性为受保护的懒加载实现，首次访问时通过 GameContext.GetFirstArchitectureContext() 获取第一个可用的架构上下文
- 生成的代码中使用 fully qualified 名称（global:: 前缀）确保跨程序集引用的稳定性
- Context 属性的生成逻辑包含字段缓存与延迟初始化分支
flowchart TD
Start(["访问 Context 属性"]) --> Check["_context 是否为 null?"]
Check --> |是| Load["调用 GameContext.GetFirstArchitectureContext()"]
Load --> Cache["缓存到 _context"]
Cache --> Return["返回 _context"]
Check --> |否| Return
图表来源
章节来源
显式接口实现与方法体生成
- 生成器遍历 IContextAware 的所有普通方法，逐个生成显式接口实现
- SetContext：直接赋值内部字段
- GetContext：返回 Context 属性
- 其他方法：若非 void，抛出未实现异常，避免误用
flowchart TD
Enter(["生成方法体"]) --> Name{"方法名"}
Name --> |SetContext| Set["_context = context"]
Name --> |GetContext| Get["return Context"]
Name --> |其他| Void{"是否 void?"}
Void --> |是| End(["结束"])
Void --> |否| Throw["抛出 NotImplementedException"]
Set --> End
Get --> End
Throw --> End
图表来源
章节来源
诊断系统工作机制
- ContextAwareDiagnostic 定义 GF_Rule_001 诊断规则，限制 ContextAwareAttribute 仅能应用于类
- ContextAwareGenerator 在 ValidateSymbol 中对类声明进行 partial 与 class 校验，不符合条件时报告诊断
flowchart TD
Scan["扫描类声明"] --> Partial{"是否 partial?"}
Partial --> |否| Report1["报告 ClassMustBePartial 诊断"]
Partial --> |是| Class{"是否 class?"}
Class --> |否| Report2["报告 ContextAwareOnlyForClass 诊断"]
Class --> |是| Pass["通过验证"]
图表来源
章节来源
与架构系统的集成与最佳实践
- 上下文注入：通过 IContextAware.SetContext 注入 IArchitectureContext，随后可通过 Context 属性或扩展方法访问系统、模型、工具、命令、查询、事件等
- 懒加载策略：Context 属性在首次访问时才解析架构上下文，避免不必要的初始化开销
- 扩展方法：ContextAwareExtensions 提供 GetSystem/GetModel/GetUtility/SendCommand/SendQuery/SendEvent/RegisterEvent 等便捷方法，减少样板代码
- 状态管理：ContextAwareStateBase 同时实现 IState 与 IContextAware，便于状态机场景下的上下文访问
章节来源
使用示例与生成代码结构
- 在类上添加 [ContextAware] 特性，并确保类为 partial class
- 生成器会自动生成部分类，显式实现 IContextAware，并提供 Context 属性
- 生成的代码位于提示名称为 类名.ContextAware.g.cs 的文件中
参考快照测试以了解生成器输出的预期结构与行为。
章节来源
依赖关系分析
- ContextAwareGenerator 依赖：
- MetadataAttributeClassGeneratorBase：提供基于元数据名称解析特性的能力
- PathContests：提供核心抽象层命名空间常量，用于拼接接口全名
- ContextAwareAttribute：作为特性元数据名称来源
- IContextAware：生成显式接口实现的目标接口
- GameContext：提供上下文解析入口
- ContextAwareBase 依赖：
- IContextAware：作为基类实现接口
- GameContext：在 GetContext 未设置时提供默认上下文解析
- ContextAwareExtensions 依赖：
- IContextAware：扩展方法的接收者
- IArchitectureContext：扩展方法内部调用上下文方法
graph LR
GEN["ContextAwareGenerator"] --> BASE["MetadataAttributeClassGeneratorBase"]
GEN --> PATH["PathContests"]
GEN --> ATTR["ContextAwareAttribute"]
GEN --> INTF["IContextAware"]
GEN --> CTX["GameContext"]
CBASE["ContextAwareBase"] --> INTF
CBASE --> CTX
EXT["ContextAwareExtensions"] --> INTF
EXT --> CTX
图表来源
- ContextAwareGenerator.cs
- MetadataAttributeClassGeneratorBase.cs
- PathContests.cs
- ContextAwareAttribute.cs
- IContextAware.cs
- GameContext.cs
- ContextAwareBase.cs
- ContextAwareExtensions.cs
章节来源
- ContextAwareGenerator.cs
- MetadataAttributeClassGeneratorBase.cs
- PathContests.cs
- ContextAwareBase.cs
- ContextAwareExtensions.cs
性能考虑
- 懒加载 Context 属性：首次访问时才解析架构上下文，避免无谓的初始化
- 显式接口实现：生成器按需生成方法体，未覆盖的方法默认抛出异常，防止运行期误用
- 扩展方法：通过 IContextAware.GetContext() 获取上下文后再调用，避免重复解析
故障排查指南
- 诊断规则 GF_Rule_001：确认 [ContextAware] 仅用于类，且类声明为 partial
- 运行期异常：若调用未覆盖的方法（非 SetContext/GetContext），将抛出未实现异常；请检查生成的接口实现是否完整
- 上下文未设置：GetContext 在未设置时会尝试获取第一个架构上下文；若无可用上下文，需先通过 GameContext.Bind 注册
章节来源
结论
上下文感知生成器通过特性驱动的方式，为标记了 ContextAware 的类自动生成 IContextAware 接口实现，结合 Context 属性的懒加载与扩展方法，提供了简洁而强大的架构上下文访问能力。配合诊断系统与测试用例，可有效保障生成代码的质量与一致性。
附录
- 快照测试：验证生成器输出与预期一致
- 单元测试：验证基类实现与上下文生命周期行为
章节来源