ASP.NET Core模型绑定：区分属性省略与null/默认值

问题根源 #

你遇到的核心问题是：ASP.NET Core的JSON绑定系统在处理值类型（结构体）时，默认会用无参构造函数初始化实例。当客户端显式传入null时，绑定器不会触发自定义转换器逻辑，而是直接创建Optional<T>的默认实例（HasValue = false），导致无法区分“显式设为null”和“属性省略”两种场景。

可行解决方案 #

1. 针对Newtonsoft.Json的正确转换器实现 #

如果你的项目使用Newtonsoft.Json作为JSON序列化器，需要实现泛型版本的JsonConverter，确保只要JSON中存在该属性（哪怕值是null），就标记HasValue = true。

转换器代码

public class OptionalJsonConverter<T> : JsonConverter<Optional<T>>
{
    public override Optional<T> ReadJson(JsonReader reader, Type objectType, Optional<T> existingValue, bool hasExistingValue, JsonSerializer serializer)
    {
        // 只要JSON属性存在，就反序列化值并创建HasValue=true的实例
        var value = serializer.Deserialize<T>(reader);
        return new Optional<T>(value);
    }

    public override void WriteJson(JsonWriter writer, Optional<T> value, JsonSerializer serializer)
    {
        if (value.HasValue)
        {
            serializer.Serialize(writer, value.Value);
        }
        else
        {
            writer.WriteNull();
        }
    }

    public override bool CanWrite => true;
    public override bool CanRead => true;
}

更新Optional结构体特性

修改结构体的JsonConverter特性，指定泛型转换器：

[TypeConverter(typeof(OptionalConverter))]
[JsonConverter(typeof(OptionalJsonConverter<>))]
public readonly struct Optional<T>
{
    private readonly T _value;

    public T Value => _value;
    public bool HasValue { get; }

    public Optional(T value)
    {
        HasValue = true;
        _value = value;
    }

    public static implicit operator Optional<T>(T value) => new Optional<T>(value);
    public static explicit operator T(Optional<T> value) => value.Value;
}

配置Newtonsoft为默认序列化器

在Program.cs中确保注册Newtonsoft：

builder.Services.AddControllers()
    .AddNewtonsoftJson();

2. 针对System.Text.Json的解决方案（ASP.NET Core默认） #

如果使用默认的System.Text.Json，实现对应的泛型转换器：

转换器代码

public class OptionalSystemTextJsonConverter<T> : JsonConverter<Optional<T>>
{
    public override Optional<T> Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        var value = JsonSerializer.Deserialize<T>(ref reader, options);
        return new Optional<T>(value);
    }

    public override void Write(Utf8JsonWriter writer, Optional<T> value, JsonSerializerOptions options)
    {
        if (value.HasValue)
        {
            JsonSerializer.Serialize(writer, value.Value, options);
        }
        else
        {
            writer.WriteNullValue();
        }
    }
}

注册转换器

可以通过特性标记或全局注册：

// 方式1：特性标记Optional<T>
[JsonConverter(typeof(OptionalSystemTextJsonConverter<>))]
public readonly struct Optional<T> { /* 原有代码 */ }

// 方式2：全局注册（Program.cs）
builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        // 为需要的类型添加转换器，或通过反射批量注册所有Optional<T>
        options.JsonSerializerOptions.Converters.Add(new OptionalSystemTextJsonConverter<string>());
        options.JsonSerializerOptions.Converters.Add(new OptionalSystemTextJsonConverter<DateTime?>());
    });

3. 关键注意事项 #

• Optional<T>必须保持readonly struct，避免编译器生成额外的无参构造逻辑干扰。
• 不要依赖TypeConverter处理JSON绑定场景，它主要用于表单、路由参数等非JSON的模型绑定。
• 转换器的核心逻辑是：只要JSON中存在该属性，无论值是什么，都创建HasValue = true的实例；只有当属性完全不存在时，才使用结构体的默认值（HasValue = false）。

测试验证 #

发送PUT请求{"foo":"foo","bar":null}后，SomeDto实例会符合预期：

{
  Foo: { Value: "foo", HasValue: true },
  Bar: { Value: null, HasValue: true },
  Baz: { Value: null, HasValue: false }
}

内容的提问来源于stack exchange，提问作者Smockr