如果你最近两年开始做 .NET 开发,那大概率绕不开 SourceGenerator 这个名字。我第一次真正被它打动,是在一个需要给几十个 DTO 类自动生成 INotifyPropertyChanged 实现的场景里。手写重复代码写到最后麻木,改用反射又担心启动性能和裁剪兼容性,后来切到 SourceGenerator,核心思路就是把一个原本要交给运行时做的事情挪到编译期,而且用一种很优雅的姿势:生成器只负责生成 partial 类型的另一半代码。
这篇文章我会从一个实际写过多个生成器的人的角度,把 SourceGenerator 的 partial 范式、具体的生成器实现方式,以及怎么给生成器构造一套可落地的测试方案,完整讲一遍。适合已经开始接触 Roslyn 的 .NET 开发者,也适合那些被重复代码逼得想换方案的团队。源码生成器这种东西,看起来是一次性魔法,但它并不是只有在运行时才需要验证。真正让这套 partial 范式稳下来的是测试,而且是能自动回归的测试。
1. SourceGenerator 是什么,以及 partial 范式为什么成为主流
1.1 编译期“插件”的基本原理
SourceGenerator 本质上是 Roslyn 编译器暴露出来的一套扩展点。编译器在把 C# 源码编译成程序集的过程中,会经历解析语法树、构建符号、语义绑定、生成 IL 等阶段。生成器就挂在编译管道上,它能够读取当前编译单元里的语法树和语义模型,然后向编译器追加新的 C# 源码。
我习惯把它比喻成“编译流水线上的代工厂”。你原来的代码是原材料,编译器负责组装,生成器是中间插入的一个加工环节。它不会去修改你的任何源码文件,只会把产出物以额外语法树的形式塞回编译流程。接下来编译器把“原始代码 + 生成代码”当作一个整体继续编译,最终输出程序集。这种机制天然决定了生成器只能“新增”而无法“修改”已有代码,这也是 partial 范式之所以重要的根本原因。
生成器有两种常见接口:经典写法是 ISourceGenerator,用 Execute 方法直接做遍历和生成;新写法是 IIncrementalGenerator,它把相同的输入分阶段缓存起来,在增量编译时能复用上一轮结果,性能更好。现在新项目我基本都直接推荐 IIncrementalGenerator,虽然刚上手时它的链式调用有点绕,但好处非常明显。
1.2 partial 关键字为什么成了生成器的最佳搭档
既然生成器无法修改已有源码,那它生成的代码必须找到“挂载点”。C# 的 partial 关键字几乎是为这个场景量身定做的:partial 类可以把一个类型拆到多个文件,partial 方法可以先把声明写在一个地方、把实现放到另一个地方。
生成器的典型用法就是“你写一半,我写另一半”。开发者在业务文件里写一个 partial class,声明自己想要什么;生成器检测到这些声明后,在另外的语法树里补全这个类的其余成员。以此实现“手写部分负责业务语义,生成部分负责机械实现”的分工。
如果不用 partial,生成器生成的类型和手写类型就是两个完全独立的类型,无法合并到一个类里。那样的话要么生成器被迫生成一个基类,你的业务类去继承基类,灵活性大打折扣;要么就得靠扩展方法补能力,很多场景根本走不通。所以 partial 范式几乎是所有正经 SourceGenerator 项目的最优解,形式上有 partial 类、partial 方法、partial 属性三种,后面我会分别展开。
1.3 和反射、T4、运行时动态代码的横向对比
聊 SourceGenerator 之前,很容易被问“那反射为什么不行?”我遇到过很多团队,第一版做属性通知、映射、序列化时都是用反射硬刚。反射的优势是运行时通用,代码写起来直观,不用了解编译器。但代价也很明显:启动时 Type 扫描和缓存、AOT 裁剪时元数据丢失、IL 级别优化困难。
T4 模板是另一种思路,在编译前生成一批 .cs 文件提交到代码库。它的问题是生成时机靠手动或构建脚本触发,生成结果的时效性差。改一个模型文件,忘记跑模板,生成的代码还是旧的,等到运行时才发现。
SourceGenerator 和这两个比起来,最大的优势是“即时”和“类型安全”。它在编译一开始就基于当前代码的最新状态生成源码,生成的结果马上参与编译,类型是强绑定的,IDE 也能识别。性能上它更是碾压反射——大部分逻辑在编译期已经展开,运行期不需要任何反射调用。
我用一个表格来说明取舍:
| 方案 | 运行性能 | 编译期介入 | 类型安全 | 调试体验 | 适用场景 |
|---|---|---|---|---|---|
| SourceGenerator | 高 | 是 | 强 | 中等 | 编译期可确定的重复代码 |
| 反射 | 低 | 否 | 弱 | 较好 | 运行时动态元数据访问 |
| T4 模板 | 高 | 否 | 强 | 一般 | 预生成独立代码文件 |
| 运行时代码生成 | 中 | 否 | 弱 | 较差 | 复杂动态构建场景 |
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. partial 范式的三种典型写法
2.1 模式一:partial 类补充成员
这是最简单的模式:生成器识别到某个类上存在约定好的特性,就为这个类补充额外的成员。因为类是 partial,生成器生成的成员会被合并进同一个类型,用户在使用时完全感知不到“这些成员是自动生成的”。
举个例子,我定义一个 [GeneratedGreeting] 特性,目标允许标注在类上。生成器检测到之后,给这个类生成一个 SayHello 方法。源码里可以这样声明:
csharp复制[GeneratedGreeting]
public partial class Greeter
{
}
生成器补全后,实际编译的代码相当于:
csharp复制public partial class Greeter
{
public string SayHello() => "Hello from generated code!";
}
这里有个很重要的细节:类必须声明为 partial。如果漏掉了 partial,编译器会报“缺少 partial 修饰符”的错误,因为生成代码里也定义了一个 Greeter 类。所以写生成器时,应该在诊断信息里明确提示用户“用 [GeneratedGreeting] 标记的类必须是 partial class”。
2.2 模式二:partial 方法实现“可插拔逻辑”
C# 9 之前,partial 方法必须是 private、返回 void、不能有访问修饰符,用途非常受限制。C# 9 开始放宽了限制,partial 方法可以有返回值、可以带访问修饰符,这给了生成器很大的发挥空间。
partial 方法的范式是:一个地方写声明,另
