You need to enable JavaScript to run this app. ASP.NET Web API如何改造接口兼容单对象与集合请求参数
优惠活动
大模型
产品
解决方案
定价
更多

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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.26 07:36:05