多部分请求

在 启用 MultipartResolver 后，multipart/form-data 的 POST 请求内容会被解析并作为常规请求参数访问。以下示例访问一个常规表单字段和一个上传文件：

  • Java

  • Kotlin

@Controller
public class FileUploadController {

	@PostMapping("/form")
	public String handleFormUpload(@RequestParam("name") String name,
			@RequestParam("file") MultipartFile file) {

		if (!file.isEmpty()) {
			byte[] bytes = file.getBytes();
			// store the bytes somewhere
			return "redirect:uploadSuccess";
		}
		return "redirect:uploadFailure";
	}
}
@Controller
class FileUploadController {

	@PostMapping("/form")
	fun handleFormUpload(@RequestParam("name") name: String,
						@RequestParam("file") file: MultipartFile): String {

		if (!file.isEmpty) {
			val bytes = file.bytes
			// store the bytes somewhere
			return "redirect:uploadSuccess"
		}
		return "redirect:uploadFailure"
	}
}

将参数类型声明为 List<MultipartFile> 允许为相同的参数名解析多个文件。

当 @RequestParam 注解被声明为 Map<String, MultipartFile> 或 MultiValueMap<String, MultipartFile>，并且没有在注解中指定参数名时，该 Map 会填充每个给定参数名的多部分文件。

使用 Servlet 多部分解析，您也可以声明 jakarta.servlet.http.Part 而不是 Spring 的 MultipartFile 作为方法参数或集合值类型。

您还可以将多部分内容作为数据绑定的一部分，绑定到 命令对象。例如，前面示例中的表单字段和文件可以是表单对象上的字段，如下例所示：

  • Java

  • Kotlin

class MyForm {

	private String name;

	private MultipartFile file;

	// ...
}

@Controller
public class FileUploadController {

	@PostMapping("/form")
	public String handleFormUpload(MyForm form, BindingResult errors) {
		if (!form.getFile().isEmpty()) {
			byte[] bytes = form.getFile().getBytes();
			// store the bytes somewhere
			return "redirect:uploadSuccess";
		}
		return "redirect:uploadFailure";
	}
}
class MyForm(val name: String, val file: MultipartFile, ...)

@Controller
class FileUploadController {

	@PostMapping("/form")
	fun handleFormUpload(form: MyForm, errors: BindingResult): String {
		if (!form.file.isEmpty) {
			val bytes = form.file.bytes
			// store the bytes somewhere
			return "redirect:uploadSuccess"
		}
		return "redirect:uploadFailure"
	}
}

多部分请求也可以在 RESTful 服务场景中从非浏览器客户端提交。以下示例展示了一个包含 JSON 的文件：

POST /someUrl Content-Type: multipart/mixed

--edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp Content-Disposition: form-data; name="meta-data" Content-Type: application/json; charset=UTF-8 Content-Transfer-Encoding: 8bit

{ "name": "value" } --edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp Content-Disposition: form-data; name="file-data"; filename="file.properties" Content-Type: text/xml Content-Transfer-Encoding: 8bit …​ 文件数据 …​

您可以使用 @RequestParam 以 String 形式访问 "meta-data" 部分，但您可能希望将其从 JSON 反序列化（类似于 @RequestBody）。使用 @RequestPart 注解在通过 HttpMessageConverter 转换后访问多部分：

  • Java

  • Kotlin

@PostMapping("/")
public String handle(@RequestPart("meta-data") MetaData metadata,
		@RequestPart("file-data") MultipartFile file) {
	// ...
}
@PostMapping("/")
fun handle(@RequestPart("meta-data") metadata: MetaData,
		@RequestPart("file-data") file: MultipartFile): String {
	// ...
}

您可以将 @RequestPart 与 jakarta.validation.Valid 结合使用，或使用 Spring 的 @Validated 注解，两者都会导致应用标准 Bean 验证。默认情况下，验证错误会导致 MethodArgumentNotValidException，该异常会转换为 400 (BAD_REQUEST) 响应。或者，您可以通过 Errors 或 BindingResult 参数在控制器内部处理验证错误，如下例所示：

  • Java

  • Kotlin

@PostMapping("/")
public String handle(@Valid @RequestPart("meta-data") MetaData metadata, Errors errors) {
	// ...
}
@PostMapping("/")
fun handle(@Valid @RequestPart("meta-data") metadata: MetaData, errors: Errors): String {
	// ...
}

如果由于其他参数具有 @Constraint 注解而应用了方法验证，则会抛出 HandlerMethodValidationException。有关更多详细信息，请参阅 验证 部分。