Java常用表单处理类库与FormData_技术教程

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。

@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity handleUpload(
    @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 实例，而是复用旧实例（它内部是只读快照），导致新文件未生效