Files and multipart
A method with @RequestPart parameters sends a multipart/form-data body, one part per parameter: files, text fields and JSON parts. MultipartFile is the same type controllers receive, so a file a controller received can be passed on as it is.
Why
Uploads (a cover image, a document with its metadata) need a multipart body with boundaries, content types and file names. Written by hand it is fiddly; declared with @RequestPart, the client builds it from the arguments.
Example
@FeignClient('catalog', url: r'${catalog.url}')
abstract interface class CatalogFiles {
// Uploads a book's cover with its description.
@PostMapping.of(path: '/books/{isbn}/files', consumes: MediaType.multipartFormData)
Future<UploadResult> upload(
@PathVariable() String isbn,
@RequestPart('file') MultipartFile file, // a file part
@RequestPart('meta') FileMeta meta, // an object: a JSON part
@RequestPart('note') String? note, // a text field; left out when null
@RequestParam('draft') bool draft, // still a query parameter: ?draft=false
);
}
await files.upload(
'978-0',
InMemoryMultipartFile('file', bytes, originalFilename: 'cover.png'),
FileMeta(title: 'Cover'),
'first edition',
false,
);
Parts
@RequestPart('x') parameter |
Part |
|---|---|
MultipartFile |
A file. Its file name and content type come from the file (else the type is guessed from the file name, else application/octet-stream). The part is named after the annotation, not after file.name. |
List<MultipartFile> |
One file part per file, all named x. |
Uint8List, List<int> |
A file part without a file name (application/octet-stream). |
String, numbers, bool, enums, DateTime (or a List of them) |
A text field (one per item), written as query parameters are. |
an object, a Map, a List of objects |
A JSON part (application/json), written with the client's ObjectMapper. |
InMemoryMultipartFilebuilds a file from bytes, or from text withInMemoryMultipartFile.fromString.- A nullable parameter leaves its part out for
null. consumes: MediaType.multipartFormDatais optional; any otherconsumesstops the application at startup.@RequestParam,@RequestHeaderand@PathVariablework as on any other method;@RequestParamstays in the query, as in Spring Cloud OpenFeign.- The
Content-Typeismultipart/form-data; boundary=.... - A method with both
@RequestPartand@RequestBody, or a parameter with@RequestPartand another annotation, stops the application at startup.
How the body is built
The body is built in memory once per call, reading each file once, so retries send the same bytes. There is no streaming upload yet: very large files are held in memory during the call.
In Spring (Java)
@PostMapping(value = "/books/{isbn}/files", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
UploadResult upload(@PathVariable String isbn, @RequestPart("file") MultipartFile file);
The same annotations. A list of plain values in a @RequestPart is sent as one text field per item.