多部分数据（Multipart）

Hunyuan 7b 中英对照 Multipart

请参见Reactive栈中的等效内容

在启用MultipartResolver后（详见../../mvc-servlet/multipart.md），带有multipart/form-data的POST请求的内容将被解析，并可以作为常规请求参数进行访问。以下示例访问了一个常规表单字段和一个上传的文件：

Java

@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";
	}
}

Kotlin

@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>类型时，如果在注解中未指定参数名称，则该映射会填充每个给定参数名称对应的多个部分文件（multipart files）。

备注

在使用Servlet的多部分数据解析时，你也可以使用jakarta.servlet.http.Part来代替Spring的MultipartFile，无论是作为方法参数还是集合值类型。

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

Java

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";
	}
}

Kotlin

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服务场景中，非浏览器客户端也可以提交多部分请求（multipart requests）。以下示例展示了一个包含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
... File Data ...

你可以使用@RequestParam将“元数据”部分作为String类型访问，但可能更希望将其从JSON中反序列化（类似于@RequestBody）。在通过HttpMessageConverter进行转换后，可以使用@RequestPart注解来访问多部分数据：

Java

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

Kotlin

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

你可以将@RequestPart与jakarta.validation.Valid结合使用，或者使用Spring的@Validated注解，这两种方式都会触发标准Bean Validation的验证。默认情况下，验证错误会引发MethodArgumentNotValidException异常，该异常会被转换为400（BAD_REQUEST）响应。另外，你也可以像以下示例所示，在控制器内部通过Errors或BindingResult参数来处理验证错误：

Java

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

Kotlin

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

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