ASP.NET Core WebAPI中PUT请求如何判断JSON属性是否被设置

在ASP.NET Core WebAPI的PUT场景里，这个问题确实很常见——默认的类反序列化会把“未传的属性”和“传了null的属性”都设为null（引用类型），导致我们没法区分客户端的真实意图。下面是几种实用的解决方案，按推荐度排序：

方案一：自定义Optional<T>类型（最优推荐） #

这种方式通过包装类型来追踪属性是否被显式设置，类型安全且代码可读性高。

首先定义一个通用的Optional<T>类，用来记录属性的设置状态：

public class Optional<T>
{
    public bool IsSet { get; private set; }
    private T _value;
    
    public T Value
    {
        get => _value;
        set
        {
            _value = value;
            IsSet = true;
        }
    }

    // 隐式转换，方便直接使用Value值
    public static implicit operator T(Optional<T> optional) => optional.Value;
}

然后在你的请求模型中，用Optional<T>代替原来的属性类型：

public class UpdateUserRequest
{
    // 初始化空的Optional实例，默认IsSet为false
    public Optional<string> Name { get; set; } = new Optional<string>();
    // 对于值类型，比如int，包装成可空值类型+Optional，区分“传了0”“传了null”“没传”
    public Optional<int?> Age { get; set; } = new Optional<int?>();
}

最后在API接口里，就可以通过IsSet属性判断客户端的意图：

[HttpPut("users/{id}")]
public IActionResult UpdateUser(int id, [FromBody] UpdateUserRequest request)
{
    // 处理Name字段
    if (request.Name.IsSet)
    {
        if (request.Name.Value == null)
        {
            // 客户端明确把Name设置为null
            _userRepository.ClearUserName(id);
        }
        else
        {
            // 客户端设置了新的Name值
            _userRepository.UpdateUserName(id, request.Name.Value);
        }
    }
    else
    {
        // 客户端没传Name字段，保持数据库中原有值不变
    }

    // 处理Age字段
    if (request.Age.IsSet)
    {
        if (request.Age.HasValue)
        {
            _userRepository.UpdateUserAge(id, request.Age.Value.Value);
        }
        else
        {
            _userRepository.ClearUserAge(id);
        }
    }

    return Ok();
}

方案二：直接解析原始JSON文档 #

如果你不想自定义类型，可以先把请求体解析为JsonDocument，手动检查属性是否存在，再映射到模型。这种方式适合字段较少的场景：

[HttpPut("users/{id}")]
public async Task<IActionResult> UpdateUser(int id)
{
    // 解析原始请求体为JsonDocument
    using var jsonDoc = await JsonDocument.ParseAsync(Request.Body);
    var rootElement = jsonDoc.RootElement;

    var updateModel = new UpdateUserRequest();

    // 检查Name属性是否存在
    if (rootElement.TryGetProperty("Name", out var nameProp))
    {
        updateModel.Name = nameProp.GetString();
        // 这里说明客户端明确传了Name，不管值是null还是具体字符串
    }
    else
    {
        // 客户端没传Name，不修改原有值
    }

    // 同理处理其他属性
    return Ok();
}

方案三：利用JSON序列化器的扩展特性（适合进阶场景） #

如果你使用System.Text.Json，可以自定义JsonConverter或者利用JsonExtensionData来捕获所有传入的属性，然后对比模型的默认值。不过这种方式相对复杂，适合需要全局处理的场景：

比如用JsonExtensionData来收集所有传入的JSON属性键值对：

public class UpdateUserRequest
{
    public string Name { get; set; }
    public int? Age { get; set; }

    // 存储所有传入的JSON属性键值对
    [JsonExtensionData]
    public IDictionary<string, JsonElement> ExtraData { get; set; } = new Dictionary<string, JsonElement>();

    // 判断属性是否被传入的方法
    public bool IsPropertySet(string propertyName)
    {
        return ExtraData.ContainsKey(propertyName);
    }
}

然后在接口里：

[HttpPut("users/{id}")]
public IActionResult UpdateUser(int id, [FromBody] UpdateUserRequest request)
{
    if (request.IsPropertySet("Name"))
    {
        // 客户端传了Name字段
    }
    else
    {
        // 没传
    }
    return Ok();
}

不过要注意，JsonExtensionData会收集所有模型中未定义的属性，同时也会收集已定义的属性，所以可以用来判断是否存在。

总结一下，Optional<T>模式是最清晰、最类型安全的解决方案，推荐在大多数PUT/PATCH场景中使用。

内容的提问来源于stack exchange，提问作者Frederik Nygaard Svendsen