5步掌握System.Text.Json：ASP.NET Core Web API中的高效JSON处理

admin

2025年3月22日 7:58 本文热度 133

在现代软件开发中，JSON（JavaScript Object Notation）作为一种轻量级的数据交换格式，被广泛应用于前后端交互、配置文件管理以及分布式系统间的数据传输。System.Text.Json 是 .NET Core 3.0 及更高版本中引入的高性能 JSON 处理库，提供了序列化和反序列化的功能，并且与 .NET 平台深度集成, 在 ASP.NET Core Web API 中是默认的 JSON 序列化和反序列化库，用于处理 HTTP 请求和响应中的 JSON 数据。

1. 配置 `System.Text.Json`

在 ASP.NET Core 项目中，可以通过 Startup.cs 或 Program.cs 配置 System.Text.Json 的行为。以下是一些常见的配置选项：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers()
        .AddJsonOptions(options =>
        {
            // 配置 JSON 序列化选项
            options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase; // 使用驼峰式命名
            options.JsonSerializerOptions.WriteIndented = true; // 格式化输出
            options.JsonSerializerOptions.Encoder = JavaScriptEncoder.Create(UnicodeRanges.All); // 取消 Unicode 编码
            options.JsonSerializerOptions.IgnoreNullValues = true; // 忽略空值
            options.JsonSerializerOptions.AllowTrailingCommas = true; // 允许尾随逗号
            options.JsonSerializerOptions.PropertyNameCaseInsensitive = true; // 反序列化时不区分大小写
        });
}

2. 序列化和反序列化

序列化

在控制器中返回对象时，System.Text.Json 会自动将其序列化为 JSON：

[HttpGet]
public IActionResult Get()
{
    var user = new { Name = "张三", Age = 30 };
    return Ok(user); // 自动序列化为 JSON
}

需要手动序列化，可以使用 JsonSerializer.Serialize：

var user = new { Name = "张三", Age = 30 };
string jsonString = JsonSerializer.Serialize(user);
return Ok(jsonString);

反序列化

在接收 JSON 数据时，System.Text.Json 会自动将其反序列化为对象。例如，通过 [FromBody] 接收请求体中的 JSON 数据：

[HttpPost]
public IActionResult Post([FromBody] User user)
{
    return Ok(user);
}

需要手动反序列化，可以使用 JsonSerializer.Deserialize：

string jsonString = await new StreamReader(Request.Body).ReadToEndAsync();
var user = JsonSerializer.Deserialize<User>(jsonString);
return Ok(user);

3. 高级用法

自定义转换器

需要对特定类型进行自定义序列化或反序列化，可以实现 JsonConverter<T> 并注册到 JsonSerializerOptions 中：

public classCustomDateTimeConverter : JsonConverter<DateTime>
{
    public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return DateTime.Parse(reader.GetString());
    }

    public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)
    {
        writer.WriteStringValue(value.ToString("yyyy-MM-dd"));
    }
}

services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.Converters.Add(new CustomDateTimeConverter());
    });

使用 `JsonDocument` 和 `JsonNode`

在某些场景下，可能需要动态处理 JSON 数据，而不是直接映射到实体类。可以使用 JsonDocument 或 JsonNode：

string jsonString = await new StreamReader(Request.Body).ReadToEndAsync();
using JsonDocument doc = JsonDocument.Parse(jsonString);
var name = doc.RootElement.GetProperty("Name").GetString();
return Ok(name);

或者使用 JsonNode：

JsonNode node = JsonNode.Parse(jsonString);
var name = node["Name"].GetValue<string>();
return Ok(name);

4. 全局配置

在 Web API 中，可以通过 JsonSerializerOptions 配置全局的 JSON 处理行为。例如，设置日期格式：

services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.Converters.Add(new DateTimeConverter());
    });

其中，DateTimeConverter 是自定义的日期格式转换器。

5. 性能优化

从 .NET 8 开始，System.Text.Json 支持源生成（Source Generation），可以在编译时生成优化的序列化和反序列化代码：

[JsonSerializable(typeof(User))]
[JsonSourceGenerationOptions(WriteIndented = true, PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
public partial class JsonContext : JsonSerializerContext
{
}