
# アップロード

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

## 使う理由

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

- 誰が最初に求めても、リクエストごとに一回だけボディを解析します。
- 各ファイルを、届いたそばから非公開の一時ファイルにストリーミングするので、アップロード全体がメモリに保持されることはありません。
- 上限を超えた時点で読むのをやめ、`413` で応答します。
- ハンドラーが何をしたかに関わらず、リクエストが終わると一時ファイルを削除します。

## 例

```dart
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;
  }
}
```

```yaml
# 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` が送るリクエスト:

```text
curl -F 'book={"isbn":"9780441013593","title":"Dune"};type=application/json' \
     -F cover=@dune.png -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` で、上限に独自の言葉で応答できます。

```dart
@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](../errors/exception-handler.md) を参照してください。

## 一時ファイル

- 各ファイルは、`file-size-threshold` に収まらない限り、届いたそばから一時ファイルにストリーミングされます。
- ファイルは、プロセスのユーザーだけが開けるディレクトリ (`0700`) に置かれます。このディレクトリはプロセスごとに一回、`location` の中、またはシステムの一時ディレクトリの中に作られます。各ファイルはランダムな名前 (`upload_<32 hex digits>.tmp`) を持ち、排他的に作られるので、マシンの他のユーザーはアップロードを読むことも、その名前でファイルやリンクを仕込むこともできません。
- そのディレクトリが消えた場合 (システムが一時ディレクトリを掃除した場合)、次のアップロードのために新しいものが作られます。
- **リクエストが終わると削除されます。** コントローラーメソッドとその戻り値の後で、ハンドラーが何をしたかに関わらずです。ファイルを残すには `transferTo` を使うか、リクエスト中に `openRead()` をコピーしてください。
- コントローラーに届かないリクエストのパートを (`multipartResolver` Bean を通して) 自分で読むフィルターは、終わったら `multipartResolver.cleanup(request)` を呼ぶべきです。
- `dart:io` がない場合 (Web では)、ファイルはメモリに残ります。

## プロパティ

### `spring.web.multipart.enabled`

| 型 | デフォルト |
|---|---|
| `bool` | `true` |

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

```yaml
spring:
  web:
    multipart:
      enabled: false
```

### `spring.web.multipart.max-file-size`

| 型 | デフォルト |
|---|---|
| `DataSize` | `1MB` |

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

```yaml
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` と一緒に引き上げてください。

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

### `spring.web.multipart.max-part-count`

| 型 | デフォルト |
|---|---|
| `int` | `50` |

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

```yaml
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` がない場合は無視され、ファイルは常にメモリに残ります。

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

### `spring.web.multipart.location`

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

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

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

## 独自のリゾルバー

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

```dart
@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`。 |

## テスト

```dart
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 のパートです。[テスト](../testing.md) を参照してください。

## Spring (Java) との対応

```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"));
  ...
}
```

```properties
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)` です。

## 関連項目

- [ダウンロード](downloads.md)
- [@RequestParam](../controllers/request-param.md)
- [@RequestBody](../controllers/request-body.md)
- [@ExceptionHandler](../errors/exception-handler.md)
- [DataSize](../../spring-core-dart/conversion/data-size.md)
- [すべてのプロパティ](../properties.md)
