Spring Boot多附件邮件API异常：Swagger提交后files数组为空

架构老林

2026-5-12

解决Spring Boot多附件上传时files参数为null的问题

看起来你在升级邮件API支持多附件时遇到了参数接收的问题，我来帮你梳理一下可能遗漏的关键点：

确认请求的Content-Type必须是multipart/form-data
上传文件的请求必须使用这个Content-Type，虽然Swagger在选择文件时通常会自动设置，但你可以在提交请求后检查请求头，确保这个属性正确配置。如果是自定义前端表单，也要确保form标签加上enctype="multipart/form-data"。
检查参数名与表单输入的name完全匹配
你的代码里用了@RequestParam(value = "files")，所以前端（包括Swagger）提交时，文件参数的name必须严格是files。如果Swagger里显示的参数名不符，可能需要调整注解或Swagger的配置。
尝试用@RequestPart替代@RequestParam
对于MultipartFile数组的接收，@RequestPart比@RequestParam更适配multipart场景，你可以修改参数注解试试：
```
@RequestPart(value = "files", required = false) MultipartFile[] files
```
这个注解专门用于处理multipart请求中的分段内容，对多文件上传的支持更稳定。
配置Swagger明确支持多文件上传
如果你的Swagger没有正确识别多文件参数，需要在参数上添加Swagger注解说明允许多选：
```
@ApiParam(value = "上传的多个附件", allowMultiple = true)
@RequestParam(value = "files", required = false) MultipartFile[] files
```
这样Swagger UI会生成支持多选的文件选择框，确保提交的参数格式符合后端要求。
确认Spring Boot的Multipart配置正常开启
虽然Spring Boot默认开启了multipart支持，但可以在application.properties里确认配置：
```
spring.servlet.multipart.enabled=true
spring.servlet.multipart.max-file-size=10MB
spring.servlet.multipart.max-request-size=10MB
```
确保没有禁用multipart功能，并且文件大小限制足够容纳你上传的附件。