Spring Boot如何接收内含文件对象的数组类型请求体

前提说明 #

你要接收的请求包含二进制文件字段，所以请求必须使用multipart/form-data类型，无法直接通过JSON格式（@RequestBody）传递。

步骤1：定义单条数据的DTO #

首先创建一个DTO类，对应数组中的每个元素结构：

import org.springframework.web.multipart.MultipartFile;

public class FileItemDTO {
    // 对应请求中的普通字段name
    private String name;
    // 对应请求中的文件字段file
    private MultipartFile file;

    // 以下是Getter和Setter
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public MultipartFile getFile() {
        return file;
    }
    public void setFile(MultipartFile file) {
        this.file = file;
    }
}

步骤2：调整Multipart配置（可选，默认开启） #

Spring Boot默认已经开启multipart支持，仅需要调整文件大小限制时修改application.yml即可：

spring:
  servlet:
    multipart:
      enabled: true
      max-file-size: 10MB # 单个文件最大大小，按需调整
      max-request-size: 100MB # 整个请求最大大小，按需调整

步骤3：编写Controller接收逻辑 #

使用@ModelAttribute绑定参数即可直接接收数组/列表结构的数据：

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;

@RestController
public class FileUploadController {

    @PostMapping("/upload/batch")
    public String batchUpload(@ModelAttribute List<FileItemDTO> fileItems) {
        // 遍历即可获取所有普通字段和文件对象
        for (FileItemDTO item : fileItems) {
            String name = item.getName();
            MultipartFile file = item.getFile();
            // 自定义文件处理逻辑，比如转存本地、上传到对象存储等
            // file.transferTo(...)
        }
        return "处理完成，共接收" + fileItems.size() + "条数据";
    }
}

前端传参要求 #

multipart/form-data没有原生数组结构，需要按索引规则传递键名，示例如下：

• 第1条数据：键名fileItems[0].name传值fileName，键名fileItems[0].file传文件二进制内容
• 第2条数据：键名fileItems[1].name传值fileName，键名fileItems[1].file传文件二进制内容
• 以此类推

Axios请求示例：

const formData = new FormData();
const fileList = [file1, file2, file3]; // 你的文件列表
fileList.forEach((file, index) => {
  formData.append(`fileItems[${index}].name`, 'fileName');
  formData.append(`fileItems[${index}].file`, file);
});

axios.post('/upload/batch', formData, {
  headers: {
    'Content-Type': 'multipart/form-data'
  }
});

常见问题排查 #

• 参数绑定为空：检查前端传递的键名前缀是否和Controller参数名完全一致（示例中参数名是fileItems，键名必须以fileItems[索引]开头）
• 列表绑定失败：低版本Spring MVC可以把参数类型换成FileItemDTO[] fileItems数组格式，兼容性更好
• 文件大小超限：对应调整yaml配置中的大小限制即可

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