ファイルとマルチパート

@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)。

ボディの組み立て方

ボディは呼び出しごとに一度メモリ上で組み立てられ、各ファイルは一度だけ読まれるため、リトライは同じバイトを送ります。ストリーミングのアップロードはまだありません。非常に大きなファイルは、呼び出しの間メモリに保持されます。

Spring (Java) との対応

@PostMapping(value = "/books/{isbn}/files", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
UploadResult upload(@PathVariable String isbn, @RequestPart("file") MultipartFile file);

アノテーションは同じです。@RequestPart の中の単なる値のリストは、項目ごとに一つのテキストのフィールドとして送られます。

関連項目