C# Post端点可选属性支持null/空列表更新的实现方案咨询
核心问题本质
常规可选属性的设计只能区分两种状态:「属性存在」、「属性不存在」,但实际需要的是三种独立状态:
- 请求未传递该字段:不对原资源的对应属性做任何改动
- 请求显式传递该字段:不管传入的是具体值、null、空集合,都按传入值覆盖原属性
之前用固定特殊值(比如-1、特定字符串)做标记的方式,本质是硬编码预留特殊语义,不仅容易和业务实际有效值冲突,对集合类型也无法适配。额外加布尔标志位的方式又会成倍增加请求体属性数量,不符合精简设计要求。
通用实现:泛型可设置状态包装器
这套方案不需要额外新增冗余属性,核心是通过值类型的状态包装器,从序列化层直接区分三种状态,适配基础类型、字符串、集合等所有类型:
- 针对未传递的字段:包装器处于「未设置」状态,不触发任何更新逻辑
- 针对显式传递的字段:不管传入值是null、空值、具体业务值,包装器都会处于「已设置」状态,携带实际传入值,触发对应更新逻辑
首先定义泛型包装器结构,必须使用值类型(struct),利用struct的默认值特性区分未设置状态:
public readonly struct Updateable<T> { /// <summary> /// 标记当前字段是否被请求体显式传递 /// </summary> public bool HasValue { get; } /// <summary> /// 请求体传递的实际值 /// </summary> public T? Value { get; } private Updateable(bool hasValue, T? value) { HasValue = hasValue; Value = value; } /// <summary> /// 未传递字段时的默认状态 /// </summary> public static Updateable<T> NotSet => new(false, default); /// <summary> /// 传递了字段时的状态,与传入值无关 /// </summary> public static Updateable<T> FromValue(T? value) => new(true, value); // 隐式转换支持,减少日常使用的样板代码 public static implicit operator Updateable<T>(T? value) => FromValue(value); }
序列化层适配
默认JSON序列化逻辑无法直接识别上述包装器的状态,需要针对项目使用的JSON序列化器做最小适配:
适配System.Text.Json(.NET Core/.NET 5+内置默认序列化器)
编写自定义JsonConverter,利用System.Text.Json的内置触发规则完成状态识别:只要请求JSON中存在对应属性名,序列化器就会触发对应Converter的Read方法;如果JSON中完全没有该属性,序列化器会直接取类型的默认值(也就是我们定义的NotSet状态),不会进入Read逻辑,完美匹配状态区分需求。
public class UpdateableJsonConverter<T> : JsonConverter<Updateable<T>> { public override Updateable<T> Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) { // 能进入Read方法,说明当前字段在JSON中是显式存在的 var parsedValue = JsonSerializer.Deserialize<T>(ref reader, options); return Updateable<T>.FromValue(parsedValue); } public override void Write(Utf8JsonWriter writer, Updateable<T> value, JsonSerializerOptions options) { // 序列化响应时如果是未设置状态,可按业务需求选择跳过或输出空值 if (!value.HasValue) { writer.WriteNullValue(); return; } JsonSerializer.Serialize(writer, value.Value, options); } }
最后在全局Json配置中注册该Converter即可,不需要每个属性单独配置。
适配Newtonsoft.Json(.NET Framework/老版本项目常用序列化器)
实现逻辑和System.Text.Json完全一致:自定义JsonConverter,判断JSON节点是否存在对应属性名,存在则标记为已设置状态并解析实际值,不存在则返回NotSet默认状态。
实际使用方式
改造原有请求DTO时,仅需要把原有属性的类型替换为Updateable<T>,不需要新增任何额外标志位,DTO的精简度和原设计完全一致:
public class UpdateUserRequest { // 未传该字段则不更新用户名;传null则清空用户名;传具体值则更新为对应值 public Updateable<string> UserName { get; set; } = Updateable<string>.NotSet; // 未传该字段则不更新年龄;传null则清空年龄;传具体值则更新为对应值 public Updateable<int> Age { get; set; } = Updateable<int>.NotSet; // 未传该字段则不更新标签;传null/空列表[]则清空标签;传具体列表则更新为对应值 public Updateable<List<string>> Tags { get; set; } = Updateable<List<string>>.NotSet; }
端点内的更新逻辑也只需要判断HasValue标记即可,不需要硬编码特殊值判断:
[HttpPost("user/update")] public async Task<IActionResult> UpdateUser(UpdateUserRequest request) { var currentUser = await _userRepository.GetByIdAsync(CurrentUserId); // 仅在字段被显式传递时执行覆盖操作 if (request.UserName.HasValue) { currentUser.UserName = request.UserName.Value; } if (request.Age.HasValue) { currentUser.Age = request.Age.Value; } if (request.Tags.HasValue) { // 不管传入的是空列表、null还是具体值,都直接覆盖对应属性 currentUser.Tags = request.Tags.Value; } await _userRepository.SaveChangesAsync(); return Ok(); }
常见注意事项
- 包装器必须使用struct值类型实现,不能用class引用类型:引用类型的默认值是null,无法和「请求显式传null」的状态做区分,值类型的默认值刚好可以对应NotSet状态
- 集合类型的空列表
[]和null都是合法的已设置状态:只要JSON中出现了对应属性名,哪怕值是空列表,都会被识别为需要执行更新的操作,完全解决列表类型的更新判定难题 - 该方案对所有类型通用:基础值类型、字符串、自定义对象、集合类型都可以直接用
Updateable<T>包装,不需要为不同类型单独写判定逻辑
内容的提问来源于stack exchange,提问作者Ravindra Sinare

