Newtonsoft.Json序列化时如何忽略空值？

Question

在使用 Newtonsoft.Json 进行对象序列化时，如何忽略值为 null 的属性是一个常见需求。默认情况下，JsonConvert.SerializeObject 会包含所有属性，包括 null 值，导致生成的 JSON 不够简洁。许多开发者希望在不修改源对象的前提下，全局或局部控制序列化行为，仅输出非空字段。常见的疑问是：如何通过 JsonSerializerSettings 配置忽略 null 值？是否支持按属性粒度控制？以及该设置是否适用于嵌套对象和集合？这个问题在构建 API 返回数据或优化传输负载时尤为关键。

Answer 1

一、背景与问题引入

在现代Web开发中，尤其是基于RESTful API的系统设计中，数据序列化是前后端通信的核心环节。Newtonsoft.Json（又称Json.NET）作为.NET生态中最广泛使用的JSON序列化库之一，提供了强大的功能支持复杂对象结构的序列化与反序列化。

然而，默认情况下，JsonConvert.SerializeObject会将对象的所有公共属性输出到JSON字符串中，即使其值为null。这不仅增加了传输负载，还可能暴露不必要的字段信息，影响接口的整洁性与安全性。

二、基础解决方案：使用 JsonSerializerSettings 全局控制

最直接的方式是通过配置 JsonSerializerSettings 来全局忽略 null 值属性。该设置可在应用程序启动时统一注册，适用于所有调用场景。

var settings = new JsonSerializerSettings
{
    NullValueHandling = NullValueHandling.Ignore
};
var json = JsonConvert.SerializeObject(obj, settings);

上述代码中，NullValueHandling.Ignore 指示序列化器跳过所有值为 null 的属性。这是实现“仅输出非空字段”目标的基础手段。

三、深度解析：NullValueHandling 枚举选项

枚举值	行为描述
Include	默认行为，包含所有属性，包括null值
Ignore	跳过值为null的属性，不输出到JSON

四、嵌套对象与集合中的 null 处理机制

开发者常关心的问题是：该设置是否递归作用于嵌套对象和集合？答案是肯定的。

例如以下类结构：

public class Address
{
    public string Street { get; set; }
    public string City { get; set; }
}

public class Person
{
    public string Name { get; set; }
    public int? Age { get; set; }
    public Address HomeAddress { get; set; }
}

当 HomeAddress 为 null 时，整个属性将被忽略；若 HomeAddress.City 为 null，则该字段也不会出现在输出中。

五、粒度控制：按属性级别忽略 null 值

除了全局设置外，Newtonsoft.Json 支持通过特性（Attribute）进行细粒度控制。使用 [JsonProperty] 特性可指定单个属性的行为。

public class User
{
    public string Username { get; set; }

    [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
    public string Email { get; set; }

    [JsonProperty(NullValueHandling = NullValueHandling.Include)]
    public string Phone { get; set; }
}

此方式允许在同一对象中对不同属性应用不同的 null 处理策略，极大增强了灵活性。

六、高级应用场景与配置策略

在大型系统中，通常需要结合依赖注入容器（如ASP.NET Core的IServiceCollection）注册统一的序列化配置。

services.AddSingleton<IJsonSerializer>(sp => new JsonSerializer
{
    NullValueHandling = NullValueHandling.Ignore,
    MissingMemberHandling = MissingMemberHandling.Ignore,
    ReferenceLoopHandling = ReferenceLoopHandling.Serialize
});

此外，在中间件或ActionFilter中动态控制序列化行为也是一种常见模式。

七、流程图：序列化过程中 null 值处理逻辑

graph TD
            A[开始序列化对象] --> B{属性值是否为null?}
            B -- 是 --> C[检查NullValueHandling设置]
            C --> D{设置为Ignore?}
            D -- 是 --> E[跳过该属性]
            D -- 否 --> F[输出"property": null]
            B -- 否 --> G[正常序列化值]
            G --> H[继续下一个属性]
            E --> H
            H --> I{还有更多属性?}
            I -- 是 --> B
            I -- 否 --> J[完成JSON生成]

八、性能与最佳实践建议

• 对于高并发API服务，推荐启用全局 NullValueHandling.Ignore 以减少响应体积。
• 避免在DTO中暴露业务无关的可空字段，从源头减少null出现的可能性。
• 结合 [JsonIgnore] 与 [JsonProperty] 实现更精细的控制。
• 注意：忽略null可能导致前端误判字段缺失，需前后端约定明确。
• 测试覆盖各种边界情况，如深层嵌套、数组元素为null等。
• 考虑使用 System.Text.Json 替代方案时，注意其类似但略有差异的配置方式。
• 日志记录中建议保留原始对象结构，避免因忽略null导致调试困难。
• 文档化API返回结构时，应注明哪些字段可能因为空而不存在。
• 使用自动化测试验证序列化输出的一致性。
• 监控生产环境JSON大小变化趋势，评估优化效果。