How a request travels
One GET /api/v1/orders/42, from the socket to MySQL and back.
Analogy cheat-sheet: a bank branch
You walk in and ask for the statement of account 42. Every Spring Boot layer has a person in that branch. Each step below adds an "In real life" note in these terms.
| In real life (bank branch) | In Spring Boot |
|---|---|
| You, with a request slip | The HTTP client |
| A free teller who serves you start to finish | Tomcat worker thread (up to 200) |
| Security guard at the door | Servlet filters (Spring Security) |
| Help desk that reads your slip | DispatcherServlet |
| Directory board: "Statements → counter 3" | HandlerMapping |
| Counter's own checks and sign-out sheet | HandlerInterceptor |
| Assistant who turns your scribble into a proper form | HandlerAdapter + Jackson + @Valid |
| Clerk with a numbered "transaction folder" | @Transactional service (AOP proxy) |
| Vault key hook with 10 keys | HikariCP connection pool |
| The vault with the ledgers | MySQL |
The same trip as real code
This is all you write. Everything else in the diagram happens around it.
@RestController
class OrderController {
@GetMapping("/api/v1/orders/{id}") // HandlerMapping finds this method
Order get(@PathVariable Long id) { // HandlerAdapter turns "42" into a Long
return service.find(id); // goes through the service proxy
}
}
@Service
class OrderService {
@Transactional(readOnly = true) // proxy opens the "folder" and borrows a key
Order find(Long id) {
return repo.findById(id) // Hikari key, then MySQL
.orElseThrow(() -> new OrderNotFoundException(id)); // exception path
}
}
@RestControllerAdvice // the pre-printed rejection letters
class Errors {
@ExceptionHandler(OrderNotFoundException.class)
ResponseEntity<?> notFound(OrderNotFoundException e) {
return ResponseEntity.status(404).body(
Map.of("error", "ORDER_NOT_FOUND", "message", e.getMessage(), "status", 404));
}
}
Insight: three places to intercept, three altitudes
| Servlet Filter | HandlerInterceptor | AOP proxy (@Transactional, @Aspect) | |
|---|---|---|---|
| Belongs to | Servlet container | Spring MVC | Spring bean |
| Runs | Before DispatcherServlet | Around the controller call | Around any bean method |
| Knows | Raw request/response | Which controller method was matched | Method, arguments, return value |
| Use for | Auth, CORS, request IDs, access logs | Per-endpoint checks, timing by handler | Transactions, caching, audit |
Trade-off: one thread per request
Spring MVC on Tomcat is blocking. A worker thread (default max 200) and a Hikari connection (default max 10) are held for the whole request. It is simple to reason about and debug. It stops scaling when requests wait on slow I/O, because threads pile up. WebFlux or virtual threads (spring.threads.virtual.enabled=true, Boot 3.2+) change that trade.
Where to look when…
| Symptom | Suspect |
|---|---|
| 401/403 and your controller never logs | Security filter chain. It rejects before DispatcherServlet. |
| 404 for a URL that "should" exist | HandlerMapping: wrong path, verb or Content-Type; component scan missed the controller. |
| 400 with a body-parse or validation error | Argument resolver: Jackson deserialization or @Valid. |
| Slow requests, DB looks idle | Hikari pool exhausted or long @Transactional methods. See chapter 2. |
| Data written, then half-rolled back or not at all | Self-invocation bypassed the proxy, or a checked exception committed. |
Recap
- Tomcat gives each request a thread; filters run before Spring MVC knows the controller.
DispatcherServletorchestrates:HandlerMapping→ interceptors →HandlerAdapter→ your method.- Your service is a proxy; the transaction and the DB connection live as long as the proxied method.
- Responses unwind the same layers in reverse. Exceptions are turned into responses by
@RestControllerAdviceinsideDispatcherServlet, before the filters see the result.