Asp.Net Core 5.0 Web API多部分表单提交包含文件与复杂数组的模型绑定问题

我之前也碰到过完全一样的问题，默认的[FromForm]模型绑定不会自动解析你直接输入的JSON字符串——因为它期望的是表单字段格式而非JSON格式。下面给你两种可行的解决方案，按需选择：

方案一：使用表单索引式字段命名（推荐标准表单提交方式） #

ASP.NET Core的模型绑定支持通过索引来识别列表项，你只需要按照Items[N].PropertyName的格式提交表单字段，模型绑定器就会自动把这些字段映射到List<Item>中。

提交格式示例（以FormData为例） #

在Postman或Swagger的表单中，添加以下键值对：

• Surname: "Doe"
• FamilyName: "Jane"
• Image: 选择你要上传的文件
• Items[0].Value: "Item-001"
• Items[0].Description: "第一个测试项"
• Items[1].Value: "Item-002"
• Items[1].Description: "第二个测试项"

你的控制器代码不需要修改，保持原来的[FromForm] Person p即可，模型绑定会自动解析出完整的Items列表。

方案二：将列表序列化为JSON字符串提交（适合前端序列化场景） #

如果前端更方便把列表序列化为JSON字符串，你可以在模型中添加一个辅助属性接收JSON，再在控制器中手动反序列化为List<Item>。

步骤1：修改模型 #

public class Person { 
    public string Surname { get; set; } 
    public string FamilyName { get; set; } 
    public IFormFile Image { get; set; } 
    // 新增辅助属性，用于接收JSON字符串
    public string ItemsJson { get; set; }
    // 保持原有的Items列表
    public List<Item> Items { get; set; } = new List<Item>(); 
}

public class Item { 
    public string Value { get; set; } 
    public string Description { get; set; } 
}

步骤2：修改控制器动作 #

using System.Text.Json;

[HttpPost] 
public ActionResult Post([FromForm] Person p) { 
    // 解析JSON字符串到Items列表
    if (!string.IsNullOrEmpty(p.ItemsJson))
    {
        try
        {
            p.Items = JsonSerializer.Deserialize<List<Item>>(p.ItemsJson);
        }
        catch (JsonException ex)
        {
            ModelState.AddModelError("ItemsJson", "Items的JSON格式无效");
            return BadRequest(ModelState);
        }
    }

    if (ModelState.IsValid) { 
        return Ok(); 
    } 
    return BadRequest(ModelState); 
}

提交格式示例 #

在Swagger的ItemsJson输入框中，输入以下JSON数组：

[{"Value":"Item-001","Description":"第一个测试项"},{"Value":"Item-002","Description":"第二个测试项"}]

优化Swagger UI体验 #

默认的Swagger UI不会自动显示Items的子字段（方案一的场景），你可以添加一个自定义操作过滤器，让Swagger生成对应的表单输入项：

添加操作过滤器 #

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

public class AppendFormFieldOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 只处理FromForm类型的请求
        var isFormRequest = context.ApiDescription.ParameterDescriptions
            .Any(p => p.Source == BindingSource.Form);
        
        if (!isFormRequest) return;

        // 生成Item的Schema
        var itemSchema = context.SchemaGenerator.GenerateSchema(typeof(Item), context.SchemaRepository);
        
        // 添加2个示例列表项的表单字段（可根据需要调整数量）
        for (int i = 0; i < 2; i++)
        {
            foreach (var property in itemSchema.Properties)
            {
                operation.RequestBody.Content["multipart/form-data"].Schema.Properties.Add(
                    $"Items[{i}].{property.Key}",
                    property.Value
                );
            }
        }
    }
}

在Startup.cs中注册过滤器 #

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API", Version = "v1" });
    // 注册自定义过滤器
    c.OperationFilter<AppendFormFieldOperationFilter>();
});

这样Swagger UI就会显示Items[0].Value、Items[0].Description等输入框，方便你直接测试。

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