Java后端通过Spring Boot的@RequestPart接收FormData，需启用multipart支持、避免@RequestBody，并确保前端正确构造请求体。
Java后端如何接收前端传来的FormData
Java后端本身不直接“解析”浏览器 FormData，因为 FormData 是前端 JavaScript API，最终通过 HTTP 请求（通常是 POST）以 multipart/form-data 编码方式发送。后端真正处理的是这种 MIME 类型的请求体。
关键判断：如果你用的是 Spring Boot，默认已集成 CommonsMultipartResolver（旧版）或基于 Servlet 4.0+ 的原生 StandardServletMultipartResolver，只要配置得当，@RequestParam、@RequestPart 就能接住。
-
multipart/form-data请求必须配spring.servlet.multipart.enabled=true（Spring Boot 2.0+ 默认开启） - 单个文件大小限制由
spring.servlet.multipart.max-file-size控制，总请求体大小由spring.servlet.multipart.max-request-size控制 - 不要试图用
@RequestBody接收FormData—— 它只适用于application/json或text/plain等非文件类内容类型
Spring Boot 中用 @RequestPart 接收混合数据（文本 + 文件）
@RequestPart 是处理 multipart/form-data 中命名字段的标准方式，比 @RequestParam 更明确支持文件和 JSON 字符串混合提交。
常见错误：把 JSON 字符串字段用 @RequestParam 接收，结果中文乱码或解析失败 —— 因为 @RequestParam 默认按 ISO-8859-1 解码，而 @RequestPart 走的是 multipart 解析器，支持 UTF-8。
立即学习“Java免费学习笔记（深入）”；
@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) public ResponseEntityhandleUpload( @RequestPart("metadata") String metadataJson, @RequestPart("avatar") MultipartFile avatar) { // metadataJson 是普通字符串，可转为对象 // avatar.getInputStream() 可读取二进制内容 return ResponseEntity.ok("ok"); }
-
@RequestPart的 name 必须与前端FormData.append("metadata", ...)中的键完全一致 - 若
metadata是 JSON 对象，建议额外加@Valid和 DTO 类，而不是直接用String - 多个同名字段（如多图上传）可用
List接收，但需确保前端调用多次append("images", file1)、append("images", file2)
Apache Commons FileUpload 还需要手动引入吗
Spring Boot 2.0+ 默认不再依赖 commons-fileupload，改用 Servlet 容器原生 multipart 支持（Tomcat/Jetty/Undertow 均内置）。除非你有特殊需求（如自定义解析逻辑、兼容老版本 Tomcat 7），否则不需要引入 commons-fileupload。
容易踩的坑：
- 显式引入
commons-fileupload且版本与 Spring 不匹配，会导致java.lang.NoClassDefFoundError: org/apache/commons/fileupload/FileItemFactory - 在非 Spring 环境（如纯 Servlet/JSP 项目）中才需要手动配置
DiskFileItemFactory和ServletFileUpload - 若用 Netty（如 WebFlux），则根本不能用传统 multipart 解析器 —— WebFlux 使用
Flux，需改用@RequestPart Mono等响应式写法
前端 FormData 发送时后端收不到字段？检查这三点
不是后端问题，大概率是前端构造或发送方式不对。最常漏掉的三个点：
- fetch 或 axios 发送时没删掉
Content-Type头 —— 浏览器会自动设置正确的multipart/form-data; boundary=...，手动设了反而会失效，导致后端当成普通表单甚至application/x-www-form-urlencoded处理 - 用
new FormData(formElement)时，元素没有name属性，导致该字段根本不会被 append 进去 - Vue/React 组件中异步获取文件后未重新创建
FormData实例，而是复用旧实例（它内部是只读快照），导致新文件未生效
调试建议：用浏览器 DevTools 的 Network → Payload 查看实际发出的请求体结构，确认 boundary 是否存在、字段名是否拼写一致、文件字段是否有 content-type 和 filename。
