Newtonsoft.Json 序列化属性详解：控制JSON序列化的艺术

蓬为宜

于 2025-06-03 09:12:28 发布

阅读量356

点赞数 3

本文链接：https://blog.csdn.net/gitblog_01113/article/details/148394260

版权

Newtonsoft.Json 序列化属性详解：控制JSON序列化的艺术

Newtonsoft.Json Json.NET is a popular high-performance JSON framework for .NET 项目地址: https://gitcode.com/gh_mirrors/ne/Newtonsoft.Json

前言

在现代.NET开发中，JSON序列化是系统间数据交换的核心技术。Newtonsoft.Json作为.NET生态中最流行的JSON处理库，提供了丰富的特性来控制序列化过程。其中，序列化属性(Serialization Attributes)是最常用且强大的功能之一，它允许开发者精细控制对象如何被转换为JSON以及如何从JSON重建对象。

标准.NET序列化属性与Newtonsoft.Json

Newtonsoft.Json不仅支持自身的专有属性，还能识别标准的.NET序列化属性：

SerializableAttribute：标记可序列化的类
DataContractAttribute/DataMemberAttribute：WCF风格的序列化控制
NonSerializedAttribute：标记不应序列化的字段

重要提示：当Newtonsoft.Json属性与标准.NET属性同时存在时，Newtonsoft.Json属性具有更高优先级。例如，如果同时使用JsonPropertyAttribute和DataMemberAttribute指定属性名，将采用JsonPropertyAttribute的命名。

Newtonsoft.Json核心序列化属性详解

1. JsonObjectAttribute：类级别的序列化控制

JsonObjectAttribute用于控制整个类的序列化行为：

MemberSerialization：指定成员序列化模式
- OptIn：只有显式标记的成员才会被序列化
- OptOut：默认模式，所有公共成员都会被序列化(除非显式忽略)
- Fields：序列化所有字段(包括私有字段)，忽略属性

[JsonObject(MemberSerialization.OptIn)]
public class User
{
    [JsonProperty] // 只有标记的才会被序列化
    public string Name { get; set; }
    
    public int Age { get; set; } // 不会被序列化
}

NamingStrategy：可设置命名策略，如驼峰式、蛇形命名等
对于实现了IEnumerable的类，默认会序列化为JSON数组，使用此属性可强制序列化为对象

2. JsonArrayAttribute/JsonDictionaryAttribute：集合类型控制

这两个属性专门用于集合类型：

JsonArrayAttribute：明确指定类应序列化为JSON数组
JsonDictionaryAttribute：明确指定类应序列化为JSON对象(字典)

[JsonDictionary(NamingStrategyType = typeof(SnakeCaseNamingStrategy))]
public class CustomDictionary : Dictionary<string, string>
{
    // 会使用蛇形命名法序列化键名
}

3. JsonPropertyAttribute：属性级精细控制

这是最常用的属性，功能丰富：

自定义属性名：允许JSON属性名与.NET属性名不同
控制可见性：可序列化非公共属性
空值处理：自定义null值的处理方式
默认值：设置默认值行为
类型处理：控制类型名称和引用处理
命名策略：为单个属性设置命名策略

public class Product
{
    [JsonProperty("product_name")] // 自定义JSON属性名
    public string Name { get; set; }
    
    [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
    public decimal Price { get; set; }
}

4. JsonIgnoreAttribute：排除序列化

简单直接地排除字段或属性：

public class Account
{
    public string Username { get; set; }
    
    [JsonIgnore] // 密码不会被序列化
    public string Password { get; set; }
}

5. JsonConverterAttribute：自定义转换逻辑

允许为类或属性指定自定义转换器：

[JsonConverter(typeof(CustomDateTimeConverter))]
public class Event
{
    public DateTime Date { get; set; }
}

// 或者在属性级别应用
public class LogEntry
{
    [JsonConverter(typeof(UnixDateTimeConverter))]
    public DateTime Timestamp { get; set; }
}

6. JsonExtensionDataAttribute：处理额外数据

用于捕获JSON中不存在于类定义中的额外属性：

public class Person
{
    public string Name { get; set; }
    
    [JsonExtensionData]
    public IDictionary<string, JToken> AdditionalData { get; set; }
}

7. JsonConstructorAttribute：自定义构造逻辑

指定反序列化时应使用的构造函数：

public class Rectangle
{
    public int Width { get; }
    public int Height { get; }
    
    [JsonConstructor]
    public Rectangle(int width, int height)
    {
        Width = width;
        Height = height;
    }
}