System.Text.Json：从对接一个第三方 API 学起

{
  "order_id": "SF20260928",
  "receiver_name": "张三",
  "created_at": "2026-09-28 10:30:00",
  "remark": null,
  "packages": [
    { "pkg_no": 1, "weight_kg": 2.5 }
  ]
}

using System.Text.Json;

var order = new ShipmentOrder
{
    OrderId = "SF20260928",
    ReceiverName = "张三",
    CreatedAt = DateTime.Now,
};

// 对象 -> JSON 字符串
string json = JsonSerializer.Serialize(order);
Console.WriteLine(json);

// JSON 字符串 -> 对象（泛型版本显式标类型，非泛型版本省略）
ShipmentOrder? copy = JsonSerializer.Deserialize<ShipmentOrder>(json);
Console.WriteLine(copy!.ReceiverName);

record ShipmentOrder
{
    public string OrderId { get; set; } = "";
    public string ReceiverName { get; set; } = "";
    public DateTime CreatedAt { get; set; }
}

var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower, // .NET 8+ 内置 snake_case；.CamelCase 亦常用
    WriteIndented = true,                                   // 带缩进，人可读（日志/调试用）
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull, // null 属性不输出
    PropertyNameCaseInsensitive = true,                     // 反序列化时大小写不敏感
};
string json = JsonSerializer.Serialize(order, options);

var lenient = new JsonSerializerOptions
{
    ReadCommentHandling = JsonCommentHandling.Skip, // 跳过注释
    AllowTrailingCommas = true,
};

public class User
{
    [JsonPropertyName("user_name")]   // 单个属性改名，优先级高于命名策略
    public string Name { get; set; }

    [JsonIgnore]                      // 永不序列化（密码、内部字段）
    public string Password { get; set; }

    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    public string? Nick { get; set; } // 仅在为 null 时不输出

    [JsonPropertyOrder(0)]            // 控制输出顺序（默认按属性声明顺序）
    public int Id { get; set; }
}

using var fs = File.OpenRead("response.json");
var data = await JsonSerializer.DeserializeAsync<List<ShipmentOrder>>(fs);

using var outFs = File.Create("out.json");
await JsonSerializer.SerializeAsync(outFs, data);

public class CnDateTimeConverter : JsonConverter<DateTime>
{
    private const string Format = "yyyy-MM-dd HH:mm:ss";

    public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
        => DateTime.ParseExact(reader.GetString()!, Format, null);

    public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)
        => writer.WriteStringValue(value.ToString(Format));
}

[JsonDerivedType(typeof(Circle), "circle")]
[JsonDerivedType(typeof(Square), "square")]
public abstract class Shape { }

// JSON 里自动带类型鉴别符，反序列化能还原出正确子类
Shape shape = JsonSerializer.Deserialize<Shape>(json)!;

// JsonDocument：只读，用完要 Dispose
using var doc = JsonDocument.Parse(json);
string name = doc.RootElement.GetProperty("receiver_name").GetString()!;

// JsonNode：可读写
JsonNode node = JsonNode.Parse(json)!;
node["weight_total"] = 5.5;
string updated = node.ToJsonString();

// 也可以从零构造
var obj = new JsonObject { ["name"] = "Alice", ["age"] = 30 };

// 1. 声明上下文，登记参与的类型
[JsonSourceGenerationOptions(WriteIndented = true)]
[JsonSerializable(typeof(ShipmentOrder))]
public partial class AppJsonContext : JsonSerializerContext { }

// 2/3. 调用时把上下文的类型信息传进去
string json = JsonSerializer.Serialize(order, AppJsonContext.Default.ShipmentOrder);
var copy = JsonSerializer.Deserialize(json, AppJsonContext.Default.ShipmentOrder);