,,

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

admin

2025年3月22日 7:58 本文熱度 258

在現代軟件開發中，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
{
}