ASP.NET Core Web API中如何区分模型绑定场景下的NULL与UNDEFINED

这个问题我之前做部分更新的PATCH接口时踩过坑——毕竟有时候我们得搞清楚：用户是主动要把某个字段设为null，还是压根没打算修改这个字段。下面给你几个实际项目里能用的解决方案：

1. 自定义Optional可空包装类型（首推） #

自己实现一个轻量的结构体，用来标记字段是被显式提交过（包括提交null）还是完全没提交。代码大概是这样：

[JsonConverter(typeof(OptionalJsonConverter<>))]
public struct Optional<T>
{
    public T Value { get; }
    public bool HasValue { get; }

    private Optional(T value)
    {
        Value = value;
        HasValue = true;
    }

    // 支持隐式转换，用起来和普通类型差不多
    public static implicit operator Optional<T>(T value) => new Optional<T>(value);

    // 表示未被设置的空状态
    public static Optional<T> Empty => new Optional<T>();
}

// 配套的JSON转换器，确保序列化/反序列化正常工作
public class OptionalJsonConverter<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 value;
    }

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

然后在你的请求模型里替换掉原来的可空类型：

public class UpdateProfileRequest
{
    public Optional<string?> Nickname { get; set; }
    public Optional<int?> Age { get; set; }
}

控制器里判断就很直观了：

[HttpPatch("profile")]
public IActionResult UpdateProfile([FromBody] UpdateProfileRequest request)
{
    if (request.Nickname.HasValue)
    {
        // 不管Value是不是null，都是客户端主动提交的字段
        if (request.Nickname.Value == null)
        {
            // 执行清空昵称的逻辑
        }
        else
        {
            // 用新昵称更新数据
        }
    }
    else
    {
        // 客户端没传Nickname，保持数据库里的原有值不变
    }

    return Ok();
}

这个方案的好处是类型安全，后续看代码的同事一眼就能明白字段的意图，不会踩坑。

2. 利用ModelState检查提交字段 #

ASP.NET Core的ModelState会保留请求里实际提交的所有字段信息，我们可以直接检查ModelState是否包含目标字段的键：

[HttpPatch("profile")]
public IActionResult UpdateProfile([FromBody] UpdateProfileRequest request)
{
    // 检查Nickname是否被客户端提交过
    bool nicknameWasSubmitted = ModelState.ContainsKey(nameof(UpdateProfileRequest.Nickname));

    if (nicknameWasSubmitted)
    {
        if (request.Nickname == null)
        {
            // 主动提交了null，要清空字段
        }
        else
        {
            // 更新字段为新值
        }
    }
    else
    {
        // 没提交这个字段，不做修改
    }

    return Ok();
}

这个方案适合快速实现简单场景，但如果是嵌套模型（比如Address.City），你需要用完整的路径作为键名（比如"Address.City"），复杂场景下容易出错。

3. 调整JSON序列化配置（辅助方案） #

如果你的API只处理JSON请求，可以配置System.Text.Json或Newtonsoft.Json的行为，配合前面的方案使用。比如让未提交的字段不覆盖模型的默认值：

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        // 序列化输出时忽略null值（可选，和区分逻辑无关，只是优化输出）
        options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
        // 确保反序列化时，未提交的属性保持结构体的默认状态（配合Optional<T>用）
        options.JsonSerializerOptions.PropertyNameCaseInsensitive = true;
    });

注意这个方法不能单独用来区分null和未提交，必须和前面的Optional或ModelState检查配合。

内容来源于stack exchange