Spring Boot 文件上传需用 @ModelAttribute 绑定 MultipartFile 与业务字段，配置 multipart 大小限制，服务层校验类型、重命名并存储，Postman 测试须用 form-data 格式。
Spring Boot 实现文件上传 REST 接口，关键在于正确解析 multipart/form-data 请求、合理组织参数绑定、做好校验与存储分离，并配置必要的大小限制。不是写个 @PostMapping 就完事，而是要兼顾可用性、安全性和可维护性。
控制器必须用 @ModelAttribute 绑定混合数据
当上传文件同时携带业务字段（如 userId、type、description）时：
- 不能用
@RequestBody——MultipartFile不支持 JSON 反序列化 - 必须用
@ModelAttribute，搭配自定义请求模型类 - 模型类字段包含
MultipartFile file和其他普通字段（Long userId、String description等） - 推荐用 Lombok 的
@Getter/@Setter简化代码
application.yml 中配好上传限制
Spring Boot 2.0+ 默认启用 multipart 支持，但默认限制太小（1MB），必须显式配置：
-
spring.servlet.multipart.max-file-size=10MB：单个文件最大体积 -
spring.servlet.multipart.max-request-size=20MB：整个请求（含多个文件+表单字段）最大体积 - 单位支持
KB、MB；不写单位默认为字节 - 如需更精细控制（如内存阈值），可手动注册
MultipartConfigElementBean
服务层负责校验、重命名和存储
控制器只做接收和转发，真正逻辑下沉到 service：
- 检查
file.isEmpty()和file.getSize()是否超限 - 校验
file.getContentType()（例如只允许image/jpeg、application/pdf） - 生成唯一文件名：用
UUID.randomUUID()+ 原扩展名，避免覆盖或路径遍历 - 存储方式按需选择：
file.transferTo()保存到本地磁盘、对接 MinIO / 阿里云 OSS / AWS S3 - 文件元数据（原始名、大小、存储路径、归属用户 ID）应单独存入数据库
Postman 测试要注意格式细节
调试阶段最容易出错的是请求格式不匹配：
- 方法选
POST，URL 填接口地址（如/api/v1/files/image） - Body →
form-data，Key 填字段名（如file、userId），Value 对应选文件或输文本 - 不要手动设置
Content-Type—— Postman 会自动生成带boundary的完整头 - 响应状态码要有区分：
200成功、400文件为空/类型不符、413超限、500存储失败
