Startup checks
When the application starts, the starter checks every controller and every @ControllerAdvice bean. A mistake stops the start, with one message that lists every problem found.
Why
A wrong mapping would otherwise show up only when a client calls it, maybe in production: a path variable that is never filled, a parameter nothing can bind, two methods for the same request. Checked at startup, the mistake is seen at once, in a test or on the developer's machine, and all mistakes are reported together rather than one per run.
Example
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
class BookFilter {
String? author;
}
@RestController()
@RequestMapping('/api/books')
class BookController {
// The parameter names {id}, but the path has {isbn}: two problems.
@GetMapping('/{isbn}')
String find(@PathVariable('id') String isbn) => isbn;
// A class parameter without an annotation: nothing can fill it.
@GetMapping('/search')
String search(BookFilter filter) => '';
}
@RestController()
@RequestMapping('/api/orders')
class OrderController {
@GetMapping()
List<String> list() => [];
// The same request as list().
@GetMapping()
List<String> all() => [];
}
The application does not start, and the log shows:
Invalid controllers:
- BookController.find: @PathVariable "id" is not in the path
- BookController.find: the path variable {isbn} of "/api/books/{isbn}" has no @PathVariable parameter
- BookController.search: parameter filter (BookFilter) needs @PathVariable, @RequestParam, @RequestHeader, @CookieValue or @RequestBody
- Ambiguous mapping: OrderController.all and OrderController.list both map GET /api/orders
What is checked
Each line of the list starts with the method, as Class.method. The checks and their messages:
| Mistake | Message |
|---|---|
| two mapping annotations on one method | BookController.find has several mapping annotations; use one (@RequestMapping.of for other methods) |
| a malformed path pattern | BookController.find: <reason> in "<path>", such as "**" and "{*name}" may only appear at the end of a pattern, Duplicate variable {isbn}, Unbalanced "{" in "{isbn", Malformed variable {...}, Invalid regex in {...}, A {*name} needs a name |
a produces or consumes that is not a media type |
BookController.find: invalid produces "<value>": <reason> (or consumes) |
| a parameter with two binding annotations | BookController.find: parameter isbn has several roles |
a @PathVariable whose name is not in the path |
BookController.find: @PathVariable "id" is not in the path |
a {variable} of the path without a @PathVariable |
BookController.find: the path variable {isbn} of "/api/books/{isbn}" has no @PathVariable parameter |
a @PathVariable, @RequestParam, @RequestHeader or @CookieValue of a type that is not a simple value |
BookController.find: the @RequestParam parameter filter (Filter) is not a simple value; use a String, number, bool, enum, DateTime, Duration, Uri or a List of them |
| a parameter without annotation that nothing can fill | BookController.search: parameter filter (Filter) needs @PathVariable, @RequestParam, @RequestHeader, @CookieValue or @RequestBody |
two @RequestBody parameters |
BookController.create has more than one @RequestBody |
a method returning a Future of a stream |
BookController.changes returns a Future of a stream: return the EventStream / Stream directly |
@CrossOrigin(allowCredentials: true) with all origins |
BookController.find: @CrossOrigin(allowCredentials: true) needs origins or originPatterns (all origins, "*", cannot be allowed with credentials) |
@CrossOrigin(allowPrivateNetwork: true) with all origins |
BookController.find: @CrossOrigin(allowPrivateNetwork: true) needs origins or originPatterns (all origins, "*", cannot be allowed to a private network) |
an @ExceptionHandler parameter that is not the exception, the request, the response or the headers |
@ExceptionHandler ApiErrors.notFound: parameter extra must be the exception, the ServerHttpRequest, the ServerHttpResponse or the HttpHeaders |
an @ExceptionHandler without an exception type |
@ExceptionHandler ApiErrors.timeout: give the exception types (@ExceptionHandler([MyException])) or take the exception as a parameter |
| two methods for the same request | Ambiguous mapping: OrderController.all and OrderController.list both map GET /api/orders |
Rules:
- "The same request" means the same HTTP method, the same pattern and the same conditions. Two methods that differ in
consumes,producesorheadersare not ambiguous: the request decides (GET /api/orders produces [text/csv]andGET /api/ordersare two mappings). - Placeholders are resolved first. A
${...}in a path or media type is filled from the configuration, then checked. - Parameters a custom
HandlerMethodArgumentResolversupports are never reported: the resolver is asked first (see WebMvcConfigurer). - A
Mapparameter of@RequestParamor@RequestHeader, and anHttpHeadersone, are allowed: they are not simple values but take all values. - When the checks run. After every singleton bean is created (
afterSingletonsInstantiatedof therequestMappingHandlerMappingbean), before the server starts. The problems are thrown as oneStateError, which fails the start like any other startup error. - What is not checked here. The JSON classes are checked by the generator at build time and by the
ObjectMapperat run time; whether a service exists for a constructor parameter is checked by the container.
To see the mappings that passed, set logging.level.spring.web.mvc=trace: each is logged as Mapped GET /api/books/{isbn} -> BookController.find, after the count at debug level.
In Spring (Java)
Spring checks fewer things at startup. An ambiguous mapping fails the start (Ambiguous mapping. Cannot map 'orderController' method ...). A path variable without a parameter, a parameter nothing can fill, or a wrong @ExceptionHandler fail only the requests that reach them, often with a 500.