.net实体类如何转化为json

.NET 实体类转换为 JSON 的多种方法与实践指南**

在现代软件开发中，JSON（JavaScript Object Notation）因其轻量级、易读以及与 JavaScript 的天然亲和力，已成为数据交换的主流格式之一，在 .NET 应用程序中，我们经常需要将内存中的实体类对象序列化为 JSON 字符串，以便进行 API 交互、数据存储或配置文件读写，本文将详细介绍在 .NET 中将实体类转换为 JSON 的多种方法，包括官方推荐的 System.Text.Json 以及广泛使用的 Newtonsoft.Json（Json.NET），并探讨它们的使用场景、优缺点及最佳实践。

为什么需要将实体类转换为 JSON？

将实体类（POCO/Plain Old CLR Object）转换为 JSON 主要有以下目的：

API 通信：在 Web API 开发中，服务器端通常将数据实体序列化为 JSON 响应给客户端；客户端也将请求数据序列化为 JSON 发送给服务器。
数据持久化：虽然数据库是主要存储方式，但有时也会将对象序列化为 JSON 字符串存储在文本文件、NoSQL 数据库（如 MongoDB 的文档）或缓存中。
配置管理：JSON 格式的配置文件因其结构清晰而被广泛使用，应用程序启动时需要将 JSON 配置反序列化为相应的配置类。
跨平台/跨语言交互：JSON 是一种通用的数据格式，不同语言和平台的应用程序可以通过 JSON 进行数据交换。

使用 System.Text.Json（.NET 官方推荐）

从 .NET Core 3.0 开始，微软推出了 System.Text.Json 命名空间，作为 .NET 平台内置的 JSON 处理库，旨在提供高性能、低内存占用的 JSON 序列化和反序列化功能。

基本使用方法

确保你的项目已经引用了 System.Text.Json 程序集（在 .NET Core/.NET 5+ 中通常是默认包含的）。

示例实体类：

public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
    public List<string> Hobbies { get; set; }
}

序列化为 JSON 字符串：

using System.Text.Json;
using System.Text.Json.Serialization;
// 创建实体对象
var user = new User
{
    Id = 1,
    Name = "张三",
    Age = 30,
    Hobbies = new List<string> { "阅读", "编程", "旅行" }
};
// 配置选项（可选）
var options = new JsonSerializerOptions
{
    WriteIndented = true, // 格式化输出，使 JSON 更易读
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase // 属性名采用驼峰命名法
};
// 序列化为 JSON 字符串
string jsonString = JsonSerializer.Serialize(user, options);
Console.WriteLine(jsonString);

输出结果（当 WriteIndented = true 和 CamelCase 时）：

{
  "id": 1,
  "name": "张三",
  "age": 30,
  "hobbies": [
    "阅读",
    "编程",
    "旅行"
  ]
}

反序列化 JSON 字符串为实体类

string jsonInput = @"{""id"":2,""name"":""李四"",""age"":25,""hobbies"":[""音乐"",""运动""]}";
User deserializedUser = JsonSerializer.Deserialize<User>(jsonInput);
Console.WriteLine($"ID: {deserializedUser.Id}, Name: {deserializedUser.Name}");

System.Text.Json 的特点

高性能：通常比 Newtonsoft.Json 有更好的性能表现。
低依赖：.NET 内置，无需额外安装 NuGet 包（.NET Core 3.0+）。
与现代 .NET 特性集成：对 record 类型、源生成器（Source Generators）等有良好支持。
功能相对精简：相比 Newtonsoft.Json,一些高级特性可能需要额外配置或暂不支持。

使用 Newtonsoft.Json（Json.NET）

尽管 System.Text.Json 是官方推荐，但在 .NET Framework 旧项目或需要特定高级功能的场景中，Newtonsoft.Json（Json.NET）仍然是许多开发者的首选，它功能丰富,社区支持强大。

安装 NuGet 包

需要在项目中安装 Newtonsoft.Json 包：

Install-Package Newtonsoft.Json

基本使用方法

序列化为 JSON 字符串：

using Newtonsoft.Json;
// 创建实体对象（同上）
var user = new User
{
    Id = 1,
    Name = "张三",
    Age = 30,
    Hobbies = new List<string> { "阅读", "编程", "旅行" }
};
// 序列化为 JSON 字符串
string jsonString = JsonConvert.SerializeObject(user, Formatting.Indented); // Formatting.Indented 格式化输出
Console.WriteLine(jsonString);

输出结果：

{
  "Id": 1,
  "Name": "张三",
  "Age": 30,
  "Hobbies": [
    "阅读",
    "编程",
    "旅行"
  ]
}

反序列化 JSON 字符串为实体类

string jsonInput = @"{""Id"":2,""Name"":""李四"",""Age"":25,""Hobbies"":[""音乐"",""运动""]}";
User deserializedUser = JsonConvert.DeserializeObject<User>(jsonInput);
Console.WriteLine($"ID: {deserializedUser.Id}, Name: {deserializedUser.Name}");

Newtonsoft.Json 的特点

功能极其丰富：提供大量灵活的配置选项，如自定义序列化器、条件序列化、类型转换、支持动态对象等。
广泛的社区支持和文档：遇到问题容易找到解决方案。
良好的兼容性：支持 .NET Framework 和 .NET Core/.NET 5+。
性能略逊于 System.Text.Json：在某些场景下,性能可能不如官方库。

高级配置与常见场景

无论是使用 System.Text.Json 还是 Newtonsoft.Json,都会遇到一些需要特殊配置的情况：

处理循环引用：
- System.Text.Json：默认会抛出异常，可以在 JsonSerializerOptions 中设置 ReferenceHandler = ReferenceHandler.Preserve（.NET 6+）或使用 [JsonIdentityInfo] 特性。
- Newtonsoft.Json：默认会抛出异常，可以在 JsonSerializerSettings 中设置 ReferenceLoopHandling = ReferenceLoopHandling.Ignore（忽略）或 ReferenceLoopHandling.Serialize（序列化，配合 $id 和 $ref）。
自定义属性名/命名策略：
- System.Text.Json：使用 [JsonPropertyName("新名称")] 特性或 PropertyNamingPolicy。
- Newtonsoft.Json：使用 [JsonProperty("新名称")] 特性或 ContractResolver。
控制序列化/反序列化：
- System.Text.Json：使用 [JsonIgnore]（忽略属性）、[JsonInclude]（显式包含，用于只读属性）、[JsonRequired] 等特性。
- Newtonsoft.Json：使用 [JsonIgnore]、[JsonProperty] 的 NullValueHandling、DefaultValueHandling 等属性。
处理复杂类型和自定义转换器：当内置序列化器无法处理某些特殊类型时，可以自定义 JsonConverter 来实现特定的序列化和反序列化逻辑。

如何选择？

新建项目，使用 .NET Core 3.0 / .NET 5 / .NET 6+：优先考虑 System.Text.Json，它是未来的方向，性能好，且无需额外依赖，如果需要 Newtonsoft.Json 的高级功能,再考虑引入。
维护 .NET Framework 项目：继续使用 Newtonsoft.Json，因为 System.Text.Json 在 .NET Framework 中不可用（除非通过 Microsoft.AspNetCore.App 等方式引用，但不推荐）。
需要 Newtonsoft.Json 特有的高级功能：如复杂的 ContractResolver、特定的日期格式处理等，System.Text.Json 的配置无法满足，则使用 Newtonsoft.Json。