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,會出現問題,例如命名大小寫或格式不一致。
GO TO FULL VERSION