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

459 lines
27 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 生成器抽象层
<cite>
**本文引用的文件**
- [GenerateEnumExtensionsAttribute.cs](file://GFramework.SourceGenerators.Abstractions/enums/GenerateEnumExtensionsAttribute.cs)
- [LogAttribute.cs](file://GFramework.SourceGenerators.Abstractions/logging/LogAttribute.cs)
- [ContextAwareAttribute.cs](file://GFramework.SourceGenerators.Abstractions/rule/ContextAwareAttribute.cs)
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs)
- [AttributeEnumGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeEnumGeneratorBase.cs)
- [MetadataAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/MetadataAttributeClassGeneratorBase.cs)
- [TypeAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/TypeAttributeClassGeneratorBase.cs)
- [INamedTypeSymbolExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/INamedTypeSymbolExtensions.cs)
- [AttributeDataExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/AttributeDataExtensions.cs)
- [CommonDiagnostics.cs](file://GFramework.SourceGenerators.Common/diagnostics/CommonDiagnostics.cs)
- [ContextAwareDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/ContextAwareDiagnostic.cs)
- [LoggerDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/LoggerDiagnostic.cs)
- [EnumExtensionsGenerator.cs](file://GFramework.SourceGenerators/enums/EnumExtensionsGenerator.cs)
- [LoggerGenerator.cs](file://GFramework.SourceGenerators/logging/LoggerGenerator.cs)
- [ContextAwareGenerator.cs](file://GFramework.SourceGenerators/rule/ContextAwareGenerator.cs)
- [GenericInfo.cs](file://GFramework.SourceGenerators.Common/info/GenericInfo.cs)
- [PathContests.cs](file://GFramework.SourceGenerators.Common/constants/PathContests.cs)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向“生成器抽象层”的设计与实现，系统化阐述其设计理念、架构模式与扩展方式。抽象层通过统一的增量生成器基类、属性解析策略与通用工具类，屏蔽不同生成器之间的重复逻辑，降低维护成本并提升可复用性。同时，文档详细解释以下关键要素：
- 属性定义：LogAttribute、ContextAwareAttribute、GenerateEnumExtensionsAttribute 的用途与行为
- 基类体系：AttributeClassGeneratorBase、AttributeEnumGeneratorBase、MetadataAttributeClassGeneratorBase、TypeAttributeClassGeneratorBase 的职责与继承关系
- 工具类组织：INamedTypeSymbolExtensions、AttributeDataExtensions 的扩展能力
- 诊断与错误处理：通用诊断与各生成器专用诊断
- 扩展指南：如何基于抽象层开发自定义生成器
## 项目结构
生成器抽象层位于独立的 NuGet 包中，主要由三部分组成：
- 抽象属性层：定义可被生成器识别的标注属性
- 通用生成器基类层：提供增量生成器的通用流程与校验
- 通用工具与诊断层：提供符号与特性解析的扩展方法以及诊断描述符
```mermaid
graph TB
subgraph "抽象属性层"
A1["LogAttribute.cs"]
A2["ContextAwareAttribute.cs"]
A3["GenerateEnumExtensionsAttribute.cs"]
end
subgraph "通用生成器基类层"
B1["AttributeClassGeneratorBase.cs"]
B2["AttributeEnumGeneratorBase.cs"]
B3["MetadataAttributeClassGeneratorBase.cs"]
B4["TypeAttributeClassGeneratorBase.cs"]
end
subgraph "通用工具与诊断层"
C1["INamedTypeSymbolExtensions.cs"]
C2["AttributeDataExtensions.cs"]
C3["CommonDiagnostics.cs"]
C4["ContextAwareDiagnostic.cs"]
C5["LoggerDiagnostic.cs"]
C6["GenericInfo.cs"]
C7["PathContests.cs"]
end
subgraph "具体生成器实现"
D1["LoggerGenerator.cs"]
D2["ContextAwareGenerator.cs"]
D3["EnumExtensionsGenerator.cs"]
end
A1 --> B4
A2 --> B3
A3 --> B2
B1 --> C1
B1 --> C2
B1 --> C3
B2 --> C1
B2 --> C2
B2 --> C3
B3 --> B1
B4 --> B1
D1 --> B4
D2 --> B3
D3 --> B2
C7 --> D1
C7 --> D2
C7 --> D3
```
图表来源
- [LogAttribute.cs](file://GFramework.SourceGenerators.Abstractions/logging/LogAttribute.cs#L1-L40)
- [ContextAwareAttribute.cs](file://GFramework.SourceGenerators.Abstractions/rule/ContextAwareAttribute.cs#L1-L11)
- [GenerateEnumExtensionsAttribute.cs](file://GFramework.SourceGenerators.Abstractions/enums/GenerateEnumExtensionsAttribute.cs#L1-L20)
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L1-L175)
- [AttributeEnumGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeEnumGeneratorBase.cs#L1-L104)
- [MetadataAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/MetadataAttributeClassGeneratorBase.cs#L1-L41)
- [TypeAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/TypeAttributeClassGeneratorBase.cs#L1-L35)
- [INamedTypeSymbolExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/INamedTypeSymbolExtensions.cs#L1-L108)
- [AttributeDataExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/AttributeDataExtensions.cs#L1-L47)
- [CommonDiagnostics.cs](file://GFramework.SourceGenerators.Common/diagnostics/CommonDiagnostics.cs#L1-L60)
- [ContextAwareDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/ContextAwareDiagnostic.cs#L1-L21)
- [LoggerDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/LoggerDiagnostic.cs#L1-L21)
- [GenericInfo.cs](file://GFramework.SourceGenerators.Common/info/GenericInfo.cs#L1-L13)
- [PathContests.cs](file://GFramework.SourceGenerators.Common/constants/PathContests.cs#L1-L42)
- [LoggerGenerator.cs](file://GFramework.SourceGenerators/logging/LoggerGenerator.cs#L1-L103)
- [ContextAwareGenerator.cs](file://GFramework.SourceGenerators/rule/ContextAwareGenerator.cs#L1-L234)
- [EnumExtensionsGenerator.cs](file://GFramework.SourceGenerators/enums/EnumExtensionsGenerator.cs#L1-L114)
章节来源
- [LogAttribute.cs](file://GFramework.SourceGenerators.Abstractions/logging/LogAttribute.cs#L1-L40)
- [ContextAwareAttribute.cs](file://GFramework.SourceGenerators.Abstractions/rule/ContextAwareAttribute.cs#L1-L11)
- [GenerateEnumExtensionsAttribute.cs](file://GFramework.SourceGenerators.Abstractions/enums/GenerateEnumExtensionsAttribute.cs#L1-L20)
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L1-L175)
- [AttributeEnumGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeEnumGeneratorBase.cs#L1-L104)
- [MetadataAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/MetadataAttributeClassGeneratorBase.cs#L1-L41)
- [TypeAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/TypeAttributeClassGeneratorBase.cs#L1-L35)
- [INamedTypeSymbolExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/INamedTypeSymbolExtensions.cs#L1-L108)
- [AttributeDataExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/AttributeDataExtensions.cs#L1-L47)
- [CommonDiagnostics.cs](file://GFramework.SourceGenerators.Common/diagnostics/CommonDiagnostics.cs#L1-L60)
- [ContextAwareDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/ContextAwareDiagnostic.cs#L1-L21)
- [LoggerDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/LoggerDiagnostic.cs#L1-L21)
- [GenericInfo.cs](file://GFramework.SourceGenerators.Common/info/GenericInfo.cs#L1-L13)
- [PathContests.cs](file://GFramework.SourceGenerators.Common/constants/PathContests.cs#L1-L42)
- [LoggerGenerator.cs](file://GFramework.SourceGenerators/logging/LoggerGenerator.cs#L1-L103)
- [ContextAwareGenerator.cs](file://GFramework.SourceGenerators/rule/ContextAwareGenerator.cs#L1-L234)
- [EnumExtensionsGenerator.cs](file://GFramework.SourceGenerators/enums/EnumExtensionsGenerator.cs#L1-L114)
## 核心组件
- 抽象属性层
- LogAttribute：为带标注的类生成日志记录器字段，支持命名、静态、访问修饰符等配置
- ContextAwareAttribute：标记类需自动实现 IContextAware 接口
- GenerateEnumExtensionsAttribute：为枚举生成扩展方法（IsX 与 IsIn）
- 通用生成器基类层
- AttributeClassGeneratorBase：面向“类+属性”的增量生成器基类，负责候选收集、属性解析、类校验、生成与输出
- AttributeEnumGeneratorBase：面向“枚举+属性”的增量生成器基类，负责候选收集、属性解析、符号校验、生成与输出
- MetadataAttributeClassGeneratorBase：基于特性元数据名称解析属性
- TypeAttributeClassGeneratorBase：基于特性类型全名解析属性
- 通用工具与诊断层
- INamedTypeSymbolExtensions：类型解析（类型种类、泛型参数与约束、完整类名、命名空间）
- AttributeDataExtensions：特性参数读取（命名参数、构造函数首个字符串参数）
- CommonDiagnostics：通用诊断描述符与跟踪输出
- 各生成器专用诊断：ContextAwareDiagnostic、LoggerDiagnostic
- 具体生成器实现
- LoggerGenerator：基于 LogAttribute 自动生成日志字段
- ContextAwareGenerator：基于 ContextAwareAttribute 自动生成 IContextAware 实现
- EnumExtensionsGenerator：基于 GenerateEnumExtensionsAttribute 生成枚举扩展方法
章节来源
- [LogAttribute.cs](file://GFramework.SourceGenerators.Abstractions/logging/LogAttribute.cs#L1-L40)
- [ContextAwareAttribute.cs](file://GFramework.SourceGenerators.Abstractions/rule/ContextAwareAttribute.cs#L1-L11)
- [GenerateEnumExtensionsAttribute.cs](file://GFramework.SourceGenerators.Abstractions/enums/GenerateEnumExtensionsAttribute.cs#L1-L20)
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L1-L175)
- [AttributeEnumGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeEnumGeneratorBase.cs#L1-L104)
- [MetadataAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/MetadataAttributeClassGeneratorBase.cs#L1-L41)
- [TypeAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/TypeAttributeClassGeneratorBase.cs#L1-L35)
- [INamedTypeSymbolExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/INamedTypeSymbolExtensions.cs#L1-L108)
- [AttributeDataExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/AttributeDataExtensions.cs#L1-L47)
- [CommonDiagnostics.cs](file://GFramework.SourceGenerators.Common/diagnostics/CommonDiagnostics.cs#L1-L60)
- [ContextAwareDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/ContextAwareDiagnostic.cs#L1-L21)
- [LoggerDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/LoggerDiagnostic.cs#L1-L21)
- [LoggerGenerator.cs](file://GFramework.SourceGenerators/logging/LoggerGenerator.cs#L1-L103)
- [ContextAwareGenerator.cs](file://GFramework.SourceGenerators/rule/ContextAwareGenerator.cs#L1-L234)
- [EnumExtensionsGenerator.cs](file://GFramework.SourceGenerators/enums/EnumExtensionsGenerator.cs#L1-L114)
## 架构总览
抽象层采用“基类 + 扩展方法 + 诊断系统”的组合架构，通过 IIncrementalGenerator 的统一入口，将不同生成器的差异化逻辑下沉至子类，从而实现高内聚、低耦合与强复用。
```mermaid
classDiagram
class AttributeClassGeneratorBase {
<<abstract>>
+Initialize(context)
#ResolveAttribute(compilation, symbol) AttributeData?
#ValidateSymbol(...)
#Generate(...)
#GetHintName(symbol) string
#ReportClassMustBePartial(...)
}
class AttributeEnumGeneratorBase {
<<abstract>>
+Initialize(context)
#ResolveAttribute(compilation, symbol) AttributeData?
#ValidateSymbol(...)
#Generate(...)
#GetHintName(symbol) string
}
class MetadataAttributeClassGeneratorBase {
<<abstract>>
#AttributeMetadataName string
#ResolveAttribute(compilation, symbol) AttributeData?
}
class TypeAttributeClassGeneratorBase {
<<abstract>>
#AttributeType Type
#ResolveAttribute(compilation, symbol) AttributeData?
}
class LoggerGenerator {
+[Generator]
#AttributeType Type
#AttributeShortNameWithoutSuffix string
#ValidateSymbol(...)
#Generate(...)
#GetHintName(symbol) string
}
class ContextAwareGenerator {
+[Generator]
#AttributeMetadataName string
#AttributeShortNameWithoutSuffix string
#ValidateSymbol(...)
#Generate(...)
#GetHintName(symbol) string
}
class EnumExtensionsGenerator {
+[Generator]
#AttributeShortNameWithoutSuffix string
#ResolveAttribute(...)
#ValidateSymbol(...)
#Generate(...)
#GetHintName(symbol) string
}
AttributeClassGeneratorBase <|-- MetadataAttributeClassGeneratorBase
AttributeClassGeneratorBase <|-- TypeAttributeClassGeneratorBase
AttributeClassGeneratorBase <|-- LoggerGenerator
AttributeClassGeneratorBase <|-- ContextAwareGenerator
AttributeEnumGeneratorBase <|-- EnumExtensionsGenerator
```
图表来源
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L1-L175)
- [AttributeEnumGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeEnumGeneratorBase.cs#L1-L104)
- [MetadataAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/MetadataAttributeClassGeneratorBase.cs#L1-L41)
- [TypeAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/TypeAttributeClassGeneratorBase.cs#L1-L35)
- [LoggerGenerator.cs](file://GFramework.SourceGenerators/logging/LoggerGenerator.cs#L1-L103)
- [ContextAwareGenerator.cs](file://GFramework.SourceGenerators/rule/ContextAwareGenerator.cs#L1-L234)
- [EnumExtensionsGenerator.cs](file://GFramework.SourceGenerators/enums/EnumExtensionsGenerator.cs#L1-L114)
## 详细组件分析
### 抽象属性定义与作用
- LogAttribute
- 作用：为类生成日志记录器字段，支持命名、静态、访问修饰符等配置
- 关键属性：Name、FieldName、IsStatic、AccessModifier
- ContextAwareAttribute
- 作用：标记类需自动实现 IContextAware 接口
- GenerateEnumExtensionsAttribute
- 作用：为枚举生成扩展方法，支持 IsX 与 IsIn 两种生成选项
章节来源
- [LogAttribute.cs](file://GFramework.SourceGenerators.Abstractions/logging/LogAttribute.cs#L1-L40)
- [ContextAwareAttribute.cs](file://GFramework.SourceGenerators.Abstractions/rule/ContextAwareAttribute.cs#L1-L11)
- [GenerateEnumExtensionsAttribute.cs](file://GFramework.SourceGenerators.Abstractions/enums/GenerateEnumExtensionsAttribute.cs#L1-L20)
### 基类功能与继承关系
- AttributeClassGeneratorBase
- 负责：候选类收集、属性解析、类校验（如 partial）、生成与输出
- 关键抽象：ResolveAttribute、ValidateSymbol、Generate、GetHintName
- AttributeEnumGeneratorBase
- 负责：候选枚举收集、属性解析、符号校验、生成与输出
- 关键抽象：ResolveAttribute、ValidateSymbol、Generate、GetHintName
- MetadataAttributeClassGeneratorBase
- 基于特性元数据名称解析属性，便于跨包引用
- TypeAttributeClassGeneratorBase
- 基于特性类型全名解析属性，适用于本地特性
章节来源
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L1-L175)
- [AttributeEnumGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeEnumGeneratorBase.cs#L1-L104)
- [MetadataAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/MetadataAttributeClassGeneratorBase.cs#L1-L41)
- [TypeAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/TypeAttributeClassGeneratorBase.cs#L1-L35)
### 通用工具类
- INamedTypeSymbolExtensions
- 类型种类解析：根据 TypeKind 返回 "class"/"struct"/"record"
- 泛型解析：提取泛型参数与约束，返回 GenericInfo
- 名称解析：GetFullClassName、GetNamespace
- AttributeDataExtensions
- GetNamedArgument：按名称读取特性命名参数，支持默认值
- GetFirstCtorString：读取特性构造函数首个参数（字符串）
章节来源
- [INamedTypeSymbolExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/INamedTypeSymbolExtensions.cs#L1-L108)
- [AttributeDataExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/AttributeDataExtensions.cs#L1-L47)
- [GenericInfo.cs](file://GFramework.SourceGenerators.Common/info/GenericInfo.cs#L1-L13)
### 诊断系统与错误处理
- CommonDiagnostics
- ClassMustBePartial：类必须为 partial 的错误
- GeneratorTrace：生成器跟踪信息
- ContextAwareDiagnostic
- ContextAwareOnlyForClass：ContextAwareAttribute 仅能用于类
- LoggerDiagnostic
- LogAttributeInvalid：LogAttribute 无效的警告
章节来源
- [CommonDiagnostics.cs](file://GFramework.SourceGenerators.Common/diagnostics/CommonDiagnostics.cs#L1-L60)
- [ContextAwareDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/ContextAwareDiagnostic.cs#L1-L21)
- [LoggerDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/LoggerDiagnostic.cs#L1-L21)
### 具体生成器工作流
- LoggerGenerator
- 使用 TypeAttributeClassGeneratorBase，基于 LogAttribute 生成日志字段
- 通过 INamedTypeSymbolExtensions 与 AttributeDataExtensions 完成类型与参数解析
- ContextAwareGenerator
- 使用 MetadataAttributeClassGeneratorBase，基于 ContextAwareAttribute 元数据生成 IContextAware 实现
- 通过编译期接口符号生成显式接口实现
- EnumExtensionsGenerator
- 使用 AttributeEnumGeneratorBase，基于 GenerateEnumExtensionsAttribute 生成枚举扩展方法
```mermaid
sequenceDiagram
participant IDE as "IDE/MSBuild"
participant Gen as "增量生成器"
participant Base as "AttributeClassGeneratorBase"
participant Impl as "具体生成器"
participant Ext as "扩展方法"
participant Out as "生成源文件"
IDE->>Gen : 触发增量生成
Gen->>Base : Initialize(context)
Base->>Impl : ResolveAttribute(compilation, symbol)
Impl-->>Base : AttributeData
Base->>Base : ValidateSymbol(...)
alt 校验失败
Base-->>IDE : 报告诊断
else 校验成功
Base->>Impl : Generate(context, compilation, symbol, attr)
Impl->>Ext : 使用扩展方法解析参数/类型
Impl-->>Out : 返回生成源代码
Base-->>IDE : AddSource(hintName, source)
end
```
图表来源
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L1-L175)
- [LoggerGenerator.cs](file://GFramework.SourceGenerators/logging/LoggerGenerator.cs#L1-L103)
- [ContextAwareGenerator.cs](file://GFramework.SourceGenerators/rule/ContextAwareGenerator.cs#L1-L234)
- [EnumExtensionsGenerator.cs](file://GFramework.SourceGenerators/enums/EnumExtensionsGenerator.cs#L1-L114)
- [INamedTypeSymbolExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/INamedTypeSymbolExtensions.cs#L1-L108)
- [AttributeDataExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/AttributeDataExtensions.cs#L1-L47)
## 依赖分析
- 命名空间与路径常量
- PathContests 统一管理 GFramework 基础命名空间、核心抽象层命名空间与源码生成器抽象层命名空间
- 生成器与基类的依赖
- 具体生成器均继承自通用基类，复用候选收集、属性解析与输出流程
- 诊断与工具的依赖
- 通用基类依赖 CommonDiagnostics；具体生成器可叠加专用诊断
- 生成器广泛使用 INamedTypeSymbolExtensions 与 AttributeDataExtensions
```mermaid
graph LR
P["PathContests.cs"] --> LG["LoggerGenerator.cs"]
P --> CG["ContextAwareGenerator.cs"]
P --> EG["EnumExtensionsGenerator.cs"]
ACGB["AttributeClassGeneratorBase.cs"] --> LG
ACGB --> CG
AECB["AttributeEnumGeneratorBase.cs"] --> EG
MABCGB["MetadataAttributeClassGeneratorBase.cs"] --> CG
TABCGB["TypeAttributeClassGeneratorBase.cs"] --> LG
INSE["INamedTypeSymbolExtensions.cs"] --> LG
INSE --> CG
INSE --> EG
ADEC["AttributeDataExtensions.cs"] --> LG
ADEC --> CG
ADEC --> EG
CD["CommonDiagnostics.cs"] --> ACGB
CAD["ContextAwareDiagnostic.cs"] --> CG
LDI["LoggerDiagnostic.cs"] --> LG
```
图表来源
- [PathContests.cs](file://GFramework.SourceGenerators.Common/constants/PathContests.cs#L1-L42)
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L1-L175)
- [AttributeEnumGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeEnumGeneratorBase.cs#L1-L104)
- [MetadataAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/MetadataAttributeClassGeneratorBase.cs#L1-L41)
- [TypeAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/TypeAttributeClassGeneratorBase.cs#L1-L35)
- [INamedTypeSymbolExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/INamedTypeSymbolExtensions.cs#L1-L108)
- [AttributeDataExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/AttributeDataExtensions.cs#L1-L47)
- [CommonDiagnostics.cs](file://GFramework.SourceGenerators.Common/diagnostics/CommonDiagnostics.cs#L1-L60)
- [ContextAwareDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/ContextAwareDiagnostic.cs#L1-L21)
- [LoggerDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/LoggerDiagnostic.cs#L1-L21)
- [LoggerGenerator.cs](file://GFramework.SourceGenerators/logging/LoggerGenerator.cs#L1-L103)
- [ContextAwareGenerator.cs](file://GFramework.SourceGenerators/rule/ContextAwareGenerator.cs#L1-L234)
- [EnumExtensionsGenerator.cs](file://GFramework.SourceGenerators/enums/EnumExtensionsGenerator.cs#L1-L114)
章节来源
- [PathContests.cs](file://GFramework.SourceGenerators.Common/constants/PathContests.cs#L1-L42)
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L1-L175)
- [AttributeEnumGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeEnumGeneratorBase.cs#L1-L104)
- [MetadataAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/MetadataAttributeClassGeneratorBase.cs#L1-L41)
- [TypeAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/TypeAttributeClassGeneratorBase.cs#L1-L35)
- [INamedTypeSymbolExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/INamedTypeSymbolExtensions.cs#L1-L108)
- [AttributeDataExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/AttributeDataExtensions.cs#L1-L47)
- [CommonDiagnostics.cs](file://GFramework.SourceGenerators.Common/diagnostics/CommonDiagnostics.cs#L1-L60)
- [ContextAwareDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/ContextAwareDiagnostic.cs#L1-L21)
- [LoggerDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/LoggerDiagnostic.cs#L1-L21)
- [LoggerGenerator.cs](file://GFramework.SourceGenerators/logging/LoggerGenerator.cs#L1-L103)
- [ContextAwareGenerator.cs](file://GFramework.SourceGenerators/rule/ContextAwareGenerator.cs#L1-L234)
- [EnumExtensionsGenerator.cs](file://GFramework.SourceGenerators/enums/EnumExtensionsGenerator.cs#L1-L114)
## 性能考虑
- 增量生成：基类通过 IncrementalGeneratorInitializationContext 与 Combine/CombineLatest 实现增量输入，避免全量扫描
- 早期短路：在 ResolveAttribute 失败、ValidateSymbol 失败时尽早返回，减少不必要的生成开销
- 语法筛选：先用简单的 Name.Contains 快速过滤候选，再做语义解析，降低 Roslyn 解析压力
- 生成内容最小化：仅生成必要代码与注释，避免冗余空行与无意义片段
## 故障排查指南
- 类必须为 partial
- 现象：编译报错“Class 'X' must be declared partial for code generation”
- 处理：将目标类声明为 partial
- ContextAwareAttribute 仅能用于类
- 现象：编译报错“ContextAwareAttribute can only be applied to class 'X'”
- 处理：确保标注在 class 上
- LogAttribute 无效
- 现象：编译警告“LogAttribute on class 'X' is ineffective: ...”
- 处理：检查特性参数与类可见性，确认生成器可用性
- 生成器跟踪
- 使用 CommonDiagnostics.Trace 输出生成器内部流程信息，辅助定位问题
章节来源
- [CommonDiagnostics.cs](file://GFramework.SourceGenerators.Common/diagnostics/CommonDiagnostics.cs#L1-L60)
- [ContextAwareDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/ContextAwareDiagnostic.cs#L1-L21)
- [LoggerDiagnostic.cs](file://GFramework.SourceGenerators/diagnostics/LoggerDiagnostic.cs#L1-L21)
- [AttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeClassGeneratorBase.cs#L1-L175)
## 结论
生成器抽象层通过“基类 + 扩展方法 + 诊断系统”的组合，实现了对不同生成场景的统一抽象与高效复用。它将通用流程（候选收集、属性解析、校验、生成、输出）下沉至基类，将差异化逻辑（属性解析策略、生成模板）下沉至子类，既保证了可维护性，也降低了学习与扩展成本。借助 INamedTypeSymbolExtensions 与 AttributeDataExtensions，生成器能够稳定地解析复杂类型与特性参数；借助诊断系统，开发者可以快速定位问题并优化生成行为。
## 附录
### 扩展指南：开发自定义生成器
- 选择基类
- 若特性来自外部包或需跨包引用：继承 MetadataAttributeClassGeneratorBase，并提供 AttributeMetadataName
- 若特性来自本地项目：继承 TypeAttributeClassGeneratorBase，并提供 AttributeType
- 若处理枚举：继承 AttributeEnumGeneratorBase
- 实现抽象方法
- ResolveAttribute：解析目标特性数据
- ValidateSymbol：执行必要的符号与上下文校验
- Generate：生成源代码字符串
- GetHintName：自定义生成文件名
- 使用工具与诊断
- 使用 INamedTypeSymbolExtensions 与 AttributeDataExtensions 简化类型与参数解析
- 使用 CommonDiagnostics 输出跟踪信息，必要时叠加专用诊断
- 路径常量
- 使用 PathContests 中的命名空间常量，确保生成代码引用正确
章节来源
- [MetadataAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/MetadataAttributeClassGeneratorBase.cs#L1-L41)
- [TypeAttributeClassGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/TypeAttributeClassGeneratorBase.cs#L1-L35)
- [AttributeEnumGeneratorBase.cs](file://GFramework.SourceGenerators.Common/generator/AttributeEnumGeneratorBase.cs#L1-L104)
- [INamedTypeSymbolExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/INamedTypeSymbolExtensions.cs#L1-L108)
- [AttributeDataExtensions.cs](file://GFramework.SourceGenerators.Common/extensions/AttributeDataExtensions.cs#L1-L47)
- [CommonDiagnostics.cs](file://GFramework.SourceGenerators.Common/diagnostics/CommonDiagnostics.cs#L1-L60)
- [PathContests.cs](file://GFramework.SourceGenerators.Common/constants/PathContests.cs#L1-L42)
Reference in New Issue View Git Blame Copy Permalink