
# ファイルとマルチパート

`@RequestPart` パラメーターを持つメソッドは、パラメーターごとに一つのパートを持つ `multipart/form-data` のボディを送ります。ファイル、テキストのフィールド、JSON のパートです。`MultipartFile` はコントローラーが受け取るのと同じ型なので、コントローラーが受け取ったファイルをそのまま渡せます。

## 使う理由

アップロード (表紙の画像、メタデータを伴う文書) には、境界、コンテンツタイプ、ファイル名を持つマルチパートのボディが必要です。手で書くと面倒ですが、`@RequestPart` で宣言すれば、クライアントが引数からそれを組み立てます。

## 例

```dart
@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) との対応

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

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

## 関連項目

- [メソッド](methods.md)
- [Web スターターのアップロード](../spring-boot-starter-web/streaming/uploads.md)
