适配 Native AOT：CommonLibraries 迎来重大更新

本文主要介绍了Sang.AspNetCore.CommonLibraries的最新更新。为了拥抱 .NET 的 Native AOT 特性我们对核心类库进行了重构并新增了对code与status字段的双向兼容支持旨在性能与兼容性之间取得平衡。1. 为什么要更新随着 .NET 开始大规模推广 Native AOT本地提前编译传统的依赖运行时反射Reflection的库在 AOT 环境下会遭遇“降维打击”。在之前的版本中我们的MessageModelT使用了基于反射的JsonConverterFactory动态生成转换器。在传统的 JIT 环境下这套“全自动”逻辑跑得非常丝滑。但在 AOT 环境下由于编译器会裁剪掉未被静态引用的代码且禁用了运行时动态类型生成这会导致程序直接崩溃并抛出NotSupportedException。此外为了解决不同项目对状态码字段命名status或code的偏好问题本次更新也加入了自动兼容逻辑。项目开源地址https://github.com/sangyuxiaowu/Sang.AspNetCore.CommonLibraries?wt.mc_idDT-MVP-50051952. 新特性code / status 双向兼容为了满足不同团队/不同后端框架对“状态码字段名”的习惯差异有人习惯用status也有人习惯用code我在MessageModelT上实现了code / status 双向兼容反序列化ReadJSON 里出现status或code都能正确映射到MessageModelT.Status序列化Write输出时可以按全局配置选择写成status或code整体方案的关键点是用一个可配置的“状态字段名”作为写出标准 自定义System.Text.JsonConverter 在读取时同时兼容两种字段名。2.1 写出字段名可配置StatusFieldNameMessageModelT提供了一个静态属性StatusFieldName用来配置“序列化时状态码字段的名字”。它的取值被严格限制为status或code防止被配置成其它字段名导致协议不可控。核心代码如下位于MessageModel.cspublic static string StatusFieldName { get MessageModelStatusField.Name; set MessageModelStatusField.Name value is status or code ? value : throw new ArgumentException(StatusFieldName only support status or code); }实现细节真实存储在内部静态类MessageModelStatusField.Name中默认status因为它是静态配置所以它的效果是“全局生效”的只要你设置一次后续序列化都会按该字段名输出。2.2 读取时双向兼容同时识别status/code仅靠属性的[JsonPropertyName(status)]并不能做到“读取时两种字段名都兼容”因为默认的System.Text.Json会严格按字段名映射。因此我们为MessageModelT提供了自定义 Converter在Read(...)中做兼容逻辑优先读取status如果不存在或类型不匹配再读取code最终统一写入MessageModelT.Status对应的核心代码在MessageModelJsonConverterT.Read(...)var status 0; if (root.TryGetProperty(status, out var statusElement) statusElement.ValueKind JsonValueKind.Number) { status statusElement.GetInt32(); } else if (root.TryGetProperty(code, out var codeElement) codeElement.ValueKind JsonValueKind.Number) { status codeElement.GetInt32(); }这样无论上游返回{ status: 0, msg: ok, data: {} }还是{ code: 0, msg: ok, data: {} }都能正确解析为同一个MessageModelT对象。2.3 写入时按配置输出status或code写出时的核心是字段名不写死而是从全局配置读取也就是上面StatusFieldName最终写入的MessageModelStatusField.Name。在MessageModelJsonConverterT.Write(...)中writer.WriteStartObject(); writer.WriteNumber(MessageModelStatusField.Name, value.Status); writer.WriteString(msg, value.Msg); ... writer.WriteEndObject();因此你可以通过以下方式控制输出字段名默认不设置输出status设置为MessageModelT.StatusFieldName code后输出code这就实现了“写出时统一口径读入时兼容多口径”。2.4 为什么用JsonConverterFactory让泛型MessageModelT自动生效并兼顾 AOTMessageModelT是泛型类型Converter 也对应是MessageModelJsonConverterT。为了让System.Text.Json在遇到任意MessageModel任意T时都能自动应用正确的 Converter我们在类型上标注[JsonConverter(typeof(MessageModelJsonConverterFactory))] public record class MessageModelTMessageModelJsonConverterFactory做两件事1) 判断是否是MessageModelpublic override bool CanConvert(Type typeToConvert) { return typeToConvert.IsGenericType typeToConvert.GetGenericTypeDefinition() typeof(MessageModel); }2) 创建对应的泛型 Converter并同时考虑AOT与非 AOT两条路径AOT 路径推荐通过RegisterT()预注册避免运行时反射/动态创建非 AOT 路径允许通过反射构造MessageModelJsonConverterT开发环境/普通 JIT 运行时很方便工厂的关键逻辑简化理解是// AOT先取预注册的 Converter if (Converters.TryGetValue(typeToConvert, out var converter)) { return converter; } // 非 AOT用反射创建 var dataType typeToConvert.GetGenericArguments()[0]; var converterType typeof(MessageModelJsonConverter).MakeGenericType(dataType); return (JsonConverter)Activator.CreateInstance(converterType)!;如果处在 AOT 场景且没有预注册会抛出更明确的异常提示你必须先RegisterT()。2.5 小结经过上面的处理我们实现了以下收益同时兼顾了性能与兼容性协议兼容性强读取端同时接受status/code不强迫上下游立刻统一输出标准可控写出时通过StatusFieldName统一字段名逐步推进规范化泛型友好MessageModelT不需要为每个T单独写 Converter 注册代码AOT 可用提供预注册入口避免在 AOT 环境中因反射/动态创建受限而不可用3. 深度解析AOT 模式下的“双重认证”在适配 AOT 时很多开发者会困惑“我明明已经在 Context 里注册了模型为什么还要手动 Register”这里我们可以用一个接地气的比喻来理解。3.1 户口登记 vs 岗位培训在 Native AOT 的世界里编译器是一个极其严谨且“抠门”的管家。为了节省空间他会清理掉所有看起来没用的代码。3.2 户口登记JsonSerializable这相当于给你的 DTO 模型如SummaryResponse上户口。告诉编译器“这个类是有用的请保留它的属性结构。”如果没有这一步序列化器连这个类有几个字段都不知道。3.3 岗位培训RegisterT这是针对类库自定义转换逻辑的。在 AOT 下编译器无法在运行时临时变出一个处理SummaryResponse的转换器代码。通过MessageModelJsonConverterFactory.RegisterT()你实际上是在给转换器做“岗前培训”。显式告诉编译器“请为这个类型专门编译一套处理逻辑。”4. 使用方法与 AOT 避坑指南4.1 显式注册元数据在 AOT 模式下你需要从“全自动”切换为“显式声明”。首先定义你的JsonSerializerContext[JsonSerializable(typeof(MessageModelstring))] [JsonSerializable(typeof(MessageModelSummaryResponse))] [JsonSerializable(typeof(SummaryResponse))] [JsonSerializable(typeof(LoginRequest))] [JsonSerializable(typeof(UserConfigWrapper))] internal partial class WebAppAotJsonContext : JsonSerializerContext { }4.2 初始化配置在Program.cs中完成“户口登记”与“岗位培训”builder.Services.ConfigureHttpJsonOptions(options { // 1. 设置元数据解析器户口登记 options.SerializerOptions.TypeInfoResolver WebAppAotJsonContext.Default; // 2. 注册业务模型到工厂岗位培训 MessageModelJsonConverterFactory.RegisterSummaryResponse(); MessageModelJsonConverterFactory.Registerstring(); // 3. 添加转换器 options.SerializerOptions.Converters.Add(new MessageModelJsonConverterFactory()); });4.3 警惕“裸奔”的 JsonSerializer 调用这是最容易踩坑的地方。在 AOT 环境下如果你手动调用JsonSerializer例如写入本地配置文件绝对不能使用单参数的重载版本否则会因为尝试反射而报错。❌ 错误写法// 直接崩溃Reflection-based serialization has been disabled var json JsonSerializer.Serialize(myObject);✅ 正确写法// 必须显式递交“准入证”TypeInfo var json JsonSerializer.Serialize( new UserConfigWrapper(configUser), WebAppAotJsonContext.Default.UserConfigWrapper );5. 总结Native AOT 是 .NET 发展的必然趋势。虽然它要求开发者从“反射驱动”转向“显式声明”增加了一定的手动注册工作但带来的极致启动速度和低内存占用是显著的。在 AOT 的世界里编译器不再允许“撞运气”的行为。Sang.AspNetCore.CommonLibraries的这次更新正是为了帮助开发者在享受 AOT 红利的同时依然能保留优雅的一致性返回体验。如果你正在尝试将应用迁移到 Native AOT欢迎参考我仓库中的示例项目进行实践。