gewuyou/GFramework
1
0
Fork 0
mirror of https://github.com/GeWuYou/GFramework.git synced 2026-03-26 06:16:43 +08:00
Code Issues Packages Projects Releases Wiki Activity
GFramework/.qoder/repowiki/zh/content/源代码生成器/通用源代码生成器/诊断系统.md
GeWuYou a79f02c987 docs(api): 添加 Core API 参考文档与事件系统接口文档 
- 新增 Core API 参考文档，涵盖架构与模块、数据模型与系统、命令与查询等核心组件
- 添加事件系统接口详细文档，包括 IEvent、IEventBus、IUnRegister 等接口说明
- 提供完整的 API 使用示例路径、最佳实践与性能建议
- 包含架构图、依赖关系图与故障排查指南
- 添加测试用例参考与扩展方法说明
- [skip ci]
2026-01-21 23:45:10 +08:00

18 KiB
Raw Blame History

诊断系统

**本文引用的文件** - [GFramework.SourceGenerators\diagnostics\LoggerDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/LoggerDiagnostic.cs) - [GFramework.SourceGenerators\diagnostics\ContextAwareDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/ContextAwareDiagnostic.cs) - [GFramework.SourceGenerators.Common\diagnostics\CommonDiagnostics.cs](file://GFramework.SourceGenerators.Common/diagnostics/CommonDiagnostics.cs) - [GFramework.SourceGenerators.Common\constants\PathContests.cs](file://GFramework.SourceGenerators.Common/constants/PathContests.cs) - [GFramework.SourceGenerators.Common\generator\MetadataAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/MetadataAttributeClassGeneratorBase.cs) - [GFramework.SourceGenerators.Common\extensions\INamedTypeSymbolExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/INamedTypeSymbolExtensions.cs) - [GFramework.SourceGenerators\logging\LoggerGenerator.cs](file://GFramework.SourceGenerators/logging/LoggerGenerator.cs) - [GFramework.SourceGenerators\rule\ContextAwareGenerator.cs](file://GFramework.SourceGenerators/rule/ContextAwareGenerator.cs) - [GFramework.SourceGenerators.Abstractions\logging\LogAttribute.cs](file://GFramework.SourceGenerators.Abstractions/logging/LogAttribute.cs) - [GFramework.SourceGenerators.Abstractions\rule\ContextAwareAttribute.cs](file://GFramework.SourceGenerators.Abstractions/rule/ContextAwareAttribute.cs) - [GFramework.SourceGenerators\README.md](file://GFramework.SourceGenerators/README.md) - [GFramework.SourceGenerators.Tests\rule\ContextAwareGeneratorSnapshotTests.cs](file://GFramework.SourceGenerators.Tests/rule/ContextAwareGeneratorSnapshotTests.cs) - [GFramework.SourceGenerators.Tests\logging\LoggerGeneratorSnapshotTests.cs](file://GFramework.SourceGenerators.Tests/logging/LoggerGeneratorSnapshotTests.cs)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排除指南
  9. 结论
  10. 附录

简介

本文件面向 GFramework 源代码生成器的诊断系统，系统性阐述诊断机制、错误码定义、诊断信息收集与报告流程，以及如何通过诊断改进代码质量与开发体验。重点覆盖以下内容：

  • LoggerDiagnostic 与 ContextAwareDiagnostic 的错误检测机制与报告流程
  • CommonDiagnostics 提供的通用诊断能力与错误码
  • 诊断信息在编译时的收集、分析与报告过程
  • 诊断系统的配置与自定义方法
  • 常见诊断场景与解决方案
  • 调试生成器问题的技巧与工具
  • 最佳实践与故障排除指南

项目结构

诊断系统主要分布在三个层次：

  • 生成器层：负责在编译时扫描特性、生成代码，并在必要时报告诊断
  • 诊断描述符层：集中定义各类诊断的 ID、消息、分类与严重级别
  • 通用基础设施层：提供路径常量、元数据解析、符号扩展等支撑
graph TB
subgraph "生成器层"
LG["LoggerGenerator<br/>日志生成器"]
CG["ContextAwareGenerator<br/>上下文感知生成器"]
end
subgraph "诊断描述符层"
LD["LoggerDiagnostics<br/>日志诊断"]
CD["ContextAwareDiagnostic<br/>上下文诊断"]
GD["CommonDiagnostics<br/>通用诊断"]
end
subgraph "通用基础设施层"
PAC["PathContests<br/>路径常量"]
MAB["MetadataAttributeClassGeneratorBase<br/>元数据特性基类"]
ISE["INamedTypeSymbolExtensions<br/>符号扩展"]
end
LG --> LD
LG --> GD
CG --> CD
CG --> GD
CG --> PAC
LG --> PAC
CG --> MAB
LG --> ISE

图表来源

章节来源

核心组件

  • LoggerDiagnostics：定义日志生成器相关的诊断描述符，例如日志字段无效或冲突等情况
  • ContextAwareDiagnostic：定义上下文感知生成器相关的诊断描述符，例如特性应用目标非法
  • CommonDiagnostics：提供通用诊断描述符与跟踪方法，如“类必须为 partial”“生成器跟踪信息”
  • LoggerGenerator：扫描带 Log 特性的类，生成日志字段；可结合诊断描述符进行语义校验
  • ContextAwareGenerator：扫描带 ContextAware 特性的类，生成 IContextAware 实现；包含严格的类与 partial 校验
  • 路径常量 PathContests：统一管理命名空间与路径，便于生成器与诊断共享
  • 元数据特性基类 MetadataAttributeClassGeneratorBase：按元数据名称解析特性，简化生成器实现
  • 符号扩展 INamedTypeSymbolExtensions：提供类型关键字、泛型参数与约束、完整类名、命名空间等解析

章节来源

架构总览

诊断系统围绕“特性扫描—语义校验—生成代码—报告诊断”的闭环工作。生成器在编译时解析特性，执行必要的语义校验，生成目标代码，并在发现异常时通过诊断描述符向 IDE/构建反馈。

sequenceDiagram
participant C as "编译器"
participant LG as "LoggerGenerator"
participant CG as "ContextAwareGenerator"
participant CD as "ContextAwareDiagnostic"
participant GD as "CommonDiagnostics"
C->>LG : 扫描带 Log 特性的类
LG->>LG : 解析属性参数与符号
LG->>LG : 生成日志字段代码
LG-->>C : 输出生成文件
C->>CG : 扫描带 ContextAware 特性的类
CG->>CG : 校验 partial 与类型
alt 校验失败
CG->>CD : 报告上下文诊断
end
CG->>CG : 校验类是否已实现接口
alt 已实现接口
CG->>GD : 报告“类必须为 partial”等通用诊断
end
CG->>CG : 生成 IContextAware 实现
CG-->>C : 输出生成文件

图表来源

详细组件分析

LoggerDiagnostics 与 LoggerGenerator

  • LoggerDiagnostics 定义了日志相关的诊断描述符，用于提示日志生成器无法生成有效日志字段的情况
  • LoggerGenerator 负责扫描带 Log 特性的类，解析属性参数（如字段名、访问修饰符、是否静态），并生成日志字段代码
  • 生成器通过符号扩展与路径常量，确保生成的命名空间、类型关键字与泛型约束正确
classDiagram
class LoggerDiagnostics {
+DiagnosticDescriptor LogAttributeInvalid
}
class LoggerGenerator {
+AttributeType : Type
+AttributeShortNameWithoutSuffix : string
+ValidateSymbol(...)
+Generate(...)
+GetHintName(...)
}
class LogAttribute {
+string Name
+string FieldName
+bool IsStatic
+string AccessModifier
}
LoggerGenerator --> LoggerDiagnostics : "使用诊断描述符"
LoggerGenerator --> LogAttribute : "解析特性参数"

图表来源

章节来源

ContextAwareDiagnostic 与 ContextAwareGenerator

  • ContextAwareDiagnostic 定义了上下文感知相关的诊断描述符，例如特性仅能应用于类
  • ContextAwareGenerator 执行严格校验：要求类必须为 partial、必须为 class 类型；若类已实现 IContextAware 接口，则报告通用诊断
  • 生成器通过元数据特性基类按特性元数据名称解析特性，再生成显式接口实现
flowchart TD
Start(["开始"]) --> CheckPartial["检查是否为 partial 类"]
CheckPartial --> PartialOk{"是 partial 吗？"}
PartialOk --> |否| ReportPartial["报告通用诊断：类必须为 partial"]
PartialOk --> |是| CheckType["检查类型是否为 class"]
CheckType --> TypeOk{"是 class 吗？"}
TypeOk --> |否| ReportType["报告上下文诊断：仅能应用于类"]
TypeOk --> |是| CheckInterface["检查是否已实现 IContextAware"]
CheckInterface --> Implemented{"已实现接口？"}
Implemented --> |是| ReportConflict["报告通用诊断：类已实现接口"]
Implemented --> |否| GenerateCode["生成 IContextAware 实现"]
ReportPartial --> End(["结束"])
ReportType --> End
ReportConflict --> End
GenerateCode --> End

图表来源

章节来源

CommonDiagnostics 与通用诊断能力

  • ClassMustBePartial：当类未声明为 partial 时，报告错误级别的诊断
  • GeneratorTrace：提供 Info 级别的跟踪信息，便于调试生成器行为
  • Trace 方法：在生成过程中输出跟踪信息，辅助定位问题
classDiagram
class CommonDiagnostics {
+DiagnosticDescriptor ClassMustBePartial
+DiagnosticDescriptor GeneratorTrace
+Trace(context, message)
}

图表来源

章节来源

路径常量与元数据解析

  • PathContests：集中定义命名空间常量，确保生成器与诊断共享一致的命名空间
  • MetadataAttributeClassGeneratorBase：按特性元数据名称解析特性，简化生成器实现
  • INamedTypeSymbolExtensions：提供类型关键字、泛型参数与约束、完整类名、命名空间等解析能力

章节来源

依赖关系分析

  • 生成器依赖诊断描述符与通用基础设施
  • ContextAwareGenerator 依赖上下文诊断与通用诊断
  • LoggerGenerator 依赖通用诊断与符号扩展
  • 两者均依赖路径常量与元数据解析基类
graph LR
LG["LoggerGenerator"] --> GD["CommonDiagnostics"]
LG --> ISE["INamedTypeSymbolExtensions"]
CG["ContextAwareGenerator"] --> CD["ContextAwareDiagnostic"]
CG --> GD
CG --> PAC["PathContests"]
CG --> MAB["MetadataAttributeClassGeneratorBase"]

图表来源

性能考量

  • 诊断系统在编译时运行，零运行时开销
  • 通过增量编译与合理的诊断粒度，降低构建时间
  • 生成的代码在运行时无反射或动态调用，性能接近手写代码

章节来源

故障排除指南

  • GF_Logging_001：日志字段名冲突
    • 现象：日志生成器提示字段名冲突
    • 解决：更改 Log 特性的字段名或移除冲突字段
  • GF_Rule_001：上下文感知类型非法
    • 现象：ContextAwareAttribute 应用于非类类型
    • 解决：将特性应用于 class，或移除特性
  • 通用诊断 GF_Common_Class_001：类必须为 partial
    • 现象：类未声明为 partial
    • 解决：添加 partial 关键字
  • 调试技巧
    • 使用 CommonDiagnostics.Trace 输出生成器内部状态
    • 结合快照测试验证生成器输出一致性
    • 在 IDE 中查看诊断信息，定位具体语法位置

章节来源

结论

诊断系统通过清晰的描述符定义、严格的生成器校验与可追踪的诊断输出，为 GFramework 源代码生成器提供了可靠的编译时质量保障。遵循本文的最佳实践与故障排除建议，可显著提升代码质量与开发体验。

附录

错误码与严重级别对照

  • GF_Logging_001：日志生成器相关警告
  • GF_Rule_001：上下文感知类型错误（错误）
  • GF_Common_Class_001：类必须为 partial（错误）
  • GF_Common_Trace_001：生成器跟踪信息（信息）

章节来源