Spring Boot如何接收含文件的对象列表（multipart请求）

问题分析 #

你遇到的错误核心有两点：

1. DTO类名不匹配：定义的是Contacts记录，但PartnerRequest里用的是List<Contact>，类型不匹配会直接导致绑定失败。
2. Spring默认的@ModelAttribute绑定不支持contacts[0][name]这种方括号嵌套的属性路径格式，它默认使用点号（.）分隔属性，且未自动初始化列表元素，因此抛出属性获取异常。

解决方案 #

方案一：调整参数格式为Spring原生支持的形式（推荐） #

这是最简洁的解决方式，只需调整FormData的参数命名规则，配合少量配置即可实现自动绑定。

1. 修正DTO类名
   统一类名，避免类型不匹配：

public record Contact(
        String name,
        String email,
        MultipartFile icon
) {}

public record PartnerRequest(
        String name,
        MultipartFile logo,
        String link,
        List<Contact> contacts
){}

2. 添加Controller绑定配置
   在Controller中添加@InitBinder，开启嵌套路径自动增长并设置集合最大容量：

@InitBinder
public void initBinder(WebDataBinder binder) {
    // 允许自动增长嵌套对象路径
    binder.setAutoGrowNestedPaths(true);
    // 设置列表自动增长的最大元素数量，可根据业务调整
    binder.setAutoGrowCollectionLimit(100);
}

3. 调整FormData参数格式
   将方括号嵌套改为点号分隔属性：

function createFormData() {
    const formData = new FormData()

    formData.append('name', 'test')
    formData.append('logo', new File([''], 'test.png'))
    formData.append('link', 'test')

    // 改用点号分隔属性路径
    formData.append('contacts[0].name', 'test')
    formData.append('contacts[0].email', 'test')
    formData.append('contacts[0].icon', new File([''], 'test.png'))

    formData.append('contacts[1].name', 'test')
    formData.append('contacts[1].email', 'test')
    formData.append('contacts[1].icon', new File([''], 'test.png'))

    return formData
}

此时原Controller接口无需修改，@ModelAttribute会自动完成所有参数（包括文件）的绑定。

方案二：手动解析请求参数（适配原方括号格式） #

如果无法调整前端参数格式，可以手动解析请求中的所有参数，自行组装DTO对象：

@PostMapping(value = "createPartner", consumes = "multipart/form-data")
public ResponseEntity<String> createPartner(HttpServletRequest request) {
    // 解析基础参数
    String name = request.getParameter("name");
    MultipartFile logo = ((MultipartHttpServletRequest) request).getFile("logo");
    String link = request.getParameter("link");

    // 解析contacts列表
    List<Contact> contacts = new ArrayList<>();
    int index = 0;
    while (true) {
        // 尝试获取当前索引的联系人参数
        String contactName = request.getParameter("contacts[" + index + "][name]");
        if (contactName == null) {
            // 没有更多联系人时退出循环
            break;
        }
        String contactEmail = request.getParameter("contacts[" + index + "][email]");
        MultipartFile contactIcon = ((MultipartHttpServletRequest) request).getFile("contacts[" + index + "][icon]");
        
        contacts.add(new Contact(contactName, contactEmail, contactIcon));
        index++;
    }

    // 组装DTO
    PartnerRequest partnerRequest = new PartnerRequest(name, logo, link, contacts);
    
    // 后续业务逻辑处理
    return ResponseEntity.ok("请求处理成功");
}

这种方式无需依赖Spring的自动绑定，完全自定义解析逻辑，适合特殊格式的请求场景。

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