ASP.NET Core反序列化HTTP响应为IEnumerable报JsonException如何解决

抛出JsonException: The JSON value could not be converted to System.Collections.Generic.IEnumerable<MyProject.Models.MyClass>. Path: $ | LineNumber: 0 | BytePositionInLine: 1的直接原因是：接口返回的JSON内容根节点不是数组类型，和IEnumerable<MyClass>的反序列化目标类型不匹配。
错误位置标记在第0行第1个字节，也就是JSON内容的第一个字符位置：JSON规范中数组以[开头，对象以{开头，当你直接把根节点为{的JSON对象反序列化为集合类型时，就会在第一个字符处触发类型转换错误。
Postman请求成功仅代表接口可正常访问，不代表返回结构是直接的数组格式——绝大多数对外接口会用统一包装格式返回数据，比如结构为{"code":200,"msg":"success","data":[/* 实际的MyClass数组数据*/]}，真正的数组数据存放在内层字段（通常是data）中，而非JSON根节点。
其他少量触发场景包括：响应流带UTF-8 BOM头、JSON开头存在多余非JSON字符、序列化时属性名大小写匹配规则未配置。

1. 先确认真实响应结构 #

在反序列化逻辑前临时加代码读取原始响应字符串，下断点或打日志查看完整返回内容，不要只依赖Postman的可视化展示：

// 调试用，确认原始JSON结构
string rawJson = await httpResponseMessage.Content.ReadAsStringAsync();

2. 按实际结构调整反序列化逻辑 #

场景A：响应为带内层数组的包装对象 #

先定义和接口返回匹配的通用包装类，再读取内层数组字段，同时配置序列化选项兼容大小写、命名风格差异：

// 通用接口响应包装类，属性名和接口返回字段对应即可
public class ApiResponse<T>
{
    public int Code { get; set; }
    public string Msg { get; set; }
    public T Data { get; set; }
}

[HttpGet]
public async Task<IEnumerable<MyClass>> GetAsync()
{
    var httpRequestMessage = new HttpRequestMessage(
        HttpMethod.Get,
        "https://xxx/api/123")
    {
        Headers =
        {
            { HeaderNames.Authorization, "password" },
        }
    };

    var httpClient = _httpClientFactory.CreateClient();
    var httpResponseMessage = await httpClient.SendAsync(httpRequestMessage);
    MyClasses = Enumerable.Empty<MyClass>();

    if (httpResponseMessage.IsSuccessStatusCode)
    {
        var jsonOptions = new JsonSerializerOptions
        {
            // 忽略属性名大小写匹配，适配接口返回的小驼峰字段
            PropertyNameCaseInsensitive = true,
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase
        };
        // 反序列化时目标类型改为包装类，泛型参数传入内层集合类型
        var apiResult = await httpResponseMessage.Content
            .ReadFromJsonAsync<ApiResponse<IEnumerable<MyClass>>>(jsonOptions);
        MyClasses = apiResult?.Data ?? Enumerable.Empty<MyClass>();
    }

    return MyClasses;
}

这里直接用HttpContent自带的ReadFromJsonAsync方法替代手动读取流的逻辑，会自动处理UTF-8 BOM、流编码等常见问题，减少手动读流的异常。

场景B：响应确实是数组，但带BOM/多余前缀字符 #

如果确认原始JSON根节点是[开头的数组，保留ReadFromJsonAsync写法即可，该方法会自动跳过开头的BOM字符和空白字符，不需要手动处理流。

额外排查点 #

• 检查接口响应头的Content-Type是否为application/json，如果返回XML或其他格式，需要用对应序列化器处理
• 如果MyClass的属性名和接口返回字段名不匹配，可以给属性加[JsonPropertyName("接口对应字段名")]特性指定映射关系
• 不要每次请求都new HttpClient，你当前用IHttpClientFactory创建客户端的写法是正确的，有固定配置的接口可以给HttpClient加命名配置，简化请求代码。

内容的提问来源于stack exchange，提问作者MaxK123