ファイルとマルチパート
@RequestPart パラメーターを持つメソッドは、パラメーターごとに一つのパートを持つ multipart/form-data のボディを送ります。ファイル、テキストのフィールド、JSON のパートです。MultipartFile はコントローラーが受け取るのと同じ型なので、コントローラーが受け取ったファイルをそのまま渡せます。
使う理由
アップロード (表紙の画像、メタデータを伴う文書) には、境界、コンテンツタイプ、ファイル名を持つマルチパートのボディが必要です。手で書くと面倒ですが、@RequestPart で宣言すれば、クライアントが引数からそれを組み立てます。
例
@FeignClient('catalog', url: r'${catalog.url}')
abstract interface class CatalogFiles {
// 本の表紙をその説明とともにアップロードする。
@PostMapping.of(path: '/books/{isbn}/files', consumes: MediaType.multipartFormData)
Future<UploadResult> upload(
@PathVariable() String isbn,
@RequestPart('file') MultipartFile file, // ファイルのパート
@RequestPart('meta') FileMeta meta, // オブジェクト: JSON のパート
@RequestPart('note') String? note, // テキストのフィールド。null なら省かれる
@RequestParam('draft') bool draft, // これはクエリパラメーターのまま: ?draft=false
);
}
await files.upload(
'978-0',
InMemoryMultipartFile('file', bytes, originalFilename: 'cover.png'),
FileMeta(title: 'Cover'),
'first edition',
false,
);
パート
@RequestPart('x') パラメーター |
パート |
|---|---|
MultipartFile |
ファイル。そのファイル名とコンテンツタイプはファイルから来る (なければ型はファイル名から推測され、それもなければ application/octet-stream)。パートは file.name ではなく、アノテーションにちなんで名付けられる。 |
List<MultipartFile> |
ファイルごとに一つのファイルのパート。すべて x という名前。 |
Uint8List、List<int> |
ファイル名のないファイルのパート (application/octet-stream)。 |
String、数値、bool、列挙型、DateTime (またはそれらの List) |
テキストのフィールド (項目ごとに一つ)。クエリパラメーターと同じく書かれる。 |
オブジェクト、Map、オブジェクトの List |
クライアントの ObjectMapper で書かれる JSON のパート (application/json)。 |
InMemoryMultipartFileは、バイトから、またはInMemoryMultipartFile.fromStringでテキストからファイルを作ります。- nullable なパラメーターは、
nullならそのパートを省きます。 consumes: MediaType.multipartFormDataは任意です。それ以外のconsumesは起動時にアプリケーションを止めます。@RequestParam、@RequestHeader、@PathVariableは他のメソッドと同じく動きます。Spring Cloud OpenFeign と同じく、@RequestParamはクエリに残ります。Content-Typeはmultipart/form-data; boundary=...です。@RequestPartと@RequestBodyの両方を持つメソッドや、@RequestPartと別のアノテーションを持つパラメーターは、起動時にアプリケーションを止めます。
ボディの組み立て方
ボディは呼び出しごとに一度メモリ上で組み立てられ、各ファイルは一度だけ読まれるため、リトライは同じバイトを送ります。ストリーミングのアップロードはまだありません。非常に大きなファイルは、呼び出しの間メモリに保持されます。
Spring (Java) との対応
@PostMapping(value = "/books/{isbn}/files", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
UploadResult upload(@PathVariable String isbn, @RequestPart("file") MultipartFile file);
アノテーションは同じです。@RequestPart の中の単なる値のリストは、項目ごとに一つのテキストのフィールドとして送られます。