SourceGenerator与partial范式：代码生成、测试策略与工程实践

这两年.NET生态里有个东西热度一直没降过——SourceGenerator。我最早接触它是为了绕开反射的性能损耗，后来发现这玩意儿一旦用对范式，能省掉大量样板代码，而且还能把一些运行时才能暴露的问题提前到编译期。但有个点一直很少有人系统讲清楚：partial关键字在SourceGenerator里到底扮演什么角色，以及这东西写完了怎么测才靠谱。

这篇文章就从我自己实际项目里的经验出发，把partial范式的来龙去脉、代码生成器的完整实现路径、以及生成代码的测试策略一次性聊透。适合已经会用一点SourceGenerator、但想更进一步理解设计思路和工程质量的人；如果你是完全没接触过的新手，我也会把前置知识点尽量讲明白。

1. 内容整体设计与思路拆解

1.1 为什么提起SourceGenerator就绕不开partial

先说一个很基础但特别容易被忽略的事实：SourceGenerator生成的所有代码，本质上都是“凭空出现在编译过程里的”，而这些代码要想和开发者手写的代码无缝拼接，唯一官方支持的机制就是partial。

很多人刚接触SourceGenerator时会有一个困惑：我明明生成了一个Foo类，为什么编译器告诉我“类型已存在”？因为你可能同时在代码里手写了一个同名Foo类。这个问题的根源就在于，你压根没打算用partial，而是试图让生成器“替代”你写代码。真正的SourceGenerator实践哲学不是替代，而是协作。

协作的方式很简单：

• 你在源文件里声明一个partial class，里面可以写一部分自己的逻辑。
• SourceGenerator在编译时往同一类型的另一个partial声明里填充代码。
• 编译器把两个partial合并为一个完整类型。

这就引出一个设计原则：你写的partial声明决定了生成器的“输入契约”，生成器负责为这个契约补齐实现。 这种模式在MVVM社区（比如ObservableProperty）里已经很成熟，但更多业务场景其实还没被充分挖掘。

1.2 从“生成代码”到“partial范式”

所谓“partial范式”，我个人理解包含三层含义：

第一层，语法层。 你生成的目标类型必须标记为partial，否则一旦开发者同名声明就死锁。这层是硬性规定，没啥好说的。

第二层，设计层。 好的生成器一定把“可变部分”和“不可变部分”拆开。不可变的是算法、模板结构、固定逻辑；可变的是每个使用方的差异点——比如字段的名字、属性的类型、要实现的接口列表。这些差异点通过partial声明暴露给生成器读取。

第三层，工程层。 项目的组织方式要配合partial范式。手写代码放一个文件，生成代码放另一个文件，通过partial拼起来，两者互相之间有一条清晰的边界，不会因为哪次重构就搅在一起。

我见过很多糟糕的SourceGenerator项目，典型特征是：生成器里硬编码了大量写死的业务字段名，耦合度极高。这其实就是没理解partial范式的精髓——你把本该由开发者通过partial声明提供的契约信息，强行写死在了生成器里。

1.3 这套设计解决了什么真实痛点

有人会问：我直接用T4模板、或者手写代码复制粘贴不也行吗？这就是理解SourceGenerator价值的关键。

先看反射方案的痛点：比如你要实现一个通知属性变更的机制，用反射来回读PropertyChanged，性能损耗是一方面，更重要的是反射方案完全丢失了编译期类型安全——写错一个字符串属性名，只有运行时才炸。

再看T4模板的痛点：T4是设计时工具，生成的代码是“一次性快照”，源模型变了，你忘了重新跑模板，生成的代码就过期了。而且T4生成的代码躺在项目里，很容易被人手动改两下，之后就再也没法自动化更新。

SourceGenerator的partial范式把这两者的优点都占了：

• 编译期执行，源模型一变，生成代码立刻同步。
• 类型安全，因为生成代码和手写代码会在编译时做严格校验。
• 没有运行时反射开销，性能为纯静态调用级别。
• 开发者可以放心地补充自己的逻辑到partial方法里，生成器不会覆盖。

这个“生成器不覆盖手写代码”的特性，恰好是partial范式最迷人的地方。

2. 核心细节解析与实操要点

2.1 生成目标怎么设计才符合partial范式

在动手写任何代码之前，先设计好你的“目标形态”。一个符合partial范式的生成目标，至少包含两部分：开发者手写侧和生成器生成侧。

拿一个我项目里的真实例子来说。我需要给一批数据传输对象实现深拷贝能力，理想的目标形态是：

csharp复制// 开发者手写侧——用户只写这个
public partial class UserInfo
{
    public string Name { get; set; }
    public int Age { get; set; }
    public AddressInfo Address { get; set; }
    public List<string> Tags { get; set; }
}

然后SourceGenerator自动生成另一半：

csharp复制// 生成器生成侧——开发者的partial类被自动补充了方法
public partial class UserInfo
{
    public UserInfo Clone()
    {
        return new UserInfo
        {
            Name = this.Name,
            Age = this.Age,
            Address = this.Address?.Clone(),
            Tags = this.Tags?.Select(t => t).ToList()
        };
    }
}

这样设计的好处是，开发者完全不需要手写拷贝逻辑，也不会被生成长代码淹没视线。但前提是，你必须在声明类时加上partial，否则生成器就算生成了代码也没地方挂载。

这里有一个关键判断：哪些逻辑适合放到生成器里，哪些逻辑应该留给开发者自己写？

我的经验是三个判断标准：

1. 机械重复度高的代码——比如逐字段赋值，适合生成。
2. 强依赖类型结构的代码——必须通过读取符号信息来推导，适合生成。
3. 需要开发者决策的代码——比如某个字段想自定义拷贝方式，必须留扩展点。

第3点最容易被人忽略。很多生成器刚开始很好用，等到用户说“我这个字段不想按默认规则处理”就傻眼了。解决方式是提前设计好partial方法扩展点，比如：

csharp复制// 生成器生成的Clone函数内部会自动调用这个partial方法
// 开发者可以选择实现它，也可以不管
partial void OnCloning(UserInfo source);

生成器负责在合适的位置调用这个钩子，开发者按需决定是否填充实现。这样既保持自动化的便利，又给了灵活性，是partial范式的高级用法。

2.2 为什么不是普通class而是partial class

这个问题如果你理解了上面的内容，其实已经有了答案。但我在社区里还是经常看到有人绕不开弯，再展开说几句。

SourceGenerator是编译时执行的，它和手写代码的“回合制互动”只有一次：它看到你写了什么，然后生成一些东西，编译器把两者合并。在这种机制下，如果生成器生成的是一个全新类型，它就无法和你手写的另一个类型共享私有状态、无法合并方法定义、无法形成真正的“一个类”的语义。

而partial从根本上解决了这个问题。它允许同一个类型跨多个文件声明，编译器负责合并。这意味着：

• 你可以把序列化逻辑、克隆逻辑、比较逻辑等多个关注点拆分到不同文件。
• 这些逻辑虽然物理上分离，但逻辑上完全属于一个类型，可以访问彼此的私有成员。
• 生成器只管生成自己负责的那部分，绝对不会碰到你手写的那部分。

反过来说，如果SourceGenerator不配合partial，它只能在你的类型外部生成一个扩展方法类或者装饰器类。扩展方法做不到访问私有状态，装饰器类做不到保持类型同一性（你拿到的还是原对象而不是装饰后对象）。partial范式是SourceGenerator能做到“无缝增强”而非“间接调用”的根本原因。

2.3 识别SourceGenerator能读懂的“契约信息”

设计好目标形态后，下一步就是让生成器知道你希望它做什么。这个“知道”的过程，靠的是读取源文件中的语法节点和语义符号。

很多新手写SourceGenerator容易犯一个错：拿正则去解析源代码文本。这是最糟糕的实践，因为源代码本质是结构化文本，正则很容易被注释、字符串字面量、命名空间等干扰，稍微复杂点的真实代码就出各种匹配问题。正确姿势是使用Roslyn的语法分析器（SyntaxTree）和语义模型（SemanticModel）。

举个例子，我想让生成器识别所有带[Cloneable]特性的partial类：

csharp复制[AttributeUsage(AttributeTargets.Class)]
public sealed class CloneableAttribute : Attribute
{
}

在生成器里，我要做这些事：

1. 遍历编译单元的语法树，找到所有的ClassDeclarationSyntax。
2. 获取这个类的INamedTypeSymbol。
3. 检查它是否带有CloneableAttribute特性。
4. 检查它是否是partial声明（如果不是，生成诊断信息报错）。
5. 遍历它的成员，收集需要处理的属性符号。
6. 把符号信息转换成生成代码所需的数据模型。

这里的第4步特别重要。如果你发现一个带[Cloneable]但没标记partial的类，不应该绕过它，而是应当向使用者报告一个编译诊断错误，提示“你需要在类声明上添加partial关键字”。这也是SourceGenerator的标准实践：宁可编译时明确失败，也不要生成了代码却不生效，让用户面对一个莫名的行为差异。

csharp复制private static bool IsPartial(ClassDeclarationSyntax classSyntax)
{
    return classSyntax.Modifiers.Any(m => m.IsKind(SyntaxKind.PartialKeyword));
}

然后，在生成器主流程里：

csharp复制foreach (var classSyntax in context.Compilation.SyntaxTrees
             .SelectMany(tree => tree.GetRoot().DescendantNodes())
             .OfType<ClassDeclarationSyntax>())
{
    var model = context.Compilation.GetSemanticModel(classSyntax.SyntaxTree);
    var symbol = model.GetDeclaredSymbol(classSyntax);
    
    if (symbol.GetAttributes().Any(a => a.AttributeClass?.Name == "CloneableAttribute"))
    {
        if (!IsPartial(classSyntax))
        {
            context.ReportDiagnostic(Diagnostic.Create(
                new DiagnosticDescriptor(
                    "GEN001",
                    "Cloneable类型必须声明为partial",
                    "类型'{0}'带有[Cloneable]特性但未标记partial",
                    "SourceGenerator",
                    DiagnosticSeverity.Error,
                    isEnabledByDefault: true),
                classSyntax.Identifier.GetLocation(),
                symbol.Name));
            continue;
        }
        
        // 执行真正的代码生成逻辑...
    }
}

这里要注意，AttributeClass?.Name == "CloneableAttribute"这种判断在生产级代码里不够严谨，更稳妥的方式是比较完全限定名，避免同名特性在不同命名空间造成的误判。更好的做法是：

csharp复制var targetAttribute = symbol.GetAttributes()
    .FirstOrDefault(a => a.AttributeClass?.ToDisplayString() == "MyLib.CloneableAttribute");

关于语义模型API，有个使用细节很容易踩坑：GetDeclaredSymbol的性能比你想的要好，但在遍历大量语法树时还是要克制，避免对每个语法节点都调用一次。先做语法层面的粗筛（比如只看类声明），再做语义层面的精判，这样能显著降低生成耗时。

3. 实操过程与核心环节实现

3.1 从零搭建一个基于partial范式的SourceGenerator项目

下面进入实战环节。我会从一个空白解决方案开始，逐步搭建一个完整的代码生成器，目标是为标记了[AutoNotify]的字段自动生成通知属性变更的事件调用代码。这其实就是社区里最经典的MVVM场景，用它来讲partial范式最直观。

先建项目结构：

bash复制MySolution/
  src/
    MyGenerator/            # SourceGenerator工程，目标框架netstandard2.0
    MyGenerator.Abstractions/  # 存放Attribute定义，供业务项目引用
    MyApp/                  # 测试使用的业务项目
  tests/
    MyGenerator.Tests/      # 生成器单元测试工程

为什么要单独建一个Abstractions项目？这是很多SourceGenerator初学者容易忽略的架构问题。你的业务代码需要引用AutoNotifyAttribute，但Attribute定义不能放在生成器项目里，因为生成器项目会被加载到编译器的独立进程（Roslyn的IsolatedAssemblyLoadContext）中，如果业务项目引用了生成器程序集，会造成编译时的类型加载冲突。

解决办法就是：把Attribute定义放到一个独立的、不引用Roslyn的普通类库里，生成器项目和业务项目都引用它即可。这个属性定义也可以反向通过编译指令把Attribute源码注入到业务项目，但那是进阶玩法，对绝大多数项目来说，一个独立Abstractions项目是最清晰可靠的选择。

定义特性：

csharp复制namespace MyGenerator.Abstractions
{
    [AttributeUsage(AttributeTargets.Field, AllowMultiple = false, Inherited = false)]
    public sealed class AutoNotifyAttribute : Attribute
    {
    }
}

3.2 实现生成器的核心逻辑

生成器项目需要引用这些NuGet包：

xml复制<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <LangVersion>latest</LangVersion>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.8.0" PrivateAssets="all" />
    <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.4" PrivateAssets="all" />
  </ItemGroup>
  
  <ItemGroup>
    <ProjectReference Include="..\MyGenerator.Abstractions\MyGenerator.Abstractions.csproj" />
  </ItemGroup>
</Project>

核心生成器逻辑如下：

csharp复制using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;
using Microsoft.CodeAnalysis.Text;
using System.Text;

namespace MyGenerator
{
    [Generator(LanguageNames.CSharp)]
    public sealed class AutoNotifyGenerator : IIncrementalGenerator
    {
        public void Initialize(IncrementalGeneratorInitializationContext context)
        {
            // 第一步：语法层面筛选出所有带AutoNotifyAttribute的字段声明
            var fieldDeclarations = context.SyntaxProvider
                .CreateSyntaxProvider(
                    predicate: static (node, _) => node is VariableDeclaratorSyntax,
                    transform: static (ctx, _) =>
                    {
                        var variableDeclarator = (VariableDeclaratorSyntax)ctx.Node;
                        var fieldSyntax = variableDeclarator.Parent as VariableDeclarationSyntax;
                        var fieldDeclarationSyntax = fieldSyntax?.Parent as FieldDeclarationSyntax;
                        
                        if (fieldDeclarationSyntax == null)
                            return default;
                            
                        // 快速判断特性是否存在（语法层面粗筛）
                        if (!fieldDeclarationSyntax.AttributeLists.Any(
                                al => al.Attributes.Any(a => a.Name.ToString().Contains("AutoNotify"))))
                            return default;
                            
                        var model = ctx.SemanticModel;
                        var fieldSymbol = model.GetDeclaredSymbol(variableDeclarator) as IFieldSymbol;
                        if (fieldSymbol == null)
                            return default;
                            
                        // 语义层面精判：确认特性真实存在
                        if (!fieldSymbol.GetAttributes().Any(
                                a => a.AttributeClass?.ToDisplayString() == "MyGenerator.Abstractions.AutoNotifyAttribute"))
                            return default;
                            
                        return fieldSymbol;
                    })
                .Where(static field => field != null);
            
            // 第二步：按包含类型进行分组，每个类型单独生成一份代码
            var typesToGenerate = fieldDeclarations
                .Select(static (field, _) =>
                {
                    var typeSymbol = field.ContainingType;
                    return new TypeToGenerate(
                        typeSymbol.ContainingNamespace.ToDisplayString(),
                        typeSymbol.Name,
                        typeSymbol.DeclaredAccessibility,
                        field.Name,
                        field.Type.ToDisplayString());
                })
                .Collect();
            
            // 第三步：注册生成逻辑
            context.RegisterSourceOutput(typesToGenerate, static (spc, typeGroups) =>
            {
                foreach (var group in typeGroups.GroupBy(t => t.Namespace + "." + t.TypeName))
                {
                    var typeInfo = group.First();
                    var memberBuilder = new StringBuilder();
                    
                    foreach (var field in group)
                    {
                        // 字段名下划线开头，去掉前缀并转PascalCase
                        var propertyName = char.ToUpper(field.FieldName[1]) + field.FieldName.Substring(2);
                        memberBuilder.AppendLine($"        public {field.FieldType} {propertyName}");
                        memberBuilder.AppendLine("        {");
                        memberBuilder.AppendLine($"            get => this.{field.FieldName};");
                        memberBuilder.AppendLine("            set");
                        memberBuilder.AppendLine("            {");
                        memberBuilder.AppendLine($"                if (!EqualityComparer<{field.FieldType}>.Default.Equals(this.{field.FieldName}, value))");
                        memberBuilder.AppendLine("                {");
                        memberBuilder.AppendLine($"                    this.{field.FieldName} = value;");
                        memberBuilder.AppendLine("                    this.OnPropertyChanged(nameof(this." + propertyName + "));");
                        memberBuilder.AppendLine("                }");
                        memberBuilder.AppendLine("            }");
                        memberBuilder.AppendLine("        }");
                        memberBuilder.AppendLine();
                    }
                    
                    var source = $@"// <auto-generated />
#nullable enable
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Runtime.CompilerServices;

namespace {typeInfo.Namespace}
{{
    public partial class {typeInfo.TypeName} : INotifyPropertyChanged
    {{
        public event PropertyChangedEventHandler? PropertyChanged;

        {memberBuilder}
        
        protected void OnPropertyChanged([CallerMemberName] string? propertyName = null)
        {{
            this.PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
        }}
    }}
}}
";
                    spc.AddSource($"{typeInfo.TypeName}.g.cs", SourceText.From(source, Encoding.UTF8));
                }
            });
        }
        
        private sealed record TypeToGenerate(
            string Namespace,
            string TypeName,
            Accessibility Accessibility,
            string FieldName,
            string FieldType);
    }
}

3.3 为什么这套实现要分“三步走”

上面的代码用了IIncrementalGenerator，这是新版Roslyn推荐的方式，代替了老的ISourceGenerator。为啥要这么做？因为增量生成器会自动做缓存和结果复用——你改一个文件，生成器不会重新跑全量，它只对受影响的部分重新计算。这在大项目里的编译体验差别非常明显。

具体到上面的三步：

• 第一步用CreateSyntaxProvider做“订阅式”的节点筛选，语法树有任何变化，Roslyn会精准定位到受影响的字段节点并重新走transform逻辑。
• 第二步用Select + Collect把每个字段映射成轻量的数据模型（TypeToGenerate），并汇集到一起。注意这里特意设计成了record，因为IIncrementalGenerator的缓存机制依赖值的相等性比较，record自动实现的值比较比手动写的类要可靠得多。
• 第三步用RegisterSourceOutput注册实际产出源代码的委托。

很多人写SourceGenerator图省事，直接在transform里拼字符串然后注册输出，结果发现改了源文件后生成结果没更新。就是因为没有正确使用增量API，Roslyn没法判断你的输出是否“过期”。把一个完整流程拆成独立的、可缓存的步骤，才算真正发挥了增量编译的优势。

有个小细节值得注意：我的TypeToGenerate里没有保存ISymbol引用，而是直接存储了字符串字段。这也是为了让缓存的值类型尽量简单——如果整个符号图都被缓存住，会让增量判断变得极其迟钝，因为任何无关代码的语义变化都可能让符号实例被标记为“已更改”。

3.4 业务项目里的partial使用方式

在业务项目里，使用方这样写：

csharp复制using MyGenerator.Abstractions;

namespace MyApp.Models
{
    public partial class Person
    {
        [AutoNotify]
        private string _name = string.Empty;

        [AutoNotify]
        private int _age;

        // 开发者自己补充的逻辑，不会被生成器影响
        public string Introduction => $"I'm {Name}, {Age} years old.";
    }
}

编译完成后，生成器自动生成一个Person.g.cs，里面的内容相当于：

csharp复制public partial class Person : INotifyPropertyChanged
{
    public event PropertyChangedEventHandler? PropertyChanged;

    public string Name
    {
        get => this._name;
        set { ... }
    }

    public int Age
    {
        get => this._age;
        set { ... }
    }

    protected void OnPropertyChanged([CallerMemberName] string? propertyName = null) { ... }
}

开发者这边最舒服的点在于：写不写partial，有没有引用生成器，用户完全是可感知的。 如果哪天想停用自动通知，直接删掉特性即可，手写代码完全不用动。而partial这个关键字虽然是必须的，但它只是加一个标识符的事，并不会破坏类的其他设计。

这里顺便讲一个我踩过的真实坑：如果你生成的类实现了接口，而手写侧也在同一个类的另一个partial文件里实现了同一个接口的某些成员，编译器会报重复实现错误。 但是，如果一个是显式接口实现、一个是隐式接口实现，就不会冲突。所以在生成代码的模板设计阶段，就要想好接口的实现方式，避免生成器和手写代码在接口实现上“撞车”。

3.5 生成器写好后怎么验证它真的动了

新手写完生成器最常问的问题是：我编译了，但怎么确认生成器真的在跑？

几个实用手段：

1. 设置EmitCompilerGeneratedFiles：在csproj里加上

xml复制<PropertyGroup>
  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
  <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)GeneratedFiles</CompilerGeneratedFilesOutputPath>
</PropertyGroup>

编译之后，去obj/GeneratedFiles/MyGenerator/目录下就能直接看到生成出来的Person.g.cs。

2. 在生成器里加Debug输出：可以用Debugger.Launch()打断点，不过这个方法在CI环境里会挂起进程，慎用。更好的方式是往context.ReportDiagnostic里写一个Information级别的诊断信息，让它在Error List窗口显示。

3. 用.editorconfig控制诊断级别：生成器报告诊断信息时，用户可以通过.editorconfig把这些诊断分别配置为error、warning、suggestion或silent。

我的习惯是，在开发生成器阶段直接打开obj/GeneratedFiles目录看输出，比任何调试手段都直观。只要生成的代码样子符合预期，再往测试方向推进。

4. 常见问题与排查技巧实录

4.1 SourceGenerator的单元测试怎么写

生成器本身不是普通逻辑代码，它的执行依赖Roslyn的编译上下文，没法直接new一个实例调用方法测试。所以主流的测试策略分两类：基于Roslyn的编译级测试和快照测试。

先看编译级测试。用Microsoft.CodeAnalysis.CSharp的CSharpCompilation搭建一个内存中的编译单元：

csharp复制[Fact]
public void AutoNotify_生成属性通知代码()
{
    var source = @"
using MyGenerator.Abstractions;

namespace MyApp.Models
{
    public partial class Person
    {
        [AutoNotify]
        private string _name;
    }
}";

    var syntaxTree = CSharpSyntaxTree.ParseText(source);
    
    var references = AppDomain.CurrentDomain.GetAssemblies()
        .Where(a => !a.IsDynamic && !string.IsNullOrEmpty(a.Location))
        .Select(a => MetadataReference.CreateFromFile(a.Location))
        .ToList();
        
    // 需要额外把Abstractions程序集加进来，否则Attribute解析不了
    references.Add(MetadataReference.CreateFromFile(typeof(AutoNotifyAttribute).Assembly.Location));

    var compilation = CSharpCompilation.Create(
        "TestAssembly",
        new[] { syntaxTree },
        references,
        new CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary));

    var generator = new AutoNotifyGenerator();
    GeneratorDriver driver = CSharpGeneratorDriver.Create(generator);
    driver.RunGeneratorsAndUpdateCompilation(compilation, out var outputCompilation, out var diagnostics);

    var generatedSyntaxTrees = outputCompilation.SyntaxTrees
        .Where(st => st.FilePath.EndsWith(".g.cs"))
        .ToList();

    Assert.Single(generatedSyntaxTrees);

    var generatedCode = generatedSyntaxTrees[0].GetText().ToString();
    Assert.Contains("public string Name", generatedCode);
    Assert.Contains("OnPropertyChanged(nameof(this.Name))", generatedCode);
}

这类测试的价值在于：它验证的是“在真实编译环境下，生成器真的输出了符合预期的代码”。缺陷是它不会执行生成的代码，所以类型错误、逻辑错误无法被发现。

所以更进一步的测试是：把生成代码再编译一次，并执行它跑断言。 也就是在outputCompilation基础上，用Emit把程序集写到内存流，再用反射加载调用。这样能做到端到端验证。

csharp复制var ms = new MemoryStream();
var emitResult = outputCompilation.Emit(ms);
Assert.True(emitResult.Success); // 这里会暴露生成代码的编译错误

ms.Seek(0, SeekOrigin.Begin);
var assembly = Assembly.Load(ms.ToArray());
var personType = assembly.GetType("MyApp.Models.Person");
var instance = Activator.CreateInstance(personType);

var nameProperty = personType.GetProperty("Name");
nameProperty.SetValue(instance, "张三");

var eventRaised = false;
var propertyChanged = personType.GetEvent("PropertyChanged");
var handler = new PropertyChangedEventHandler((sender, args) =>
{
    if (args.PropertyName == "Name") eventRaised = true;
});
propertyChanged.AddEventHandler(instance, handler);

nameProperty.SetValue(instance, "李四");
Assert.True(eventRaised);

这个测试设计思路的核心是：先让生成器跑一遍，得到的outputCompilation如果有编译错误，Emit一定会失败，这样你就知道生成器输出了坏代码；如果编译通过，再通过反射创建实例、订阅事件、触发赋值，验证生成代码的业务行为是否正确。这套流程基本就是SourceGenerator测试的标准打法。

4.2 快照测试：防止生成代码被无意改动

单元测试能验证行为，但没法直观展示“生成代码到底长什么样”。当我需要确认生成结果精确匹配预期时，用**快照测试（Snapshot Testing）**更合适。

快照测试的思路很简单：第一次运行测试时，把生成的代码存到一个__snapshots__目录下；之后的每次运行，把新生成的代码和快照对比，如果有任何差异，测试失败并提示你需要人工确认是“有意改动”还是“生成器回归”。

社区里有现成的Verify库，也可以自己写几十行代码实现。我更常用的是手写方式，因为生成器测试里的“快照”不只是文本快照，很多时候需要对比的是语法树的规范化形式——比如代码格式的差异不应该导致快照失败。

手写快照测试的核心逻辑：

csharp复制[Fact]
public void AutoNotify_快照对比()
{
    // 运行生成器得到generatedCode
    var normalized = CSharpSyntaxTree.ParseText(generatedCode)
        .GetRoot()
        .NormalizeWhitespace()
        .ToFullString();
        
    var snapshotPath = Path.Combine("__snapshots__", "Person.g.cs.snap");
    
    if (!File.Exists(snapshotPath))
    {
        Directory.CreateDirectory("__snapshots__");
        File.WriteAllText(snapshotPath, normalized);
        return; // 第一次运行，创建快照
    }
    
    var snapshot = File.ReadAllText(snapshotPath);
    Assert.Equal(snapshot, normalized);
}

NormalizeWhitespace()这个调用很关键，它把代码统一为一种标准的缩进格式，避免因为生成模板里的细微空白差异导致测试频繁失败。

快照测试的坑在于：首次生成的快照没经过严格审查就被当作基线，以后所有回归都被掩盖了。 所以我建议第一次跑快照测试时，生成完快照后人工打开文件看一遍，确认代码结构完全正确再提交。

4.3 常见编译错误速查表

我在开发和维护生成器的过程中，遇到过不少脑壳疼的问题。这里整理一个速查表，帮大家快速定位：

4.4 一个我实际处理过的“偏门”问题

有一次我发现生成器生成的代码在IDE里智能提示正常，但命令行dotnet build却报错。排查了很久，最后发现是两个版本的Roslyn行为差异导致的。

具体来说：IDE里我用的是VS自带的Roslyn版本（比较新），而命令行dotnet build用的SDK里带的Roslyn版本可能低一两个小版本。某些语法API（比如record、file-scoped namespace）在高版本Roslyn里能用，在低版本里会崩。

解决办法有两个：

1. 在生成器项目里固定依赖的Roslyn版本，比如指定<PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.8.0" />，但SDK自带的Roslyn版本如果低于这个，还是不行。
2. 把生成器目标框架的Roslyn版本调低，兼容更广的编译环境。

我的建议是，如果生成器是给团队内部用的，可以统一SDK版本；如果是作为NuGet包发布给社区用的，就要降低Roslyn依赖版本，扩大兼容范围。

4.5 调试生成器的实用手段

调试SourceGenerator比调试普通代码别扭一些，因为它是“寄生”在编译进程里的。分享几个我自己常用的调试方法。

方法一：生成文本日志。 在生成器的关键节点，把收集到的信息（比如命中了几个类型、每个类型有几个需要生成的字段）追加写入一个日志文件。这个方法最土但最有效，CI上也方便查。

csharp复制// 注意：只在Debug模式下写日志，避免影响Release性能
#if DEBUG
File.AppendAllText(@"D:\temp\generator.log", 
    $"发现类型: {symbol.Name}, 字段: {field.Name}, 字段类型: {field.Type}\n");
#endif

方法二：编译错误注入。 故意在生成器里ReportDiagnostic一个Error级别诊断，内容携带调试信息。这样在Error List窗口可以看到输出，比找日志文件方便。

方法三：附加到编译器进程。 这个方法比较暴力，但有时候源码级调试真的能救急。用Debugger.Launch()可以让编译器进程弹出一个调试器选择框，然后附加到dotnet进程或VBCSCompiler进程，就能在生成器代码里下断点了。

需要提醒的是，Debugger.Launch()在CI环境会导致进程挂起，提交代码前一定要删掉。

4.6 性能优化与增量缓存到底该怎么做

SourceGenerator性能问题的核心在于：它的执行时间直接叠加在你的每次编译时间上。 一个大型项目里如果生成器写得烂，编译时间从几秒飙升到几十秒，团队成员的开发体验会非常糟糕。

最常见的性能杀手是“过度收集”。比如你为了找几个带特定特性的类，把整个语法树的所有节点都遍历了一遍。项目规模大了之后，这个遍历成本完全不可接受。

正确的优化姿势是利用增量生成器的“pipeline”特性：

csharp复制var fields = context.SyntaxProvider
    .CreateSyntaxProvider(
        predicate: static (node, _) => node is VariableDeclaratorSyntax,
        transform: static (ctx, _) => { /* 语义判断 */ })
    .Where(static field => field is not null);

predicate这段只做语法层面的快速筛选，开销极小；只有语法筛选通过的节点，才会进入transform做耗时的语义分析。很多新手把语义判断一股脑写进predicate里，结果每次编译都要对每个节点做完整语义解析，项目一大必然卡死。

还有一个小技巧：在用Collect()聚合前，先把每个字段映射成轻量级值对象，让后续的缓存比较变得廉价。如果直接保留IFieldSymbol引用，任何无关的代码变更都可能让整个编译的缓存失效，增量生成的优势就全丢了。

5. 测试工程的最佳实践

5.1 测试工程的目录与依赖怎么组织

测试生成器项目的csproj和组织方式有自己的一套讲究。我的标准模板是这样的：

xml复制<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <IsPackable>false</IsPackable>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
    <PackageReference Include="xunit" Version="2.6.6" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.6" />
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.8.0" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="..\..\src\MyGenerator\MyGenerator.csproj" />
    <ProjectReference Include="..\..\src\MyGenerator.Abstractions\MyGenerator.Abstractions.csproj" />
  </ItemGroup>
</Project>

测试项目需要同时引用生成器和Abstractions：引用生成器是为了拿到生成器类，引用Abstractions是为了让测试代码里的Attribute可以被正确解析。

5.2 测试用例设计的三个层次

我习惯把生成器的测试分成三个层次，每一层解决的问题不同：

第一层：语法层测试。 输入特定源码，断言生成器输出的源代码里包含/不包含哪些特征。这层最便宜，跑得最快，适合覆盖面广的快速回归。

第二层：编译层测试。 像前面说的，把源文件和生成结果合起来Emit，断言编译成功。这层能抓住“生成的代码本身有语法错误”这种低级又致命的问题。

第三层：行为层测试。 通过反射加载生成的程序集，真实调用生成的属性、方法，断言运行时行为符合预期。这层最贵，但对生成器的信任度提升也最大。

理想的比例是：语法层测试占60%，编译层测试占30%，行为层测试占10%。不要每个用例都跑到行为层，否则测试集膨胀得厉害，维护成本也高。

5.3 测试用例里的“边界条件清单”

写SourceGenerator测试时，最有价值的是边界条件覆盖。给大家列一份我踩过坑之后总结的检查清单：

• 空输入：没有任何带特性的类型时，生成器不崩溃、不输出内容。
• 重复标记：同一个字段上标记多个[AutoNotify]时，不会生成重复代码。
• 命名冲突：手写代码已经有一个Name属性时，生成器是否报错或者跳过。
• 继承场景：包含继承关系的类型，生成代码是否和基类成员冲突。
• 泛型类型：泛型类型里的字段生成代码是否正常。
• 嵌套类型：嵌套在另一个类里的类，命名空间和类型名的拼接是否正确。
• 文件作用域命名空间：源文件用namespace X;新语法声明时，生成器能否正确处理。
• Nullable上下文：#nullable enable开启时，生成的代码是否缺失空值注解。

每个边界条件对应的测试代码都不复杂，但在项目演进过程中，它们能帮你拦住大量回归。

5.4 一个端到端的测试用例示例

下面给一个完整的“行为层”测试示例，展示覆盖边界条件时怎么写：

csharp复制[Fact]
public void AutoNotify_继承类型不冲突()
{
    var source = @"
using MyGenerator.Abstractions;

namespace MyApp.Models
{
    public class BaseEntity
    {
        public string Id { get; set; } = string.Empty;
    }

    public partial class DerivedEntity : BaseEntity
    {
        [AutoNotify]
        private string _title = string.Empty;
    }
}";

    // 运行生成器...
    var (outputCompilation, generatedCode) = RunGenerator(source);
    
    // 编译必须成功，同时生成代码中不能包含和基类重复的Id
    using var ms = new MemoryStream();
    var emitResult = outputCompilation.Emit(ms);
    Assert.True(emitResult.Success);
    Assert.DoesNotContain("public string Id", generatedCode);
}

这个例子的技术点在于：生成器在遍历字段时，必须能区分“哪些字段定义在当前类型里”和“哪些继承自基类”。IFieldSymbol.ContainingType可以帮你做这个判断。如果生成器把继承来的字段也生成了属性，那结果里就会多出一个和基类重复的Id。

5.5 在CI里跑生成器测试要注意什么

生成器测试在本地跑没问题，到了CI环境经常出现一些诡异状况，最常见的是“引用缺失”。

原因是CI环境里执行测试的进程和我本地开发机的运行时环境不完全一致，AppDomain.CurrentDomain.GetAssemblies()拿到的程序集集合可能缺少某些运行时程序集，导致生成的编译单元缺少了System.Object等基础引用，Emit直接失败。

解决方案是在测试里固定一份“基础引用集”，显式添加运行时程序集和必要的框架引用：

csharp复制private static readonly MetadataReference[] DefaultReferences =
{
    MetadataReference.CreateFromFile(typeof(object).Assembly.Location),
    MetadataReference.CreateFromFile(typeof(Attribute).Assembly.Location),
    MetadataReference.CreateFromFile(typeof(PropertyChangedEventArgs).Assembly.Location),
    // ...
};

还有一个CI相关的坑：Emit成功但测试跑不起来，通常是因为生成的程序集引用的运行时版本和测试进程不一致。比如生成代码里用了CallerMemberNameAttribute，这个Attribute在.NET Framework和.NET Core的引用程序集位置不同，测试环境缺了某个引用就会在加载时抛异常。这类问题没有捷径，只能靠工整的引用管理慢慢排查。

6. 我使用partial范式后的几点心得

最后说点代码之外的体会。

第一次用SourceGenerator写业务代码时，最容易犯的错误是贪多求全——恨不得把整个业务逻辑都塞进生成器里。实际上，SourceGenerator最擅长的是“机械的、可推导的”代码生成，而不是“智能的、有业务判断的”代码编排。保持克制，让生成器只负责那些重复劳动，把真正的业务决策留给人，这才是好的设计。

partial范式给我最大的启发是：它不是让机器替人写代码，而是人和机器各自做自己擅长的事情。 人负责描述意图（声明partial类、打标记特性），机器负责补齐琐碎的实现细节。这种协作方式让代码的可读性和可维护性都上了一个台阶。

另外，测试这块我建议团队里一定要有专门的人认真做。SourceGenerator是“编译器级”的代码，它出错不是崩一个功能，而是让整个项目编译不过。这种放大效应决定了它的质量要求必须比别人高。那种“能跑就行”的心态，在生成器这里真的会翻车。

如果你想把这套东西落地到项目里，建议从最小场景开始，比如先做DTO的Clone方法，或者先做通知属性变更，跑顺之后再逐步扩展。别一上来就写一个几百行的万能生成器，那大概率会变成谁也维护不了的代码生成怪物。

以后有机会再单独写一篇关于如何把SourceGenerator打包成NuGet集成到团队基建里的文章。先这样。