最常用方式是用MultipartFile[]接收同名多文件，需校验空值、大小、类型并生成唯一文件名；List更灵活；混合字段用@ModelAttribute封装DTO；须配置multipart大小限制并指定consumes。
用 MultipartFile 数组接收多个同名文件
这是最常见也最直接的方式，适用于前端通过 <input type="file" multiple> 或多次提交相同字段名（如 files）上传多个文件的场景。Spring Boot 会自动将同名的多个文件绑定为 MultipartFile[]。
- 控制器方法参数用
@RequestParam("files") MultipartFile[] files，字段名必须与前端表单中name属性一致 - 务必先判空：
if (files == null || files.length == 0)，避免空指针或无文件误提交 - 逐个校验每个文件：
file.isEmpty()、file.getSize()（建议限制单个文件不超过 10MB）、file.getContentType()（如只允许图片可校验image/*） - 保存时推荐生成唯一文件名（如
UUID.randomUUID() + "_" + file.getOriginalFilename()），防止重名覆盖或路径遍历风险
用 List 接收更灵活的多文件
和数组方式功能基本一致，但使用 List 在后续处理（如过滤、流式遍历、配合 Stream API）时更自然，也便于未来扩展（比如动态增删）。
- 参数写法：
@RequestParam("files") List<multipartfile> files</multipartfile> - 判空逻辑稍不同：
files == null || files.isEmpty() - 适合需要统一预处理（如按类型分组、跳过空文件、统计总大小）的业务场景
- 注意：若前端传的是单个文件，Spring 也能自动转成含一个元素的 List，兼容性比数组略好
混合数据场景：用 DTO 封装文件 + 其他字段
当上传多个文件的同时还需携带用户 ID、分类标签、描述等普通表单字段时，不能用 @RequestBody（MultipartFile 不支持 JSON 反序列化），必须用 @ModelAttribute。
- DTO 类中字段类型必须是
MultipartFile（不能是byte[]或InputStream），并配@Getter/@Setter - 控制器方法签名：
@PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE) public ResponseEntity> upload(@ModelAttribute UploadRequest request) -
UploadRequest示例：public class UploadRequest { private List<MultipartFile> files; private Long userId; private String category; // getter/setter } - 前端需确保所有字段都以
multipart/form-data形式提交，不能混用 JSON body
关键配置与避坑提醒
光写对代码还不够，几个底层配置直接影响能否成功上传：
- 在
application.yml中显式配置文件大小限制（默认仅 1MB，容易上传失败）：spring: servlet: context-path: /api servlet: multipart: max-file-size: 50MB max-request-size: 50MB - 接口必须声明
consumes = MediaType.MULTIPART_FORM_DATA_VALUE，否则 Spring 可能无法识别请求体格式 - 不要在同一个接口里混用
@RequestBody和@RequestParam（尤其是含文件时），会导致解析冲突 - 生产环境慎用本地磁盘存储；建议对接 MinIO、阿里云 OSS 或 AWS S3，并异步保存元数据到数据库
