
# レスポンスの圧縮

`server.compression.enabled=true` にすると、サーバーは gzip を受け付けるクライアントに対して、テキストのレスポンス (HTML、JSON、CSS、JavaScript など) を gzip で圧縮します。

## 使う理由

JSON と HTML は gzip で大きく縮み、多くの場合は元の 5 分の 1 程度になります。小さな応答は、遅いネットワークやスマートフォンに早く届き、帯域も節約できます。

圧縮はすべての応答で CPU を消費し、小さな応答ではほとんど得がありません。そのためデフォルトでは無効で、有効にした場合でも、小さな応答とすでに圧縮されたメディアタイプ (画像、動画、アーカイブ) はそのまま送られます。

前段のプロキシ (nginx、CDN) がすでに圧縮している場合や、事前に圧縮したファイルを提供する場合 (`spring.web.resources.chain.compressed`) は無効のままにしてください。

## 例

```yaml
# lib/resources/application.yml
server:
  compression:
    enabled: true
    mime-types:
      - text/html
      - text/css
      - text/javascript
      - application/javascript
      - application/json
      - application/problem+json
      - image/svg+xml
    min-response-size: 1KB
```

```properties
server.compression.enabled=true
server.compression.mime-types=text/html,text/css,text/javascript,application/javascript,application/json,application/problem+json,image/svg+xml
server.compression.min-response-size=1KB
```

リクエストとその応答:

```text
GET /api/books HTTP/1.1
Accept-Encoding: gzip, br

HTTP/1.1 200 OK
Content-Type: application/json
Content-Encoding: gzip
Vary: Accept-Encoding
Transfer-Encoding: chunked
```

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `server.compression.enabled` | `bool` | `false` | 条件を満たすレスポンスを gzip で圧縮する。 |
| `server.compression.mime-types` | `List<String>` | Spring Boot の一覧 (後述) | 圧縮するメディアタイプ。 |
| `server.compression.min-response-size` | `DataSize` | `2KB` | 圧縮する最小の `Content-Length`。 |

### `server.compression.enabled`

- **型:** `bool`。**デフォルト:** `false`。
- **動作:** 条件を満たす応答 (後述のルールを参照) について、`Accept-Encoding` に品質値が 0 より大きい `gzip` を挙げたクライアント (`gzip`、`gzip;q=0.5`。`gzip;q=0` は除く) に対して gzip を有効にします。
- **変更する理由:** 圧縮するプロキシを経由せず、クライアントが直接アクセスする API やサイト。
- **例:** `server.compression.enabled=true`。

### `server.compression.mime-types`

- **型:** メディアタイプのリスト (カンマ区切りまたは YAML のリスト)。**デフォルト:** Spring Boot の一覧:

```text
text/html, text/xml, text/plain, text/css, text/javascript,
application/javascript, application/json, application/xml
```

- **動作:** `Content-Type` がこれらのいずれかである応答だけが圧縮されます。パラメーターは両側で無視されます (`application/json; charset=utf-8` は `application/json` に一致します)。照合は大文字小文字を区別しません。
- **ワイルドカード:** `text/*` はすべての `text/` タイプに一致します。それ以外のパターンはサポートされません。
- **設定すると一覧が置き換わります。** デフォルトに追加されるわけではありません。必要なタイプをすべて書いてください。
- **空のリスト** (すべての要素が空) はデフォルトに戻ります。
- **変更する理由:** `application/problem+json` (エラーの応答)、`image/svg+xml`、`application/manifest+json`、`text/event-stream` を追加する、またはタイプを取り除く。
- **例:** `server.compression.mime-types=text/*,application/json,application/javascript`。

### `server.compression.min-response-size`

- **型:** `DataSize` (`2KB`、`512B`。単なる数値はバイト)。**デフォルト:** `2KB`。
- **動作:** `Content-Length` がこれより小さい応答は圧縮されません。長さがまだ分からない応答 (ストリーム、チャンク形式のボディ) は、サイズに関わらず圧縮されます。
- **変更する理由:** 応答のほとんどが小さな JSON ドキュメントなら引き下げる。CPU を節約するなら引き上げる。
- **例:** `server.compression.min-response-size=1KB`。

## どの応答が圧縮されるか

次のすべてが真のとき、応答は圧縮されます。

1. `server.compression.enabled` が `true` である。
2. クライアントが gzip を受け付ける。
3. ステータスがボディを許す。1xx、`204`、`205`、`304` ではない。
4. 部分コンテンツではない。`206` でなく、`Content-Range` もない。
5. まだ `Content-Encoding` を持たない (事前に圧縮されたファイルはそのまま送られる)。
6. 強い `ETag` を持たない。強いタグはこのバイト列そのものを約束するので、Tomcat と同じく、そうした応答は決して圧縮されない。弱いタグ (静的リソースが送る `W/"..."`) は問題ない。
7. `Content-Type` が `mime-types` に含まれる。
8. `Content-Length` が `min-response-size` 以上であるか、分からない。

応答が圧縮されると、`Content-Encoding: gzip` が追加され、`Content-Length` は取り除かれます。ボディはチャンク形式で送られます。

### `Vary: Accept-Encoding`

ルール 1 と 3 から 8 が許すすべての応答には、gzip を受け付けないクライアントに対しても `Vary: Accept-Encoding` が付きます。そのため、クライアントとサーバーの間のキャッシュは、圧縮した応答と圧縮していない応答を区別して保持します。追加されるのは一回だけです。`Vary` がすでに `*` を持つ場合は `*` のままです。

### ストリーム

- **Server-Sent Events** (`text/event-stream`) は、Spring Boot と同じくデフォルトの一覧に含まれません。圧縮するには `text/event-stream` を追加してください。フラッシュのたびにそれまでに圧縮した分が送られるので、イベントは引き続き一つずつ届きます。
- **バイトストリーム** と **NDJSON** は、メディアタイプによって同じルールに従います。

### gzip のみ

サーバーは gzip でだけ圧縮します。Brotli も `deflate` もありません。Brotli で提供するには、静的ファイルの隣に事前に圧縮した `.br` ファイルを置き、`spring.web.resources.chain.compressed=true` を設定してください。[静的リソース](../static-resources.md) を参照してください。

### WebSocket

圧縮は WebSocket のメッセージには適用されず、サーバーは permessage-deflate のネゴシエーションも行いません。[WebSocket](websocket.md) を参照してください。

## Spring (Java) との対応

```properties
server.compression.enabled=true
server.compression.mime-types=text/html,application/json
server.compression.min-response-size=2KB
```

重要な違い:

- キー、デフォルト、ルール (強い `ETag`、部分コンテンツ、`Vary`) は、Tomcat 上の Spring Boot と同じです。
- `server.compression.excluded-user-agents` はサポートされません。
- 生成するのは gzip だけです。

## 関連項目

- [組み込みサーバー](index.md)
- [静的リソース](../static-resources.md)
- [サーバー送信イベント](../streaming/sse.md)
- [すべてのプロパティ](../properties.md)
- [データサイズ](../../spring-core-dart/conversion/data-size.md)
