アップロード
multipart/form-data のリクエストは、ファイルとフォームのフィールドを一つのボディで運びます。スターターはそれを読み、ファイルを一時ファイルに保持し、各パートをコントローラーのパラメーターにバインドします。MultipartFile、テキストのフィールド、生のバイト、または JSON から読んだオブジェクトです。
使う理由
enctype="multipart/form-data" のブラウザーのフォーム、curl -F、Flutter アプリ、Feign クライアントは、この方法でファイルを送ります。この形式を手で読むのは長く、間違えやすく、不注意な読み方はアップロード全体をメモリに保持したり、クライアントにディスクを埋めさせたりします。スターターは:
- 誰が最初に求めても、リクエストごとに一回だけボディを解析します。
- 各ファイルを、届いたそばから非公開の一時ファイルにストリーミングするので、アップロード全体がメモリに保持されることはありません。
- 上限を超えた時点で読むのをやめ、
413で応答します。 - ハンドラーが何をしたかに関わらず、リクエストが終わると一時ファイルを削除します。
例
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)。 |
ルール:
- 必須か省略可能か。 パラメーターが null 許容 (
MultipartFile? cover) であるかデフォルト値を持たない限り、パートは必須です。必須のパートがないと、詳細Required part 'cover' is not present.の400になります。 - リスト。
List<MultipartFile>がない場合、必須なら400、null 許容ならnull、null 非許容の省略可能な名前付きパラメーターなら空のリストです。 - マルチパートでない場合。 マルチパートでないリクエストへの
@RequestPartは400です (Failed to parse multipart request: the request is not a multipart request (Content-Type ...))。 consumesは必須ではありません。consumes: MediaType.multipartFormDataは、別のContent-Typeのリクエストをメソッドが選ばれる前に415にし、エンドポイントの説明にもなります。- 読まれるもの。
GETでないmultipart/*のリクエストはすべて読まれます。保持されるのは、Content-Dispositionにnameを持つパートだけです。持たないパートは飛ばされます。filename(空でも) を持つパートはファイルで、それ以外はフィールドです。 - フィールドのテキスト は UTF-8 で、パートの
Content-Typeがcharset=iso-8859-1を示していれば Latin-1 でデコードされます。 - 解析できない JSON のパート は
400です (JSON parse error in part "book": ...)。制約に違反する@Valid()のパートは、@RequestBodyと同じく違反付きの400です。 - ボディを読むタイミング。 パラメーターや他のコードがパートを求めたときだけです。マルチパートのパラメーターを持たないハンドラーは、ボディをまったく読みません。
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 のルール:
- 他の読み込みの後に、一回だけ呼んでください。一時ファイルが移動された後は、元の場所からファイルを読めなくなり、二回目の
transferToは失敗します。 - 移動したファイルは、リクエストが終わっても削除されません。あなたのものです。
- メモリに保持された小さなファイル (
file-size-threshold未満) はpathに書き込まれます。
その他の実装:
InMemoryMultipartFile(name, bytes, originalFilename:, contentType:, headers:)とInMemoryMultipartFile.fromString(name, text, ...)は、内容をメモリに保持します。コードからコントローラーや Feign クライアントを呼ぶときに使います。そのtransferToはUnsupportedErrorを投げます。MockMultipartFile(name, originalFilename, contentType, bytes)は、Spring の引数の順序による同じもので、テスト用です。
上限とそのエラー
| 上限 | プロパティ | デフォルト | 超えると |
|---|---|---|---|
| 一つのファイル、または一つのテキストのフィールド | 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. |
- 応答は、
MaxUploadSizeExceededExceptionによるステータス413 Content Too LargeのProblemDetailです。 - 上限で読み込みが止まります。 サーバーはボディの残りを読まず、それまでに書いた一時ファイルは削除されます。
server.max-http-request-body-sizeは、マルチパートリゾルバーが読むボディには適用されません。max-request-sizeがそれに代わります。別の方法でマルチパートのボディを読むコード (@RequestBody() String) には、サーバーの上限が適用されたままです。- 壊れたボディ (境界がない、終わらないパート、16 KB を超えるパートのヘッダー、途中で去ったクライアント) は、
MultipartRequestExceptionによる400です:Failed to parse multipart request: ...。ディスクには何も残りません。
@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 を参照してください。
一時ファイル
- 各ファイルは、
file-size-thresholdに収まらない限り、届いたそばから一時ファイルにストリーミングされます。 - ファイルは、プロセスのユーザーだけが開けるディレクトリ (
0700) に置かれます。このディレクトリはプロセスごとに一回、locationの中、またはシステムの一時ディレクトリの中に作られます。各ファイルはランダムな名前 (upload_<32 hex digits>.tmp) を持ち、排他的に作られるので、マシンの他のユーザーはアップロードを読むことも、その名前でファイルやリンクを仕込むこともできません。 - そのディレクトリが消えた場合 (システムが一時ディレクトリを掃除した場合)、次のアップロードのために新しいものが作られます。
- リクエストが終わると削除されます。 コントローラーメソッドとその戻り値の後で、ハンドラーが何をしたかに関わらずです。ファイルを残すには
transferToを使うか、リクエスト中にopenRead()をコピーしてください。 - コントローラーに届かないリクエストのパートを (
multipartResolverBean を通して) 自分で読むフィルターは、終わったらmultipartResolver.cleanup(request)を呼ぶべきです。 dart:ioがない場合 (Web では)、ファイルはメモリに残ります。
プロパティ
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
重要な違い:
- キーは
spring.web.multipart.*で、Spring Boot のspring.servlet.multipart.*から servlet を除いたものです。サーブレットコンテナーはなく、スターターが自分でボディを解析します。 max-part-countはこのスターターのキーです。Spring Boot にはserver.tomcat.max-part-countがあります。- Spring の
resolve-lazilyとstrict-servlet-complianceはありません。パートは常に、最初に求められたときに読まれます。 required = falseは、Dart では null 許容のパラメーターです。getBytes()、getInputStream()、transferTo(File)は、bytes、openRead()、transferTo(String path)です。