Response compression
With server.compression.enabled=true, the server gzips text responses (HTML, JSON, CSS, JavaScript, ...) for clients that accept gzip.
Why
JSON and HTML shrink a lot with gzip, often to a fifth of their size. Smaller answers reach slow networks and phones sooner and cost less bandwidth.
Compression costs CPU on every answer, and small answers gain little. So it is off by default, and even when it is on, small answers and media types that are already compressed (images, video, archives) are sent as they are.
Leave it off when a proxy in front (nginx, a CDN) already compresses, or when you serve precompressed files (spring.web.resources.chain.compressed).
Example
# 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
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
A request and its answer:
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
Properties
| Key | Type | Default | Meaning |
|---|---|---|---|
server.compression.enabled |
bool |
false |
Gzip the responses that qualify. |
server.compression.mime-types |
List<String> |
Spring Boot's list (below) | The media types compressed. |
server.compression.min-response-size |
DataSize |
2KB |
The smallest Content-Length compressed. |
server.compression.enabled
- Type:
bool. Default:false. - What it does: turns gzip on for the answers that qualify (see the rules below), for clients whose
Accept-Encodinglistsgzipwith a quality above 0 (gzip,gzip;q=0.5; notgzip;q=0). - Why change it: an API or site that clients reach directly, without a compressing proxy.
- Example:
server.compression.enabled=true.
server.compression.mime-types
- Type: a list of media types (a comma list or a YAML list). Default: Spring Boot's list:
text/html, text/xml, text/plain, text/css, text/javascript,
application/javascript, application/json, application/xml
- What it does: only answers whose
Content-Typeis one of these are compressed. Parameters are ignored on both sides (application/json; charset=utf-8matchesapplication/json). Matching ignores case. - Wildcards:
text/*matches everytext/type. No other pattern is supported. - Setting it replaces the list. It does not add to the defaults. Write all the types you want.
- An empty list (all entries blank) falls back to the defaults.
- Why change it: add
application/problem+json(error answers),image/svg+xml,application/manifest+json,text/event-stream, or remove types. - Example:
server.compression.mime-types=text/*,application/json,application/javascript.
server.compression.min-response-size
- Type:
DataSize(2KB,512B; a plain number is bytes). Default:2KB. - What it does: an answer whose
Content-Lengthis smaller is not compressed. An answer whose length is not known yet (a stream, a chunked body) is compressed whatever its size. - Why change it: lower it when most of your answers are small JSON documents; raise it to save CPU.
- Example:
server.compression.min-response-size=1KB.
Which answers are compressed
An answer is compressed when all of these are true:
server.compression.enabledistrue;- the client accepts gzip;
- the status allows a body: not 1xx,
204,205or304; - it is not partial content: not
206, noContent-Range; - it has no
Content-Encodingyet (a precompressed file is sent as it is); - it has no strong
ETag. A strong tag promises these exact bytes, so, as Tomcat does, such an answer is never compressed. A weak tag (W/"...", as the static resources send) is fine; - its
Content-Typeis inmime-types; - its
Content-Lengthis at leastmin-response-size, or not known.
When the answer is compressed, Content-Encoding: gzip is added and Content-Length is dropped: the body is sent chunked.
Vary: Accept-Encoding
Every answer that rules 1 and 3 to 8 allow gets Vary: Accept-Encoding, even for a client that does not accept gzip. So a cache between the client and the server keeps the compressed and the plain answer apart. It is added once. When Vary already holds *, it stays *.
Streams
- Server-sent events (
text/event-stream) are not in the default list, as in Spring Boot. Addtext/event-streamto compress them. Each flush sends what was compressed so far, so events still arrive one by one. - Byte streams and NDJSON follow the same rules by their media type.
Only gzip
The server compresses with gzip only. No Brotli, no deflate. To serve Brotli, ship precompressed .br files next to the static files and set spring.web.resources.chain.compressed=true. See Static resources.
WebSocket
Compression does not apply to WebSocket messages, and the server does not negotiate permessage-deflate. See WebSocket.
In Spring (Java)
server.compression.enabled=true
server.compression.mime-types=text/html,application/json
server.compression.min-response-size=2KB
Differences that matter:
- The same keys, defaults and rules (strong
ETag, partial content,Vary) as Spring Boot on Tomcat. server.compression.excluded-user-agentsis not supported.- Only gzip is produced.