ASP.NET Web API如何改造接口兼容单对象与集合请求参数
兼容单对象/集合格式的API端点实现方案
可以实现同一端点同时兼容单个对象、集合格式的请求。默认反序列化逻辑无法直接适配的原因是:无论使用ASP.NET Web API默认的Newtonsoft.Json,还是.NET Core/.NET 5+默认的System.Text.Json,顶层遇到{}单对象格式时,反序列化IEnumerable<MyType>会直接抛出格式不匹配错误,需要自定义反序列化逻辑做兼容。
推荐实现方案:自定义JsonConverter(无侵入业务逻辑)
该方案不需要修改路由,直接保留改造后的IEnumerable<MyType>参数签名即可,通过自定义反序列化转换器统一处理两种请求格式。
转换器核心逻辑
- 读取请求体Json后先判断顶层token类型:
- 如果是数组
[,直接按集合格式反序列化 - 如果是对象
{,先反序列化单个MyType,再包装为仅含该元素的集合返回 - 兼容空值、空数组等边界场景
- 如果是数组
具体代码示例
1. 旧ASP.NET Web API(使用Newtonsoft.Json)实现
首先编写兼容单值/数组的通用转换器:
public class SingleOrArrayConverter<T> : JsonConverter { public override bool CanConvert(Type objectType) { return (objectType == typeof(IEnumerable<T>)); } public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer) { // 处理空请求体情况 if (reader.TokenType == JsonToken.Null) return Enumerable.Empty<T>(); // 集合格式直接反序列化 if (reader.TokenType == JsonToken.StartArray) return serializer.Deserialize<List<T>>(reader); // 单对象格式反序列化后包装为集合 if (reader.TokenType == JsonToken.StartObject) { var singleItem = serializer.Deserialize<T>(reader); return new List<T> { singleItem }; } throw new JsonSerializationException("无法处理的Json格式,仅支持单对象或数组集合"); } public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer) { // 接收请求场景不需要写逻辑,如需统一响应格式可在此扩展 throw new NotImplementedException(); } }
给接口参数标记该转换器即可:
[HttpPost, Route("DoSomething")] public async Task<IHttpActionResult> DoSomething( [FromBody, JsonConverter(typeof(SingleOrArrayConverter<MyType>))] IEnumerable<MyType> xxx, CancellationToken cancel) { // 原有业务逻辑不需要修改,直接处理集合即可 }
2. .NET Core/.NET 5+(使用System.Text.Json)实现
对应自定义转换器写法:
public class SingleOrArrayConverter<T> : JsonConverter<IEnumerable<T>> { public override IEnumerable<T> Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) { if (reader.TokenType == JsonTokenType.Null) return Enumerable.Empty<T>(); if (reader.TokenType == JsonTokenType.StartArray) return JsonSerializer.Deserialize<List<T>>(ref reader, options); if (reader.TokenType == JsonTokenType.StartObject) { var singleItem = JsonSerializer.Deserialize<T>(ref reader, options); return new List<T> { singleItem }; } throw new JsonException("仅支持单对象或数组集合的请求格式"); } public override void Write(Utf8JsonWriter writer, IEnumerable<T> value, JsonSerializerOptions options) { // 响应格式按需扩展 throw new NotImplementedException(); } }
参数标记方式和上述完全一致。
临时过渡备选方案
如果不想引入自定义转换器,也可以临时把参数类型改为JObject(Newtonsoft)或JsonElement(System.Text.Json),先判断请求格式是数组还是对象,分别反序列化后再统一传给业务逻辑处理。这种方案需要额外编写格式判断逻辑,复用性差,仅适合短期快速过渡。
注意事项
- 如果旧客户端可能发送空对象
{}或null,可在转换器里自定义边界处理逻辑,适配业务要求 - 过渡期结束后,直接移除参数上的
JsonConverter标记即可,不需要改动业务逻辑
内容的提问来源于stack exchange,提问作者pinale
相关产品推荐
相关产品推荐

