.NET Core Web API中FromQuery参数映射失败问题求助

以下是针对你的ASP.NET Core接口参数无法正确映射的排查方向：

1. 核对请求格式与接口约束 #

• 确认请求头的Content-Type必须为application/json，因为接口标注了[Consumes(MediaTypeNames.Application.Json)]，非JSON格式的请求会直接导致Body参数绑定失败。
• 验证Query参数的传递方式：必须将mapId和geoId放在URL查询串中（如/api/xxx/CreateMap?mapId=test001&geoId=geo002），同时Body部分提交标准JSON数组（如[{"Name":"Map1"},{"Name":"Map2"}]）。

2. 检查MapViewModel的序列化兼容性 #

• 确保MapViewModel的属性为public访问级别，且存在无参构造函数（ASP.NET Core默认依赖无参构造进行模型绑定）。
• 核对JSON字段与ViewModel属性的匹配度：如果JSON字段名和属性名不一致，需添加[JsonPropertyName]特性显式映射（如[JsonPropertyName("map_name")] public string Name { get; set; }）；若项目配置了大小写敏感的序列化规则，需保证字段大小写完全一致。

3. 查看模型验证错误详情 #

在接口方法中添加模型状态校验，直接输出错误信息定位问题：

public async Task<IActionResult> CreateMap([FromQuery, Required] string mapId,
                                           [FromQuery, Required] string geoId,
                                           [FromBody, Required] List<MapViewModel> mapsList)
{
    if (!ModelState.IsValid)
    {
        var errorDetails = string.Join("; ", ModelState.Values
            .SelectMany(v => v.Errors)
            .Select(e => e.ErrorMessage));
        return BadRequest(errorDetails);
    }
    throw new NotImplementedException();
}

发起请求后，查看返回的错误信息，可直接获取参数绑定失败的具体原因（如必填项缺失、类型不匹配等）。

4. 对比正常接口的配置差异 #

• 检查Program.cs/Startup.cs中的JSON序列化配置，确保与正常运行的接口一致：比如是否启用了JsonSerializerOptions.PropertyNameCaseInsensitive，是否有自定义的转换器或绑定器。
• 确认接口所在控制器的路由配置是否正确，避免路由冲突导致参数解析异常。

5. 排查测试工具的使用问题 #

• 若使用Postman/Swagger测试：确保Body选择raw格式并指定JSON，Query参数直接添加到URL的参数列表中，不要误将Query参数放到Body里。
• 检查Query参数是否存在URL编码问题，比如包含特殊字符时是否正确编码（如空格转%20）。

内容的提问来源于stack exchange，提问作者Aԃιƚყα Gυɾαʋ