CodeGym /課程 /C# SELF /設定序列化( JsonSerializerOptions)

設定序列化( JsonSerializerOptions)

C# SELF
等級 45, 課堂 3
開放

1. 介紹

如果你的需求跟預設行為一致,那就很棒。但實務上常常客戶(或第三方後端)會要求嚴格的格式:到處都是 camelCase、日期要用 ISO 8601、要忽略 null、要自訂 converters,還有一堆整合時會遇到的要求。

這時候我們的新朋友登場 —— 類別 JsonSerializerOptions。

如果把序列化比作廚房,這個類別就是你的調味料、鍋碗與秘密配方,讓你可以依照口味調整序列化行為。

如何使用 JsonSerializerOptions

要自訂序列化或反序列化流程,只要把設定物件傳給 serializer 的方法:

using System.Text.Json;

var options = new JsonSerializerOptions
{
    // 這裡放你的設定
};

string json = JsonSerializer.Serialize(myObject, options);
var obj = JsonSerializer.Deserialize<MyType>(json, options);

這個模式很常見:你建立 JsonSerializerOptions,按自己需要調整(見下文),然後傳進 Serialize/Deserialize 方法。

重要:同一個 JsonSerializerOptions 物件可以(而且通常建議)重複使用於多次序列化/反序列化。

2. JsonSerializerOptions 的基本設定

我們來看這個類別最常用的幾個「旋鈕」和「開關」。

JSON 格式化 — WriteIndented

單行的 JSON 讓眼睛不舒服?沒關係,打開漂亮縮排!

var options = new JsonSerializerOptions
{
    WriteIndented = true // 美觀的「人類可讀」JSON
};

var person = new Person { Name = "Anna", Age = 30 };
string json = JsonSerializer.Serialize(person, options);

Console.WriteLine(json);

輸出:

{
  "Name": "Anna",
  "Age": 30
}

如果沒有 WriteIndented = true,你會得到單行的 {"Name":"Anna","Age":30}。生產環境常用精簡(minified)JSON(體積小),但除錯或日誌通常用格式化的。

命名規則 — PropertyNamingPolicy

API 常要求屬性名稱使用 camelCase(例如 firstName 而不是 FirstName)。在 .NET 裡屬性通常用 PascalCase,這時候可以用 PropertyNamingPolicy:

var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

var person = new Person { Name = "Oleg", Age = 25 };
string json = JsonSerializer.Serialize(person, options);
Console.WriteLine(json); // {"name":"Oleg","age":25}

如果需要自訂風格(例如全大寫),可以實作自己的 JsonNamingPolicy。大部分情況下 CamelCase 就夠用了。

3. 忽略屬性

是否忽略 null 值 — DefaultIgnoreCondition

有時候你想讓值為空(null)的欄位完全不出現在 JSON 裡。原因可能是想要更小的 JSON,或是外部系統不支援 null。

為此使用屬性 DefaultIgnoreCondition:

using System.Text.Json.Serialization;

var options = new JsonSerializerOptions
{
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};

var person = new Person { Name = null, Age = 22 };
string json = JsonSerializer.Serialize(person, options);
Console.WriteLine(json); // {"Age":22}

如果你想不只忽略 null,還要忽略預設值(例如 int=0),可以用 WhenWritingDefault:

options.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault;

包含欄位(fields)與 [JsonInclude]

預設只序列化具有公開 setter 的 public 屬性。如果你想也序列化 fields,可以啟用:

var options = new JsonSerializerOptions
{
    IncludeFields = true
};

類別範例:

public class Item
{
    public string Name;
    public int Id { get; set; }
}

var item = new Item { Name = "Book", Id = 12 };
string json = JsonSerializer.Serialize(item, options);
// {"Name":"Book","Id":12}

若要序列化 private fields/屬性,可以使用屬性 [JsonInclude],但那是另一堂課的內容。

4. 值的轉換

日期格式化 — Converters

預設 System.Text.Json 會把日期序列化成 ISO 8601(例如 "2023-12-27T15:30:45.123Z"),這通常很方便。但有時候日期/時間格式要特別指定。

這時會加入自訂的 converter。下面是一個基本範例:

using System.Text.Json;
using System.Text.Json.Serialization;

public class CustomDateTimeConverter : JsonConverter<DateTime>
{
    private string _format = "yyyyMMdd";

    public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        var date = reader.GetString();
        return DateTime.ParseExact(date, _format, null);
    }

    public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)
    {
        writer.WriteStringValue(value.ToString(_format));
    }
}

// 使用 converter
var options = new JsonSerializerOptions();
options.Converters.Add(new CustomDateTimeConverter());

var dateObj = new { Date = new DateTime(2022, 1, 5) };
string json = JsonSerializer.Serialize(dateObj, options); // {"Date":"20220105"}

5. 實用小技巧

反序列化時忽略屬性大小寫 — PropertyNameCaseInsensitive

var options = new JsonSerializerOptions
{
    PropertyNameCaseInsensitive = true
};

var json = "{\"name\":\"Vasya\",\"age\":33}";
var person = JsonSerializer.Deserialize<Person>(json, options);
// person.Name == "Vasya"

控制巢狀深度 — MaxDepth

var options = new JsonSerializerOptions
{
    MaxDepth = 32 // 預設是 64
};

如果你的物件可能有無限深度(例如父子互相參照的樹),最好重新設計模型,而不是只靠提高 MaxDepth。

JSON 註解處理 — ReadCommentHandling(反序列化)

JSON 官方不支援註解,但有時會遇到帶有 // 註解的「創意」檔案。

var options = new JsonSerializerOptions
{
    ReadCommentHandling = JsonCommentHandling.Skip
};

string json = "{\n  \"Name\": \"Ivan\", // 使用者名稱\n  \"Age\": 30\n}";
var person = JsonSerializer.Deserialize<Person>(json, options);

特殊字元支援 — Encoder

有時你想控制序列化時如何 escape 字元(例如不要把西里爾字母轉成 \uXXXX)。你可以指定自己的 encoder:

using System.Text.Encodings.Web;

var options = new JsonSerializerOptions
{
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
};

小心使用,否則 emoji / 其他字元可能會被轉成 Unicode 序列,影響閱讀或兼容性。

6. 設定序列化時的常見錯誤

錯誤 №1:忘記公開 setter。 欄位或屬性不會被序列化,因為它沒有公開的 setter,或是它是 private 的。

錯誤 №2:錯誤地忽略 null 值。 當啟用 DefaultIgnoreCondition 時,值為 null 的屬性不會出現在 JSON 裡,可能不是你預期的行為。

錯誤 №3:日期格式不正確。 日期不是你想要的格式 —— 加上自訂 converter(JsonConverter)。

錯誤 №4:期望固定的屬性順序。 JSON 標準不保證欄位順序。如果 API 要求嚴格排序,只好改模型或用第三方庫來處理。

錯誤 №5:序列化與反序列化使用不同的設定。 如果寫與讀沒用相同的 JsonSerializerOptions,會出現問題,例如命名大小寫或格式不一致。

2
任務
C# SELF, 等級 45, 課堂 3
上鎖
設定 JSON 日期格式
設定 JSON 日期格式
留言
TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION