アップロード

multipart/form-data のリクエストは、ファイルとフォームのフィールドを一つのボディで運びます。スターターはそれを読み、ファイルを一時ファイルに保持し、各パートをコントローラーのパラメーターにバインドします。MultipartFile、テキストのフィールド、生のバイト、または JSON から読んだオブジェクトです。

使う理由

enctype="multipart/form-data" のブラウザーのフォーム、curl -F、Flutter アプリ、Feign クライアントは、この方法でファイルを送ります。この形式を手で読むのは長く、間違えやすく、不注意な読み方はアップロード全体をメモリに保持したり、クライアントにディスクを埋めさせたりします。スターターは:

例

import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

class NewBook {
  const NewBook({required this.isbn, required this.title});

  @NotBlank()
  final String isbn;

  @NotBlank()
  final String title;
}

@RestController()
@RequestMapping('/api/books')
class BookUploadController {
  // JSON のパート、ファイル、テキストのフィールド、省略可能な追加のファイル。
  @PostMapping.of(consumes: MediaType.multipartFormData)
  Future<String> create(
    @RequestPart('book') @Valid() NewBook book,
    @RequestPart('cover') MultipartFile cover,
    @RequestParam('note') String note, {
    @RequestPart('pages') List<MultipartFile>? pages,
  }) async {
    // 表紙を保存する: 一時ファイルはリクエストが終わると削除される。
    await cover.transferTo('/var/shop/covers/${book.isbn}.png');
    return '${book.title}: ${cover.size} bytes, ${pages?.length ?? 0} pages, $note';
  }

  // 一つの名前の下の複数のファイル。何も送られなければ空のリスト。
  @PostMapping('/attachments')
  List<String> attachments(@RequestPart('files') List<MultipartFile> files) => [
    for (final file in files) '${file.originalFilename}: ${file.size}',
  ];

  // 小さなファイルなら、内容をメモリに読む。
  @PostMapping('/avatar')
  Future<int> avatar(@RequestPart() MultipartFile avatar) async {
    final bytes = await avatar.bytes;
    return bytes.length;
  }
}
# lib/resources/application.yaml
spring:
  web:
    multipart:
      max-file-size: 5MB        # 一つのファイル (またはフィールド)。デフォルトは 1MB
      max-request-size: 20MB    # リクエスト全体。デフォルトは 10MB
      max-part-count: 100       # ファイルとフィールドの合計。デフォルトは 50
      file-size-threshold: 64KB # これより小さいファイルはメモリに残る。デフォルトは 0B
      location: /var/tmp/shop   # 非公開のアップロード用ディレクトリを作る場所

ブラウザーや curl が送るリクエスト:

curl -F 'book={"isbn":"9780441013593","title":"Dune"};type=application/json' \
     -F [email protected] -F note='first edition' \
     http://localhost:8080/api/books

パートをパラメーターにバインドする

パラメーター 値
@RequestPart('cover') MultipartFile cover そのパートのファイル。その名前の下に複数のファイルがあれば最初のもの。
@RequestPart('files') List<MultipartFile> files その名前のすべてのファイル。届いた順。
@RequestPart('note') String note (または int、bool、enum など) テキストのフィールド。リクエストパラメーターと同じように変換される。その名前のファイルのパートなら、内容をテキストとして与える。
@RequestPart('data') Uint8List data (または List<int>) パートの生のバイト。フィールドでもファイルでもよい。
@RequestPart('book') NewBook book パートの内容を ObjectMapper で JSON としてその型に読んだもの。@Valid() 付きならバリデーションされる。
@RequestPart() MultipartFile avatar 名前がなければ、パラメーターと同じ名前のパート (avatar)。
@RequestParam('cover') MultipartFile cover ファイルとファイルのリストについては @RequestPart と同じ。
@RequestParam('note') String note テキストのフィールド。まずクエリ文字列を見て、次にマルチパートのフィールドを見る。
@RequestParam() Map<String, String> all クエリパラメーターとテキストのフィールドをまとめたもの。同じ名前ならクエリが優先される。
アノテーションなしの MultipartFile cover パラメーターと同じ名前のファイル (cover)。

ルール:

MultipartFile

MultipartFile は spring_web_dart から来ます。

メンバー 型 意味
name String ファイルが送られたフォームのフィールド (パートの name=)。ファイル名ではない。
originalFilename String? クライアントのマシン上のファイル名 (filename=)、または null。クライアントから来るものなので、決してそのままパスとして使わないこと。
contentType String? パートの Content-Type (image/png)、または null。クライアントの申告で、チェックされない。
size int 内容のサイズ (バイト)。
isEmpty bool 内容が空かどうか。ファイルが選ばれなかったとき、ブラウザーは空のファイルのパートを送る。
headers HttpHeaders パートのすべてのヘッダー。
bytes Future<Uint8List> メモリに読んだ内容全体。大きなファイルには openRead() か transferTo を使う。
openRead() Stream<List<int>> 一時ファイルから読む、チャンクのストリームとしての内容。呼ぶたびに新しい読み込みが始まる。
transferTo(String path) Future<void> 内容を path のファイルとして保存する。可能なら (同じファイルシステムなら) 一時ファイルをそこへ移動し、そうでなければコピーする。

transferTo のルール:

その他の実装:

上限とそのエラー

上限 プロパティ デフォルト 超えると
一つのファイル、または一つのテキストのフィールド spring.web.multipart.max-file-size 1MB 413: Maximum upload size exceeded: the file "cover" is larger than 1048576 bytes. (フィールドなら part "note")
リクエスト全体 spring.web.multipart.max-request-size 10MB 413: Maximum upload size exceeded: the request is larger than 10485760 bytes.
パートの数 spring.web.multipart.max-part-count 50 413: Maximum upload size exceeded: the request has more than 50 parts.

@ExceptionHandler で、上限に独自の言葉で応答できます。

@ControllerAdvice()
class UploadErrors {
  @ExceptionHandler()
  ProblemDetail tooLarge(MaxUploadSizeExceededException e) =>
      ProblemDetail.forStatusAndDetail(
        HttpStatus.contentTooLarge,
        e.maxUploadSize < 0
            ? 'Too many files.'
            : 'Covers may have ${e.maxUploadSize ~/ 1024} KB at most.',
      );
}

MaxUploadSizeExceededException.maxUploadSize は超えた上限のバイト数で、パートの数の場合は -1 です。@ExceptionHandler を参照してください。

一時ファイル

プロパティ

spring.web.multipart.enabled

型 デフォルト
bool true

マルチパートのリクエストを読むかどうかです。false にすると、まったく解析されません。@RequestPart パラメーターは 400 で応答し、MultipartFile パラメーターも同様です。アップロードを決して受け付けてはならないサービスや、独自のフィルターやライブラリがボディを読む場合に無効にします。

spring:
  web:
    multipart:
      enabled: false

spring.web.multipart.max-file-size

型 デフォルト
DataSize 1MB

一つのファイルの最大サイズで、テキストのフィールドの最大サイズでもあります。超えると応答は 413 です。-1 は上限なしを意味します。サイズには単位を付けます (512KB、5MB、1GB)。単なる数値はバイトです。写真、文書、動画のためには引き上げてください。max-request-size より大きくするべきではありません。いずれにせよそちらがボディ全体を制限します。

spring:
  web:
    multipart:
      max-file-size: 25MB

spring.web.multipart.max-request-size

型 デフォルト
DataSize 10MB

マルチパートのリクエスト全体の最大サイズです。すべてのパートを、そのヘッダーと境界も含めて数えます。超えると応答は 413 です。-1 は上限なしを意味します。この上限は、アップロードについて server.max-http-request-body-size に代わります。フォームが複数の大きなファイルを送る場合は、max-file-size と一緒に引き上げてください。

spring:
  web:
    multipart:
      max-file-size: 25MB
      max-request-size: 100MB

spring.web.multipart.max-part-count

型 デフォルト
int 50

リクエストが持てるパートの最大数で、ファイルとフィールドの合計です。超えると応答は 413 です。-1 は上限なしを意味します。何千もの小さなパートからなるリクエストは、パートごとにサーバーの処理を要します。この上限はそれを早めに止めます。フィールドの多いフォームや、多数の小さなファイルの一括アップロードのためには引き上げてください。

spring:
  web:
    multipart:
      max-part-count: 500

このキーはこのスターター独自のものです。Spring Boot は Tomcat に対して、同じ上限を server.tomcat.max-part-count (50) で設定します。

spring.web.multipart.file-size-threshold

型 デフォルト
DataSize 0B

このサイズまでのファイルはメモリに残り、それより大きいものは一時ファイルに行きます。0B なら、内容を持つすべてのファイルがディスクに行きます。ほとんどのアップロードが小さく、それらについてディスクを使いたくない場合は引き上げ (64KB)、多数のアップロードが同時に届き得る場合は低く保ってください。メモリ上の一つ一つがメモリを消費します。dart:io がない場合は無視され、ファイルは常にメモリに残ります。

spring:
  web:
    multipart:
      file-size-threshold: 64KB

spring.web.multipart.location

型 デフォルト
String システムの一時ディレクトリ

非公開のアップロード用ディレクトリを作るディレクトリです。なければ作られます。空の値はデフォルトになります。システムの一時ディレクトリが小さい場合 (メモリ上の tmpfs) や、transferTo がファイルをコピーではなく移動するように、ファイルの最終的な置き場所と同じファイルシステムにしたい場合に設定します。

spring:
  web:
    multipart:
      location: /var/shop/uploads/tmp   # 表紙は /var/shop/covers に保存する

独自のリゾルバー

スターターは、これらのプロパティから作った multipartResolver Bean (MultipartResolver) を宣言します。別の設定を使うには、その型の独自の Bean を宣言してください。その場合、デフォルトのものは身を引きます。

@Configuration()
class UploadConfig {
  // 管理用アプリケーションは任意のサイズのアップロードを受け付ける。
  @Bean()
  MultipartResolver multipartResolver() => MultipartResolver(
    const MultipartProperties(maxFileSize: -1, maxRequestSize: -1),
  );
}

MultipartProperties は、enabled、maxFileSize、maxRequestSize、maxPartCount、fileSizeThreshold (サイズはバイト)、location を持ちます。MultipartProperties.of(environment) は、プロパティからそれらを読みます。

パートが必要なフィルターや引数リゾルバーは、リゾルバーに求めます。リゾルバーはリクエストを一回読み、すべての呼び出し元に同じ結果を渡します。

MultipartResolver のメンバー 意味
isMultipart(request) このリクエストを読むかどうか。有効で、GET でなく、multipart/* のコンテンツタイプであること。
resolve(request) パートを Future<MultipartRequest> として返す。前述の 413 と 400 の例外で失敗する。
cleanup(request) リクエストの一時ファイルを削除する。
MultipartRequest のメンバー 意味
files Map<String, List<MultipartFile>>: フィールド名ごとのファイルのパート。
fields Map<String, List<String>>: フィールド名ごとの、その他のパートのテキスト。
part(name) その名前の最初のフィールドのパートのヘッダーと生のバイト、または null。

テスト

await app.mockMvc.multipart('/api/books', files: [
  MockMultipartFile('cover', 'dune.png', 'image/png', pngBytes),
  MockMultipartFile('book', null, 'application/json',
      utf8.encode('{"isbn": "9780441013593", "title": "Dune"}')),
], params: {'note': 'first edition'}).andExpect(status: 200);

ファイル名のない MockMultipartFile はフィールドのパートです。application/json なら、@RequestPart のための JSON のパートです。テスト を参照してください。

Spring (Java) との対応

@PostMapping(path = "/api/books", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
Book create(@RequestPart("book") @Valid NewBook book,
    @RequestPart("cover") MultipartFile cover,
    @RequestParam("note") String note) throws IOException {
  cover.transferTo(Path.of("/var/shop/covers", book.isbn() + ".png"));
  ...
}
spring.servlet.multipart.max-file-size=5MB
spring.servlet.multipart.max-request-size=20MB

重要な違い:

関連項目