ASP.NET Core中含文件与DTO的表单数据接口匹配问题

核心原因 #

ASP.NET Core的[FromForm]模型绑定默认仅处理键值对形式的表单字段，它不会自动将单个表单字段中的JSON字符串反序列化为复杂对象（比如你的FileMetaDataDto）。

为什么第一种请求能成功？ #

第一种请求把FileMetaDataDto的每个属性拆成了独立的表单字段（filename、version），ASP.NET Core的表单绑定器会自动将这些键值对映射到DTO的对应属性上（默认不区分大小写，所以filename能匹配FileName），因此绑定成功，接口可以正常命中。

为什么第二种请求失败？ #

第二种请求中，metaData字段是一个完整的JSON字符串，但[FromForm]绑定器只会把它当作普通字符串处理，不会尝试将其反序列化为FileMetaDataDto对象。这就导致绑定器无法找到匹配的DTO属性，最终模型绑定失败，接口无法正常接收请求。

解决方法 #

方法1：保持现有接口，按键值对传参 #

继续使用第一种请求方式，将DTO的每个属性作为独立表单字段传入，这是最简单的方案，适合DTO结构不复杂的场景。

方法2：修改接口支持JSON格式的表单字段 #

如果必须要传入整个JSON字符串作为单个表单字段，可以通过以下两种方式实现：

方式A：手动反序列化JSON字符串

修改接口参数，将metaData改为string类型，在方法内部手动将JSON字符串反序列化为FileMetaDataDto：

[HttpPost("upload")]
public async Task<IActionResult> UploadFile([FromForm]IFormFile file, [FromForm] string metaData)
{
    // 反序列化JSON字符串
    var metaDto = JsonSerializer.Deserialize<FileMetaDataDto>(metaData);
    
    // 验证反序列化结果
    if (metaDto == null)
    {
        return BadRequest("无效的元数据格式");
    }
    
    // 后续业务逻辑
    ...
}

方式B：自定义模型绑定器

通过自定义模型绑定器，让[FromForm]支持解析单个表单字段中的JSON：

1. 实现自定义模型绑定器：

public class JsonFormDataBinder : IModelBinder
{
    public Task BindModelAsync(ModelBindingContext bindingContext)
    {
        if (bindingContext == null)
            throw new ArgumentNullException(nameof(bindingContext));

        var value = bindingContext.ValueProvider.GetValue(bindingContext.ModelName);
        if (value == ValueProviderResult.None)
            return Task.CompletedTask;

        bindingContext.ModelState.SetModelValue(bindingContext.ModelName, value);
        var jsonString = value.FirstValue;

        if (string.IsNullOrWhiteSpace(jsonString))
            return Task.CompletedTask;

        try
        {
            // 反序列化JSON到目标模型
            var model = JsonSerializer.Deserialize(jsonString, bindingContext.ModelType);
            bindingContext.Result = ModelBindingResult.Success(model);
        }
        catch (JsonException ex)
        {
            // 记录反序列化错误
            bindingContext.ModelState.TryAddModelError(bindingContext.ModelName, $"JSON解析失败: {ex.Message}");
        }

        return Task.CompletedTask;
    }
}

2. 给FileMetaDataDto添加绑定器标记：

[ModelBinder(BinderType = typeof(JsonFormDataBinder))]
public class FileMetaDataDto
{
    public string FileName { get; set; }
    public string Version { get; set; }
}

3. 保持原接口不变，此时第二种请求就能正常命中接口，绑定器会自动将metaData字段的JSON字符串解析为FileMetaDataDto对象。

内容的提问来源于stack exchange，提问作者Q-bertsuit