FUI路由层重构：从反射GetTypes到Source Generator强类型Route

如果想在我维护的FUI框架里挑一次自己都觉得值回票价的重构我会选路由层从反射GetTypes()迁到 Source Generator 强类型 Route 的那个版本。FUI 是一个面向功能模块的轻量服务框架核心思维不是 MVC 那种“控制器 Action”而是把一个领域能力包成一个可执行方法再按固定语义暴露成服务调用入口。早期版本图快路由表全部靠运行时扫描程序集完成一个GetTypes()配上几个IsAssignableFrom就能把所有 handler 捞出来。功能少的时候很舒服但随着模块变多、链路变长问题开始集中暴露。这篇文章我会用 FUI 的路由层演进作为主线讲清楚为什么一开始会选择反射实现后来为什么要切到 Source Generator强类型 Route 到底解决了哪些真实痛点以及我在落地过程中踩过哪些坑。无论你是在做类似的功能注册机制还是维护一个需要频繁扩展的服务框架这段设计演进过程应该都能给你一些可搬走的经验。1. 反射版的 GetTypes() 路由先解决了哪些问题1.1 FUI 路由层最初的需求FUI 的路由层做的是三件事第一在进程启动时发现所有符合约定的 handler 类型第二把每个 handler 上的公开功能方法解析成一条路由记录第三收到服务调用请求时通过路由记录找到对应的类型和方法再用反射完成调用。最初版本的代码看起来非常直白大致是这种形态public static class FuiRouteScanner { public static ListRouteMeta Scan(Assembly assembly) { var result new ListRouteMeta(); foreach (var type in assembly.GetTypes()) { if (type.IsAbstract || type.IsInterface) continue; if (!typeof(IFuiHandler).IsAssignableFrom(type)) continue; foreach (var method in type.GetMethods(BindingFlags.Public | BindingFlags.Instance)) { var attr method.GetCustomAttributeFuiRouteAttribute(); if (attr is null) continue; result.Add(new RouteMeta( method: attr.Method, route: attr.Route, handlerType: type, methodInfo: method)); } } return result; } }这个方法放在当时的环境里其实是合理的。FUI 刚起步时只有几个模块几十个功能入口程序集加载很快反射扫描一次的耗时根本不值得关心。更重要的是团队内部每天都在新增功能 handler如果路由表要手工维护肯定会有人漏登记而GetTypes()方案能保证“你写了一个 handler启动后它自动就在路由表里”。这种动态发现的爽感在小规模项目里是真实存在的。1.2 反射方案带来的三个隐性成本等项目规模到了几十个模块、几百个路由入口的时候反射方案的隐性成本就藏不住了。第一是启动阶段的安全感是假的。GetTypes()扫描表面上在启动时发现了所有 handler但它只保证“发现”这一步完成了不保证路由配置本身正确。比如 handler 的方法签名被同事改掉了参数从CreateOrderRequest换成了CreateOrderInput这个改动在编译期不会报错因为路由表里存的是MethodInfo调用时才Invoke。结果就是代码编译通过、服务正常启动等第一批请求打过来才在运行时炸出TargetParameterCountException。这类问题特别磨人因为它往往发生在发布之后。第二是程序集扫描的脆弱性。GetTypes()并不是一个绝对安全的 API只要程序集里有一个类型因为依赖缺失无法加载它可能直接抛出ReflectionTypeLoadException。FUI 早期接一个内部插件项目时就踩过这个坑那个项目引用了若干第三方 SDK类型加载器在解析部分类型时失败我们的启动逻辑直接崩掉。后来不得不用GetReferencedAssemblies做递归扫描还得包一层容错处理。隐患从功能模块扩展的第一步就存在了。第三是日志和链路里到处是魔法字符串。路由注册时可以写attr.Route /order/create调用方代码里可能也写着order/create这样的字符串。两端只要有一个字母大小写不一致请求就是 404。更麻烦的是 IDE 重构不会帮你改字符串字面量搜索历史里几千个字符串谁也不敢保证自己的改动覆盖了全部区域。1.3 真正推动演进的转折点让整个迁移正式立项的是三个很现实的场景一是线上出现过一个路由冲突。两个不同模块的 handler 给方法标注了同一个路由模板由于GetTypes()返回的 Type 顺序没有确定性保障每次启动哪个 handler 生效都不一定最后只能靠日志临时定位。这种冲突如果在编译期就能被检查出来根本不会留到生产环境。二是性能压测时发现路由分发的调用栈很难看。虽然 .NET 对反射调用做了一些优化但MethodInfo.Invoke每次都要处理参数数组、方法签名匹配和异常包装在高频调用路径上始终是额外开销。对 FUI 这种内部支撑系统来说不是致命问题但它提醒我随着请求量继续增长路由层不该成为不可控的瓶颈。三是 IDE 对路由不感知。同事问我“某个页面对应的后端入口在哪里”我只能在代码里搜字符串。问题不是找不到而是每个人都可能找到不同的地方。因为相同的 URL 可能出现在前端配置文件、反向代理规则、后端 handler 标注、单元测试断言多处纯人力维护链路的一致性迟早出事。转折点出现后我意识到真正的问题不只是替换一个 API而是把路由从“运行期发现的元数据”变成“编译期可知的符号”。2. Source Generator 为什么适合这件事强类型 Route 又是怎么回事2.1 Source Generator 的前提条件静态可枚举在决定用 Source Generator 之前我需要先确认 FUI 的模块集合是不是静态可枚举的。Source Generator 在编译期只能看到当前代码里的类型和引用没有办法在运行时动态加载一个尚未存在的程序集。所以如果业务场景真的是“外部插件随便丢一个 DLL 进来就能被识别”Source Generator 并不合适反射仍是必要的兜底手段。FUI 的实际情况是handler 类型虽然会不断新增但都来自一个或多个明确的项目程序集并且所有 handler 都遵循一个约定要么实现IFuiHandler接口要么使用[FuiRoute]标注方法。这个约定在代码层面是静态可发现的。正因如此Source Generator 才能完整替代反射扫描工作。它扫描的不是运行时程序集而是编译器语法树和语义模型相当于把原来启动时的“注册动作”提前到了每次编译时。Source Generator 这条路并不是没有成本。它要求你理解 Roslyn 的增量生成模型还要处理缓存和性能问题。但跟反射版本的问题相比成本花在刀刃上每写一个新 handler编译器都能当场验证路由是否重复、方法是否存在、类型是否符合约定。2.2 强类型 Route 的“强”体现在哪里一开始我对“强类型 Route”这个概念也不太确定后来在设计里把它拆成了两层含义。第一层是 Route 本身成为一个可引用的符号。过去路由是一段字符串/order/create散落在 handler 标注、调用方代码、测试代码多个位置。迁移后FUI 会为每个路由生成一个编译期常量例如FuiRoutes.OrderCreate服务端注册和客户端调用都引用这个常量。URL 的意义没有变但我们不再以字符串字面量的身份去维护它。一旦有人改动了路由模板或删除了对应方法编译器会直接提示引用处报错。第二层是路由对应的处理方法调用不再依赖MethodInfo.Invoke。Source Generator 在生成路由表时会生成一段针对每个 handler 方法的强类型调用代码。直接代码调用和反射调用的区别就像是你平时通过一个具体接口调方法和根据一个字符串去查找方法再动态触发调用的区别。前者能在编译期检查参数类型后者只能等到运行期撞上错误。这是“强类型 Route”最核心的价值把 Route 从“一段路径文本”升级成“一个可编译的符号”同时把路由背后的执行逻辑从“运行时元数据查找”变成“编译期生成的直接委托”。2.3 为什么不选 IL Emit 或 DynamicMethod方案评审时也考虑过另外两条路。一是用DynamicMethod在启动阶段为每个 handler 生成一个轻量的委托二是用 IL Emit 把整个路由派发逻辑动态编译出来。这两个方案在性能上其实都能满足要求而且不用引入 Roslyn 的复杂度。但我最终放弃了。原因是我发现自己并不需要“运行期动态生成 IL 的能力”真正需要的是“把这些生成物摆在代码里让人看得见、审得了、查得着”。Source Generator 生成的是 .cs 源文件团队成员在 IDE 里可以通过 Go To Definition 看到可以复制到测试工程里单测也可以在 code review 时把这个生成的代码作为 diff 的一部分讨论。IL Emit 和 DynamicMethod 做不到这一点它们只能在运行时通过调试器看中间结果排查问题成本更高。另外IL Emit 方案对模块化项目还有一个隐藏问题如果进程启动时动态生成代码失败生产环境只能看到异常栈很难做静态分析。而 Source Generator 的产物在编译阶段就已经存在CI 里跑一次dotnet build就能发现大部分问题。3. 生成器落地的核心工程细节3.1 工程结构与标记定义整个实现拆成了几个项目。Fui.Abstractions放公共约定的 Attribute 和接口它会被主业务项目和生成器项目共同引用。Fui.Generators是实际的 Source Generator 项目编译目标通常是netstandard2.0。FUI 主项目负责运行时装配、DI 集成和请求分发。FUI 的约定是直接用一个 Attribute 标在方法上using System; namespace Fui.Abstractions; [AttributeUsage(AttributeTargets.Method, AllowMultiple false, Inherited false)] public sealed class FuiRouteAttribute : Attribute { public FuiRouteAttribute(string route) { Route route; } public string Route { get; } public string Method { get; set; } POST; }Route是必须提供的Method不填默认 POST。这个 Attribute 会同时出现在编译器和运行时两个层面编译器根据它收集信息、生成路由表运行时则不再依赖它做发现只把它当成元数据备用。IFuiHandler接口仍然保留但它的作用从“被反射扫描的标记”变成了“约束 handler 类型结构”的约定。实际解析时Source Generator 会根据方法上的 Attribute 来收集路由而不是扫描整个程序集。3.2 增量生成器骨架的关键写法Source Generator 我用了IIncrementalGenerator而不是老的ISourceGenerator。增量模型能缓存中间结果只有真正受影响的输入变化时才重新执行生成逻辑这在大型解决方案里很重要。核心代码大致如下[Generator(LanguageNames.CSharp)] public sealed class FuiRouteGenerator : IIncrementalGenerator { public void Initialize(IncrementalGeneratorInitializationContext context) { var methods context.SyntaxProvider.ForAttributeWithMetadataName( Fui.Abstractions.FuiRouteAttribute, static (node, _) node is MethodDeclarationSyntax, static (ctx, _) new RouteMethodModel( MethodName: ctx.TargetSymbol.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat), Route: GetRouteValue(ctx.Attributes[0]), HttpMethod: GetHttpMethodValue(ctx.Attributes[0]), SyntaxTree: ctx.TargetSymbol.Locations.FirstOrDefault()?.GetLineSpan()) ).Where(static item item.Route is not null); var collected methods.Collect(); context.RegisterSourceOutput(collected, static (spc, routeMethods) Execute(spc, routeMethods)); } }ForAttributeWithMetadataName是 Roslyn 4.3.0 以后提供的 API非常适合这种按 Attribute 收集的生成器。它会在语义层面找到所有使用了目标 Attribute 的语法节点节省了手写SyntaxProvider.CreateSyntaxProvider再加语义过滤的步骤。RouteMethodModel是一个不可变模型用来保存从语法节点和符号中提取的字符串信息。这里有一个值得强调的细节不要直接在这个模型里塞IMethodSymbol因为符号对象非常重并且天然带有比较器缺失问题会影响增量缓存的命中率。把它们转换成字符串、枚举、布尔值这类稳定值缓存效果会好很多。3.3 生成两个产物Route 常量表与 Dispatch 注册代码每个 handler 方法被收集到后我要为它生成两个东西。第一个是强类型 Route 常量。以OrderModule.CreateOrder方法为例如果它标注的 Route 是/order/create生成器会生成类似下面的常量// auto-generated / #nullable enable public static partial class FuiRoutes { public const string OrderModule_CreateOrder /order/create; }这个常量类名是有意做成partial的这样如果未来还需要人工补充少量非 Source Generator 可发现的路由可以在同一个类的另一个 partial 文件里维护。常量命名规则用“类名_方法名”如果遇到同名冲突再追加参数类型或数字后缀来保证唯一。由于它和 handler 方法在同一个编译单元中生成一旦方法被删除或改名相关引用会立即出现编译错误。第二个是 dispatch 注册代码。这部分要让每个 handler 方法对应一个类型明确的委托。FUI 的 handler 方法返回类型通常带有自己的业务语义所以生成的委托会保持返回类型只在最外层包装成统一结构internal sealed partial class FuiRouteRegistryGen { internal void Populate(FuiRouteRegistry registry) { registry.Add(new FuiRouteDescriptor( FuiRoutes.OrderModule_CreateOrder, POST, typeof(Demo.Order.OrderModule), static (handler, context, ct) { var module (Demo.Order.OrderModule)handler; return module.CreateOrder(context, ct); })); } }这里module.CreateOrder(context, ct)是编译器能直接解析的直接调用。运行时不再需要 MethodInfo不需要准备 object[] 参数数组异常栈也干净很多。尤其当 handler 方法内部抛异常时堆栈里能看到真实的业务方法名而不是一行System.Reflection.MethodBaseInvoke这样的冷冰冰信息。3.4 路由冲突检查前移为编译期错误Source Generator 能带来的额外红利是路由冲突检查。在反射时代两个 handler 标注了同一个路由模板通常要等进程启动扫描完所有类型后Log 里才会出现一条“Duplicate route”警告。现在则完全不同因为所有路由信息在编译时就被收集到了一起。生成器里的Execute方法会遍历收集到的RouteMethodModel列表按 Route 和 HttpMethod 做一个聚合分组var duplicates routeMethods .GroupBy(item (item.Route, item.HttpMethod), StringComparer.OrdinalIgnoreCase) .FirstOrDefault(group group.Count() 1);如果找到重复项可以直接定位到源码位置输出一条Diagnosticspc.ReportDiagnostic(Diagnostic.Create( new DiagnosticDescriptor( FUI001, 路由冲突, 检测到重复路由 {0}HTTP 方法 {1} 同时被 {2} 和 {3} 注册, FUI.Route, DiagnosticSeverity.Error, isEnabledByDefault: true), duplicateLocation, dup.First().Route, dup.First().HttpMethod, dup.First().MethodName, second.MethodName));这样“重复路由”就从日志告警升级成了编译错误。同事写代码时还没编译完就知道自己撞了别人的路由不需要把问题带到集成测试阶段。4. 迁移后的调用变化与 DI 边界处理4.1 调用处的魔法字符串被常量替换路由表从反射切到 Source Generator 后第一个要改的其实是调用方。过去 FUI 内部服务之间互相调用可能长这样var result await FuiClient.InvokeAsyncCreateOrderResult( order/create, request, CancellationToken.None);现在改成了var result await FuiClient.InvokeAsyncCreateOrderResult( FuiRoutes.OrderModule_CreateOrder, request, CancellationToken.None);从字符串到常量的迁移看似简单但它改变了整个代码库的维护方式。如果路由模板改变了你不再需要靠 grep 去找所有引用点编译错误会清清楚楚地把每一个漏改的点都列出来。代码重构工具也能通过 Rename Symbol 直接改常量的名字而字符串字面量在 IDE 里通常不会被自动重构。4.2 容器实例化与生成的委托如何协作有人会问既然 dispatch 代码里已经有typeof(Demo.Order.OrderModule)为什么不直接在生成代码里new OrderModule()因为很多 handler 依赖构造器注入编译期拿不到运行时的 DI 容器。FUI 的最终设计是保留 DI 容器作为服务实例的提供者生成的委托负责处理“拿到 handler 实例之后”的调用过程。这样分工后Source Generator 只需要知道 handler 方法签名不参与构造器参数解析。运行时收到请求后FUI 从容器请求对应的 handler 类型实例再把实例传给生成的委托。这个边界的关键在于源生成器不知道也不应该知道你的 IoC 容器里注册了什么、生命周期是什么。它只负责处理“路由 - 类型 - 方法调用”这一段强类型关系。具体的实例生命周期控制仍然以IServiceProvider作为运行时抽象的边界。4.3 旧代码兼容保留一个反射开关作为过渡从反射迁移到 Source Generator 不是一次原子提交就能完成的尤其当 FUI 已经接入多个业务模块时不可能要求所有模块在同一晚完成改造。所以我留了一个过渡期开关运行时仍然支持反射扫描但启动时会输出一条废弃警告提示某个模块还没有迁移到 Source Generator 模式。这个开关的成本很低。FUI 的运行时在装配路由表时优先使用生成的FuiRouteRegistryGen填充路由如果生成器没有输出内容或者某些模块明确标记了“使用旧扫描器”则回退到GetTypes()扫描。这样新模块可以先迁移旧模块继续运行等全部模块都迁移完再删除旧扫描代码。过渡过程中我还临时加了一个启动校验用 Source Generator 生成的常量表和反射扫描结果做一次对比找出那些两边不一致的模块输出到日志里。这一步帮助我从几百个路由中发现了不少之前漏配或错配的路径算是迁移过程中最有价值的诊断数据。5. 实际踩过的坑和排查经验5.1 生成器没有生效时先查项目引用Source Generator 最常见的坑就是没生效。我在本地把 generator 项目写好构建主工程发现FuiRoutes类根本不存在。查了半天问题出在项目引用方式上。源生成器必须以 Analyzer 的方式被引用普通的ProjectReference不会让它运行。正确的 csproj 配置是ProjectReference Include..\Fui.Generators\Fui.Generators.csproj OutputItemTypeAnalyzer ReferenceOutputAssemblyfalse /另外还要确认生成器项目目标框架是netstandard2.0不能直接 net8.0否则编译器进程加载不了。像下面这样TargetFrameworknetstandard2.0/TargetFramework如果你的环境里同时有多个 SDK 版本还要注意 Roslyn 版本兼容。VS2022 17.8 以上基本都能用ForAttributeWithMetadataName但如果是更老的 IDE 或者 build agent需要回到旧式SyntaxProvider写法。5.2 ForAttributeWithMetadataName 对 Attribute 的要求这个 API 用起来很方便但有一个边界条件它要求传入的 metadata name 能够唯一对应目标 Attribute。比如你传入Fui.Abstractions.FuiRouteAttribute编译器会尝试在所有引用的程序集里找到这个名字的 Attribute 类型。如果同一个命名空间下存在两个不同程序集都定义了相同全限定名的 AttributeRoslyn 会报歧义错误。所以 Attribute 的定义位置要谨慎。最好是放在一个独立的基础包里团队里不要随便复制一份同名 Attribute 到别的项目。另一个坑是 Attribute 的可见性ForAttributeWithMetadataName可以定位 internal 的 Attribute但如果你希望其他项目通过项目引用方式使用把 Attribute 设为 public 更稳妥。5.3 增量缓存没命中导致编译变慢第二版生成器上线后我观察到一个怪现象某些项目的编译时间比以前明显变长。查了 Roslyn 的生成日志发现增量管线的缓存没有命中每次编辑都会重新执行整个生成逻辑。根因是我在增量模型里放了不可比较的类型。起初返回的RouteMethodModel里带了一个ITypeSymbol字段用来记录 handler 类型信息但没有实现IEquatableRouteMethodModel也没有覆盖Equals。Incremental Generator 判断输入是否变化全靠比较返回值如果模型类型不能正确比较Roslyn 只能保守地每次都重新执行。修复方式是把模型改成纯数据类型只用字符串记录必要信息。比如 handler 类型的完全限定名、方法名、路由模板、HttpMethod、源码位置。需要解析类型关系时再重新拿符号不在缓存模型里保存重量级对象。5.4 生成代码里的隐式冲突和警告Source Generator 生成的代码也是一等公民会被编译器继续分析。第一次生成 dispatch 代码时我漏写了#nullable enable导致依赖项目原本启用了 nullable 上下文生成代码里的引用类型字段却处于 nullable 忽略状态产生了一批警告。解决方法是生成文本的统一头部包含// auto-generated / #nullable enableauto-generated /注释会告诉编译器不要对被生成代码中的用户代码风格问题产生太多噪音。另外我会显式关闭生成文件里未使用字段的提示避免某个模块暂时没有路由时输出空类造成编译警告。5.5 生成器自身成了性能瓶颈的排查思路如果生成器自身的日志和堆栈不好排查我建议先做两步。第一步是在Execute方法里写一个临时文件把每次收集到的路由数量写到obj目录下观察它是否在预期的时候被调用。第二步是用 Roslyn 自带的 binary log 看生成阶段耗时比较不同输入下的增量或全量执行差异。Diagnostic也可以作为调试工具。你可以在生成器初始化阶段故意输出一条Diagnostic到某个临时文件路径用来确认当前 VS 或命令行构建确实加载了你的 generator 程序集。等定位完问题再移除。6. 演进之后的变化以及我的选型建议6.1 启动时间和运行路径的变化从最后效果看最明显的是启动日志里那一段反射扫描耗时消失了。FUI 之前扫描几十个模块涉及几百个类型进程启动阶段大约需要几十毫秒到上百毫秒接入新的 Source Generator 后这部分耗时不在运行时发生等于直接归零。不过坦白讲这点时间在和整个进程启动时间相比后未必特别突出它更像是一个附加的收益。更有价值的是请求调用路径的变化。以前每次请求都要走MethodInfo.Invoke现在代码生成后就是一次普通的实例方法调用。单次请求省下的开销可能微乎其微但当路由分发层不再是瓶颈时后续要接更重的中间件、拦截器、日志链路都会容易很多。毕竟你手里的牌是一张正常的直接调用而不是一层“元编程”的包装。6.2 团队协作体验的提升迁移后最让我满意的其实是 IDE 体验的变化。以前同事问“这个接口在哪实现”我只能把路由名发过去让他自己搜索。现在生成的FuiRoutes常量类和 dispatch 注册代码就是一个天然的索引F12 跳到定义就能看到路由对应的方法。新同事接手模块开发时只需要关心两件事方法是否有[FuiRoute]标注路由模板是否重复。重复会直接编译报错不需要把整个解决方案跑起来才能发现。路由常量名字写错也会在编译期报出不会出现线上 404 后才知道字符串打错的情况。6.3 什么样的框架适合这个演进思路如果你也在维护类似的功能模块注册框架我的建议是先问自己两个问题。第一个问题是模块集合是否静态可知。如果模块来自独立开发、独立发布的插件运行前无法枚举那么 Source Generator 无法完成全部发现工作你应该保留反射作为扩展点只把核心模块的注册交给编译期生成。第二个问题是你是否愿意接受生成器本身的维护成本。写一个 Source Generator 需要理解的细节并不少Roslyn API 也随着版本变化你需要为团队的构建链和 IDE 环境做一个充分的长期承诺。对我来说FUI 的路由发现这一个点是最适合试点 Source Generator 的位置因为它足够独立、改动范围可控而且能迅速地让整个团队感受到类型安全的好处。如果你也想在现有项目里引入源生成器可以找一个类似的“注册发现 调用分发”环节试试在没有真正改变框架核心的前提下先把编译期检查的收益拿到手。