.NET 6 中 JsonNumberHandlingAttribute 对非数字集合属性的行为变更解析

.NET 6 中 JsonNumberHandlingAttribute 对非数字集合属性的行为变更解析

docs This repository contains .NET Documentation. 项目地址: https://gitcode.com/gh_mirrors/docs2/docs

前言

在 .NET 6 中，System.Text.Json 序列化库引入了一个关于 JsonNumberHandlingAttribute 的重要行为变更。这个变更主要影响了该特性在非数字类型集合属性上的使用方式。本文将详细解析这一变更的背景、影响范围以及开发者应如何应对。

JsonNumberHandlingAttribute 基础

JsonNumberHandlingAttribute 是 System.Text.Json 提供的一个特性，用于控制数字类型在 JSON 序列化和反序列化过程中的处理方式。它主要支持以下两种处理模式：

1. AllowReadingFromString：允许从字符串形式读取数字
2. WriteAsString：将数字以字符串形式写入

典型用法是将其应用于数字类型的属性或集合属性：

[JsonNumberHandling(JsonNumberHandling.AllowReadingFromString | JsonNumberHandling.WriteAsString)]
public List<int> MyNumbers { get; set; }

变更内容

在 .NET 6 之前，开发者可以将 JsonNumberHandlingAttribute 应用于任何集合属性，包括非数字类型的集合。虽然这些特性会被忽略，但不会引发错误。

// .NET 5 及以下版本允许但不生效
[JsonNumberHandling(JsonNumberHandling.AllowReadingFromString)]
public List<MyClass> MyObjects { get; set; }

从 .NET 6 开始，如果将此特性应用于非数字类型的集合属性（如上述示例中的 List<MyClass>），在尝试序列化或反序列化时将会抛出 InvalidOperationException 异常。

变更原因

这一变更是性能优化的副产品。在 .NET 6 中，System.Text.Json 团队对数字处理功能进行了性能优化，使得运行时能够更早地检测并验证 JsonNumberHandlingAttribute 的正确使用场景。

影响范围

这一变更属于二进制兼容性变更，会影响以下情况：

1. 现有代码中错误地将 JsonNumberHandlingAttribute 应用于非数字集合属性
2. 所有使用 JsonSerializer 进行序列化和反序列化的操作

解决方案

如果你的代码中出现了这种情况，解决方案很简单：

1. 检查所有使用了 JsonNumberHandlingAttribute 的集合属性
2. 确保这些属性确实是数字类型的集合（如 List<int>、int[] 等）
3. 从非数字集合属性上移除该特性

// 正确的用法 - 数字集合
[JsonNumberHandling(JsonNumberHandling.AllowReadingFromString)]
public List<decimal> Prices { get; set; }

// 错误的用法 - 非数字集合（需要移除特性）
public List<Product> Products { get; set; }

最佳实践

为了避免这类问题，建议：

1. 在代码审查时特别注意 JsonNumberHandlingAttribute 的使用场景
2. 编写单元测试验证序列化/反序列化行为
3. 升级到 .NET 6 后运行现有测试，检查是否有相关异常抛出

总结

.NET 6 对 JsonNumberHandlingAttribute 的行为进行了更严格的限制，这是为了提高性能并确保特性的正确使用。虽然这是一个破坏性变更，但影响范围有限，且修复方法简单直接。开发者应当检查现有代码，确保该特性仅应用于数字类型的集合属性。

docs This repository contains .NET Documentation. 项目地址: https://gitcode.com/gh_mirrors/docs2/docs