Newtonsoft.Json如何忽略空值字段不序列化？

Question

在使用 Newtonsoft.Json 进行对象序列化时，常遇到的问题是：如何忽略值为 null 的属性，避免其出现在生成的 JSON 字符串中？默认情况下，JsonConvert.SerializeObject 会包含所有公共属性，包括 null 值字段，导致输出冗余或不符合 API 接口规范。虽然可通过全局设置 `JsonSerializerSettings` 中的 `NullValueHandling = NullValueHandling.Ignore` 来控制，但在某些场景下，部分字段仍意外输出 null，尤其当对象嵌套较深或使用匿名类型时。此外，特性 `[JsonProperty(NullValueHandling = NullValueHandling.Ignore)]` 作用于单个属性的方式也容易因疏漏而失效。如何正确配置序列化选项，确保所有 null 字段均被有效忽略？

Answer 1

一、Newtonsoft.Json 序列化中忽略 null 值属性的深度解析

1. 问题背景与常见现象

在使用 Newtonsoft.Json 进行对象序列化时，开发者常面临一个核心痛点：如何有效忽略值为 null 的属性，避免其出现在最终生成的 JSON 字符串中。默认情况下，JsonConvert.SerializeObject 方法会包含所有公共属性，即使其值为 null，这不仅造成数据冗余，还可能违反 API 接口设计规范（如 RESTful API 要求精简响应体）。

例如，以下 C# 对象：

public class User
{
    public string Name { get; set; }
    public string Email { get; set; }
    public Address HomeAddress { get; set; }
}

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

当 HomeAddress 为 null 时，默认序列化结果如下：

{"Name":"John","Email":null,"HomeAddress":null}

显然，Email 和 HomeAddress 的 null 值并无实际意义，应被排除。

2. 解决方案层级一：全局配置序列化设置

最基础且广泛使用的策略是通过 JsonSerializerSettings 全局控制 null 值处理行为。

var settings = new JsonSerializerSettings
{
    NullValueHandling = NullValueHandling.Ignore
};

string json = JsonConvert.SerializeObject(user, settings);
    

该设置将作用于整个对象图，包括嵌套对象。但需注意：此设置不会影响已显式标记为包含 null 的属性，即若某属性使用了 [JsonProperty(NullValueHandling = NullValueHandling.Include)]，则仍会输出 null。

3. 解决方案层级二：特性驱动的细粒度控制

对于需要更精细控制的场景，可使用 [JsonProperty] 特性标注特定属性。

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

    [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
    public Address HomeAddress { get; set; }
}
    

此方式适用于字段级定制，但在大型项目中易因遗漏而导致部分 null 字段泄露。此外，若与全局设置冲突，以特性优先级为准。

4. 深层嵌套与匿名类型的挑战

当对象结构复杂或涉及匿名类型时，null 值可能“穿透”配置而显现。例如：

var data = new {
    User = user,
    Metadata = (object)null
};
    

即使设置了全局 NullValueHandling.Ignore，匿名类型中的 null 属性仍可能被序列化。这是因为匿名类型的序列化行为受限于运行时反射机制，且不支持特性标注。

5. 综合解决方案：统一配置 + 自定义 ContractResolver

为彻底解决深层嵌套与动态类型的 null 输出问题，推荐结合自定义 ContractResolver 实现自动化过滤。

public class NullFilterContractResolver : DefaultContractResolver
{
    protected override JsonProperty CreateProperty(MemberInfo member, MemberSerialization memberSerialization)
    {
        var property = base.CreateProperty(member, memberSerialization);
        property.NullValueHandling = NullValueHandling.Ignore;
        return property;
    }
}
    

然后在设置中应用：

var settings = new JsonSerializerSettings
{
    ContractResolver = new NullFilterContractResolver(),
    NullValueHandling = NullValueHandling.Ignore
};

6. 配置优先级与行为验证流程图

以下是 Newtonsoft.Json 中 null 值处理的决策流程：

graph TD
    A[开始序列化属性] --> B{属性是否有[JsonProperty]?}
    B -- 是 --> C{NullValueHandling 是否指定?}
    C -- 是 --> D[使用指定的NullValueHandling]
    C -- 否 --> E[使用全局NullValueHandling]
    B -- 否 --> F{全局设置NullValueHandling?}
    F -- 是 --> E
    F -- 否 --> G[使用默认行为(Include)]
    D --> H[输出或忽略null]
    E --> H
    G --> H
    

7. 实际应用场景对比表

场景	推荐方案	优点	缺点
简单对象，统一规则	全局 NullValueHandling.Ignore	配置简单，一致性高	无法差异化控制
关键字段需保留 null	特性 + 全局设置	灵活可控	维护成本高
深度嵌套/匿名类型	自定义 ContractResolver	全面拦截 null	需编码扩展
高性能要求场景	预编译 ContractResolver 缓存	减少反射开销	实现复杂
DTO 映射层	AutoMapper + JsonIgnore 条件	解耦业务与序列化逻辑	引入额外依赖

8. 常见陷阱与规避建议

• 误以为 DefaultValueHandling.Ignore 等同于 null 忽略 —— 实际它仅针对属性的默认值（如 int=0），而非 null。
• 忽略 JObject 或 JToken 类型在序列化链中的影响，可能导致中间结构保留 null。
• 在 ASP.NET Web API 中未正确注册全局序列化设置，导致 MVC/WebAPI 使用默认配置。
• 使用 dynamic 类型时，Newtonsoft.Json 无法提前构建契约模型，null 控制失效风险增高。

9. 高级技巧：条件性忽略 null

通过重写 ShouldSerialize* 方法，实现运行时判断逻辑：

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

    public bool ShouldSerializeTempData()
    {
        return !string.IsNullOrEmpty(TempData);
    }
}
    

此方法在序列化期间被自动调用，返回 false 则跳过该属性，即使其非 null。

10. 总结性实践清单（Checklist）

1. 确认是否启用全局 NullValueHandling.Ignore
2. 检查关键属性是否被错误地标记为强制包含 null
3. 评估是否需引入自定义 ContractResolver
4. 对匿名类型输出进行单元测试验证
5. 在集成环境中测试嵌套对象的序列化行为
6. 考虑使用 ShouldSerializeXXX 方法增强灵活性
7. 避免在 DTO 中暴露不必要的可空属性
8. 利用 AutoMapper 或其他映射工具做前置清洗
9. 监控生产环境 JSON 输出大小与结构合规性
10. 文档化团队统一的序列化规范