
# Differences from Spring

`spring_boot_starter_web` follows Spring Boot and Spring MVC: the same annotations, the same property names where they make sense, the same answers. This page lists every place where it does not, and why, grouped by topic. The last section lists what is not there yet.

## Why

When you port a Spring application, or follow a Spring tutorial, you need to know where the behaviour is not the one you expect. Most differences come from three facts:

- **Dart is not Java.** There is no reflection at run time and no servlet container. Annotations on exception classes cannot be read at run time, and one `Type` cannot be tested for being a subtype of another.
- **The server is `dart:io`'s `HttpServer`**, not Tomcat. Some rules come from it.
- **Some defaults are safer.** A few limits exist here that Spring leaves to the container or to the application.

## Example

The same controller in both. The code is nearly the same; the differences are in the details below.

```dart
@RestController()
@RequestMapping('/api/books')
class BookController {
  BookController(this.books);
  final BookService books;

  @GetMapping('/{isbn}')
  Future<Book> find(@PathVariable() String isbn) => books.find(isbn);

  @GetMapping()
  Future<List<Book>> search(@RequestParam('q') String? query) => books.search(query);
}
```

```java
@RestController
@RequestMapping("/api/books")
class BookController {
  @GetMapping("/{isbn}")
  Book find(@PathVariable String isbn) { ... }

  @GetMapping
  List<Book> search(@RequestParam(name = "q", required = false) String query) { ... }
}
```

Required or optional comes from the Dart parameter (`String?`, a default value), not from `required` and `defaultValue`. See [@RequestParam](controllers/request-param.md).

## Configuration

- **Renamed properties.** `server.servlet.context-path` is `server.context-path`, `server.servlet.session.*` is `server.session.*`, and `spring.servlet.multipart.*` is `spring.web.multipart.*`: there is no servlet container. Any key under an old prefix, in any source (a file, the command line, an environment variable), stops the start and names the new key. Spring's properties migrator only logs a warning.
- **This starter's own keys**, not in Spring Boot: `server.max-http-request-body-size`, `server.request-timeout`, `server.max-concurrent-requests`, `server.max-connections`, `server.retry-after`, `server.isolates.*`, `spring.web.debug.*`, `server.forward-headers.trusted-proxies`, `server.websocket.*`, `spring.mvc.sse.heartbeat-interval`, `spring.web.multipart.max-part-count` (Spring Boot: `server.tomcat.max-part-count`), `spring.web.resources.spa-fallback`, `spring.web.resources.directory-index`.
- **`server.connection-timeout`** is the key Spring Boot 2.0 had. Spring Boot 3 and 4 use `server.tomcat.connection-timeout`.
- **`spring.main.register-shutdown-hook` is `false` by default** (a key of `spring_boot_dart`), because listening for signals keeps a Dart program alive. Set it to `true`, or `Ctrl+C` and SIGTERM end the process without a graceful shutdown.
- **`spring.main.web-application-type`** only knows `none`. There is one kind of server, not `servlet` and `reactive`.
- **No `@EnableWebMvc`.** Every `@RestController` in the scanned package is mapped.

See [All properties](properties.md).

## The server

- **`dart:io`'s `HttpServer`, not Tomcat.** HTTP/1.1 only; `server.http2.enabled` is not read. No `server.tomcat.*` keys.
- **TLS from PEM file paths.** No key stores, no SSL bundles, no `classpath:` or `resources:` locations. With `server.ssl.client-auth=need`, a client without a certificate completes the TLS handshake and gets a 403 per request. See [TLS](server/ssl.md).
- **`server.request-timeout` and `RequestDeadline` are extensions.** Spring times out connections (Tomcat) and asynchronous requests (`spring.mvc.async.request-timeout`), not the handling of a synchronous request, and no deadline follows a request into the calls it makes. See [Timeouts](server/timeouts.md).
- **Stalled request bodies get a 408** after `server.connection-timeout` (60 s). With Tomcat the read fails and Spring answers 400.
- **No connection limit unless set.** `server.max-connections` and `server.max-concurrent-requests` set one (Tomcat's `max-connections` is 8192 by default). Past either a request is answered 503 with `Retry-After` at once, instead of waiting. See [Overload](server/overload.md).
- **Isolates, not threads.** Tomcat's worker threads share the beans. Here the server answers from one isolate; `server.isolates.count` adds isolates that each run the whole application with their own beans, so sessions, caches and counters in memory are per isolate. See [A pool of isolates](server/isolates.md).
- **A body over `server.max-http-request-body-size` (10 MB)** is a 413, whatever its type. Tomcat has no such limit for every body.
- **Two `Host` headers and a `%` without two hex digits are accepted** (`dart:io` keeps the last `Host`; `/a%G1` is read as `/a%25G1`), where Tomcat answers 400.
- **A raw `\` in the request target is a `/`.** `dart:io` parses the target before the server sees it and keeps no raw form, so `/files/..\..\secret` arrives as `/secret` (its `..` resolved), and raw bytes past ASCII are read as Latin-1 (`/café` sent as UTF-8 arrives as `/caf%C3%83%C2%A9`). Tomcat answers 400 to both. Filters, security rules and controllers all see the same path, but a proxy in front whose rules look at paths must refuse `\` itself.
- **`Content-Length` with `Transfer-Encoding`** is answered 400, and the connection closes, only when the server sees both headers (Tomcat always answers 400). `dart:io` shows both only in some spellings (the length first and the encoding not written exactly `chunked`); in the others it drops the `Content-Length` itself and the request is read as chunked. Use a proxy that refuses such requests.
- **No `Server` header, no default `Content-Type`.** `dart:io`'s `X-Frame-Options: SAMEORIGIN` and `X-Content-Type-Options: nosniff` are sent on every answer (Spring Boot without Spring Security sends neither).
- **Graceful shutdown** closes open event streams and WebSocket sessions at once (1001), in both modes. See [Shutdown](server/shutdown.md).
- **A Flutter app listens on `127.0.0.1` by default.** See [The embedded server](server/index.md).

## Behind a proxy

- **`native` and `framework` do the same thing:** both apply the forwarded headers of trusted proxies only, as Tomcat's `RemoteIpValve`. Spring's `ForwardedHeaderFilter` (`framework`) believes every peer.
- **Trusted proxies are addresses and CIDR ranges** (`server.forward-headers.trusted-proxies`), not Tomcat's regular expression.
- **`X-Forwarded-Prefix` and `X-Forwarded-Ssl` are not read.**

See [Behind a reverse proxy](server/reverse-proxy.md).

## Controllers and parameters

- **More startup checks** than Spring: a path variable without a parameter, a parameter nothing can fill, an invalid `@ExceptionHandler` stop the start with the list of problems. See [Startup checks](controllers/startup-checks.md).
- **Required or optional comes from the Dart parameter**, not from `required` and `defaultValue`: a nullable parameter gets `null`, an optional one keeps its Dart default.
- **No `@ModelAttribute`, no binding of forms to objects.** Form fields reach a handler through `@RequestParam` (one field, a list, or all of them as a `Map`) or a `@RequestBody() Map<String, String>`.
- **No `HttpSession` parameter.** A handler gets the session with `request.getSession()`. See [Sessions](sessions.md).
- **Custom argument resolvers are asked before the built-in ones** (Spring asks them after), so a starter can take over any parameter, as the security starter's `@AuthenticationPrincipal` does. See [WebMvcConfigurer](web-mvc-configurer.md).
- **`@ResponseStatus` goes on handler methods or the controller class**, not on exception classes, whose annotations cannot be read at run time. Throw a `ResponseStatusException` or implement `ErrorResponse` instead.

## Errors

- **Errors are `ProblemDetail`s** (`application/problem+json`), always. Spring Boot's default is the `/error` JSON (`timestamp`, `status`, `error`, `path`) unless `spring.mvc.problemdetails.enabled=true`. Here there is no `/error` endpoint, no `ErrorController`, and `server.error.*` is not read. The exceptions are the plain-text answers Spring gives too: a refused CORS request or WebSocket handshake.
- **`@ExceptionHandler([types])` matches exact run-time types**, because Dart cannot test whether a `Type` is a subtype of another. Subtypes match through the type of the exception parameter: `@ExceptionHandler() void on(StateError e)`. See [@ExceptionHandler](errors/exception-handler.md).
- **`@ControllerAdvice.of(basePackages: ...)` takes library URI prefixes** (`package:shop/admin/`) instead of Java packages, and `annotations` match a controller's annotation by its exact type. There is no `basePackageClasses`. See [@ControllerAdvice](errors/controller-advice.md).
- **A `HandlerExceptionResolver` returns an `ErrorResponse`** (or `null`) instead of writing into the response and returning a `ModelAndView`. The built-in resolution (the `@ExceptionHandler` methods, `ResponseStatusException`) comes first; resolver beans are asked after it. See [HandlerExceptionResolver](errors/handler-exception-resolver.md).

## Streams, uploads and downloads

- **A declared `Stream<Uint8List>` or `Stream<List<int>>` result is raw bytes.** Spring MVC has no byte stream result; Spring WebFlux writes a `Flux<DataBuffer>` the same way. Other streams are server-sent events (or NDJSON). See [Downloads](streaming/downloads.md).
- **Event streams start with a `:` comment line**, because `dart:io` sends the headers with the first body bytes. Clients ignore it. See [Server-sent events](streaming/sse.md).
- **An `SseEmitter` without a timeout never times out** when `spring.mvc.async.request-timeout` is not set: there is no servlet container whose default applies (Tomcat's 30 seconds in Spring). It ends when it is completed, when the client goes away, or when the server stops. `spring.mvc.async.request-timeout` applies to `SseEmitter`s only.
- **Multipart without a servlet container.** The `spring.web.multipart.*` keys are Spring Boot's `spring.servlet.multipart.*` without the servlet, and the temporary files are this starter's own: `file-size-threshold` is `0B`, so every file goes to disk. Only `multipart/form-data` parts are bound to `@RequestPart`, not `multipart/mixed`. See [Uploads](streaming/uploads.md).
- **One byte range per request.** Several ranges get the whole content, not `multipart/byteranges`. A `Resource` a controller returns has no `ETag` (the static resources have one).

## Static resources

Stricter and a little richer than Spring's `ResourceHttpRequestHandler`. See [Static resources](static-resources.md).

- **Dot files are not served** (Spring serves them); `.well-known/` is.
- **`;` and empty segments in the path are a 404.** Spring Security's firewall answers them with a 400; plain Spring MVC serves them.
- **A symbolic link that leaves the location is refused**, and so is a path that only Windows would read as another file.
- **They send a weak `ETag`** (Spring sends none unless an `etagGenerator` is set), `X-Content-Type-Options: nosniff` (Spring Security adds it in Spring), `Cache-Control` on a `304` too, and `application/json` for `apple-app-site-association`.
- **A path without a file** gets the dispatcher's 404 (`No endpoint GET /x.`), where Spring 6.1 answers `No static resource x.`.
- **`HandlerInterceptor`s do not run for them**: they are for controller methods.
- **`spring.web.resources.spa-fallback` and `directory-index`** are this starter's own keys.
- **Not supported:** `spring.web.resources.chain.enabled`, `chain.cache`, the version strategies, the webjars mapping.
- **A precompressed variant** is a `ResourceHandlerRegistration` setting (`setCompressed`, or `spring.web.resources.chain.compressed`), instead of Spring's `resourceChain(true).addResolver(new EncodedResourceResolver())`.
- **Locations are `resources:` and `file:`.** `resources:` is a folder of `lib/resources/`, not its root (which holds the configuration). Another prefix stops the start. `META-INF/resources/` and `resources/` are not in the defaults, as Dart has no jars.

## Sessions

- **The session cookie is `SameSite=Lax`** by default.
- **The number of sessions is limited** (`server.session.max-sessions`, 10000). At the limit, expired sessions are removed, then a new session is refused with a 503.
- **Sessions live in memory** of one process, unless you declare another `HttpSessionRepository` bean.

See [Sessions](sessions.md).

## CORS

- **A pre-flight that several handlers match** (with `@CrossOrigin` each; no handler of exactly that path, or several) gets the first one's CORS rules. Spring allows it from any origin with credentials, whatever the handlers' specificity.
- **CORS values outside visible US-ASCII are refused with a 403**: an `Origin`, or a pre-flight's requested method or headers, with a space, a control character or a letter beyond ASCII, even where `*` allows any. Spring echoes such a method or header (no browser sends one), and refuses such an `Origin` too.
- **An `Origin` longer than 1024 characters is never allowed** (CORS and WebSocket handshakes: a 403), whatever the rules, `*` included. A real origin is under 300 characters. Spring checks any length, and its patterns' regular expressions slow down with it.
- **`spring.web.cors.*` is not read.** CORS is configured with `@CrossOrigin`, `WebMvcConfigurer.addCorsMappings` or a `corsConfigurationSource` bean.

See [CORS](cors.md).

## WebSocket

- **The message limits are properties of this starter** (`server.websocket.max-text-message-size` and `max-binary-message-size`, 8 KB each, Tomcat's defaults). Spring sets them on the container (`ServletServerContainerFactoryBean`). The text limit counts UTF-8 bytes; Tomcat counts characters.
- **No permessage-deflate.** Tomcat negotiates it.
- **Every session has send limits** (`server.websocket.send-buffer-size-limit`, 512 KB, and `send-time-limit`, 10 s; past them the connection is dropped with 4500), the defaults of Spring's `ConcurrentWebSocketSessionDecorator`. In Spring they apply to STOMP sessions and to sessions you decorate; a plain handler on Tomcat blocks the sending thread instead (up to Tomcat's 20-second blocking send timeout). Await `IoWebSocketSession.flush()` after `sendMessage` to wait the same way.

See [WebSocket](server/websocket.md).

## Testing

- **`MockMvc` takes named expectations** (`andExpect(status: 200, json: ...)`, matchers allowed) instead of `status().isOk()` and `jsonPath(...)`.
- **`ApplicationContextRunner` starts no server** unless the test sets `spring.test.web-environment=random-port`.

See [Testing](testing.md).

## Not yet

These are planned but not there yet:

- **`@ConditionalOnWebApplication`** and test slices such as **`@WebMvcTest`**.
- **`ResponseBodyEmitter`.** A `Stream<T>` result covers server-sent events and NDJSON.
- **Several byte ranges** as `multipart/byteranges`, an **`ETag` for a `Resource`** a controller returns, and **`@RequestPart` with `multipart/mixed`**.
- **`spring.web.cors.*`** and **`server.max-http-request-header-size`**.
- **A per-route request timeout.** `server.request-timeout` applies to every request.
- **Flutter:** a warning when a handler blocks the main isolate, decoding big JSON bodies in another isolate, and the whole server in a background isolate.
- **Other servers** (for example on `shelf`) behind the same `WebServerFactory`, and **STOMP** over WebSocket.

## In Spring (Java)

This whole page compares with Spring. In short, code moves over with small changes:

- annotations keep their names (`@RestController`, `@GetMapping`, `@PathVariable`, `@RequestBody`, `@ExceptionHandler`, `@ControllerAdvice`, `@CrossOrigin`);
- `required = false` becomes a nullable parameter, `defaultValue` a Dart default;
- `server.servlet.*` and `spring.servlet.multipart.*` lose `servlet`;
- error bodies are `ProblemDetail`s;
- `@ResponseStatus` on exception classes becomes a `ResponseStatusException` or an `ErrorResponse`.

## See also

- [Overview](index.md)
- [All properties](properties.md)
- [The embedded server](server/index.md)
- [Controllers](controllers/index.md)
- [Errors](errors/index.md)
- [Static resources](static-resources.md)
- [Testing](testing.md)
