spring-boot request lifecycle

server:
  port: 8080
  servlet:
    context-path: /console
  tomcat:
    threads:
      max: 200 # max worker threads (ignored if virtual threads enabled)
      min-spare: 10
    max-connections: 8192
    accept-count: 100
 
# Virtual threads → mỗi request 1 virtual thread, no pool limit
spring:
  threads:
    virtual:
      enabled: true

@Slf4j
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class RequestTracingFilter extends OncePerRequestFilter {
 
    @Override
    protected void doFilterInternal(HttpServletRequest request,
            HttpServletResponse response, FilterChain chain)
            throws ServletException, IOException {
 
        String traceId = Optional.ofNullable(request.getHeader("X-Request-Id"))
                                 .orElseGet(() -> UUID.randomUUID().toString());
 
        MDC.put("requestId", traceId); // Gắn vào Mapped Diagnostic Context
        response.setHeader("X-Request-Id", traceId);
 
        long start = System.nanoTime();
        try {
            chain.doFilter(request, response); // Chuyền tay cho Filter tiếp theo
        } finally {
            long duration = (System.nanoTime() - start) / 1_000_000;
            log.info("[traceId={}] {} {} → {} ({}ms)",
                traceId, request.getMethod(), request.getRequestURI(),
                response.getStatus(), duration);
            MDC.clear(); // Bắt buộc phải dọn dẹp để tránh rò rỉ context giữa các Thread
        }
    }
}

SecurityFilterChain (ordered filters):
 1. DisableEncodeUrlFilter
 2. WebAsyncManagerIntegrationFilter
 3. SecurityContextHolderFilter
 4. HeaderWriterFilter
 5. CorsFilter
 6. CsrfFilter (disabled for stateless)
 7. LogoutFilter
 8. BearerTokenAuthenticationFilter ← JWT validation
 9. RequestCacheAwareFilter
 10. SecurityContextHolderAwareRequestFilter
 11. AnonymousAuthenticationFilter
 12. SessionManagementFilter
 13. ExceptionTranslationFilter
 14. AuthorizationFilter ← URL-based access rules

// DispatcherServlet pseudocode:
HandlerExecutionChain chain = handlerMapping.getHandler(request);
// chain = controller method + interceptors
Object handler = chain.getHandler();
 
// Run interceptors pre-handle
for (HandlerInterceptor interceptor : chain.getInterceptors()) {
   if (!interceptor.preHandle(request, response, handler)) {
       return; // short-circuit (afterCompletion vẫn chạy cho các interceptor đã preHandle thành công)
   }
}
 
// Invoke controller method
// Với @RestController/@ResponseBody, JSON được ghi ra response ngay trong bước này
ModelAndView mv = handlerAdapter.handle(request, response, handler);
 
// Run interceptors post-handle (thực tế chạy theo thứ tự NGƯỢC với preHandle)
for (HandlerInterceptor interceptor : chain.getInterceptors()) {
   interceptor.postHandle(request, response, handler, mv);
}

@Component
public class AuditInterceptor implements HandlerInterceptor {
 
   @Override
   public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
                            Object handler) {
       // Runs AFTER security filters, BEFORE controller
       // handler = HandlerMethod (controller method info)
       if (handler instanceof HandlerMethod hm) {
           log.info("Calling {}.{}()", hm.getBeanType().getSimpleName(), hm.getMethod().getName());
       }
       return true; // continue chain
   }
 
   @Override
   public void postHandle(HttpServletRequest request, HttpServletResponse response,
                          Object handler, ModelAndView modelAndView) {
       // After controller (only if no exception).
       // Với @RestController/ResponseEntity, response body đã được ghi xong trước khi tới đây,
       // nên không sửa header/body ở postHandle được nữa
   }
 
   @Override
   public void afterCompletion(HttpServletRequest request, HttpServletResponse response,
                               Object handler, Exception ex) {
       // Luôn chạy nếu preHandle đã trả true, kể cả khi có exception.
       // Lưu ý: ex chỉ khác null khi exception KHÔNG được @ExceptionHandler xử lý
       // Good for cleanup
   }
}
 
// Register
@Configuration
@RequiredArgsConstructor
public class WebConfig implements WebMvcConfigurer {
   private final AuditInterceptor auditInterceptor;
 
   @Override
   public void addInterceptors(InterceptorRegistry registry) {
       registry.addInterceptor(auditInterceptor)
           .addPathPatterns("/api/**")
           .excludePathPatterns("/api/public/**");
   }
}

@RestController
@RequestMapping("/api/orders")
@RequiredArgsConstructor
public class OrderController {
   private final OrderService orderService;
 
   @PostMapping
   public ResponseEntity<APIResponse<OrderDTO>> createOrder(
           @Valid @RequestBody CreateOrderRequest request,  // ← Jackson deserialize + validate
           @AuthenticationPrincipal Jwt jwt,                // ← extract from SecurityContext
           @RequestHeader("X-Workspace-Id") UUID workspaceId // ← header extraction
   ) {
       // If @Valid fails → MethodArgumentNotValidException → @ExceptionHandler
       // If header type conversion fails → MethodArgumentTypeMismatchException
       // If header missing → MissingRequestHeaderException
       // If body missing or malformed JSON → HttpMessageNotReadableException
       OrderDTO result = orderService.createOrder(request, jwt.getSubject());
       return ResponseEntity.status(201).body(APIResponse.success(result));
   }
}

@Valid @RequestBody CreateOrderRequest
 → Jackson ObjectMapper.readValue(body, CreateOrderRequest.class)
 → Jakarta Bean Validation
   → @NotNull, @NotBlank, @Size, @Pattern...
   → Custom @ValidXxx → XxxValidator.isValid()
 → If violations → MethodArgumentNotValidException
 → Else → pass to controller method

@RestController
@RequiredArgsConstructor
public class OrderController {
   private final OrderService orderService; // ← injected PROXY, not real instance
 
   @PostMapping("/api/orders")
   public ResponseEntity<?> create(@Valid @RequestBody CreateOrderRequest req,
                                   @AuthenticationPrincipal Jwt jwt) {
       OrderDTO result = orderService.createOrder(req, jwt.getSubject());
       return ResponseEntity.status(201).body(APIResponse.success(result));
   }
}

Proxy.createOrder()
 → @PreAuthorize check (if present)
 → @Transactional interceptor (begin TX)
 → @LogExecutionTime aspect (if present)
 → Real OrderService.createOrder()
 → @Transactional interceptor (commit or rollback)

@Service
@RequiredArgsConstructor
@Slf4j
public class OrderService {
   private final OrderRepository orderRepo;
   private final ProductService productService;
   private final ApplicationEventPublisher eventPublisher;
 
   @Transactional
   public OrderDTO createOrder(CreateOrderRequest req, String userId) {
       // 1. Business validation
       Product product = productService.getById(req.getProductId());
       if (!product.isAvailable()) {
           throw new BusinessException("PRODUCT_UNAVAILABLE");
       }
 
       // 2. Create entity
       Order order = Order.builder()
           .customerId(userId)
           .productId(product.getId())
           .quantity(req.getQuantity())
           .status(OrderStatus.PENDING)
           .build();
 
       // 3. Persist: entity vào persistence context; INSERT thường chờ tới lúc flush/commit
       //    (riêng ID kiểu IDENTITY thì INSERT chạy ngay để lấy ID)
       Order saved = orderRepo.save(order);
 
       // 4. Publish event: mặc định ĐỒNG BỘ, listener chạy ngay trong thread và transaction này.
       //    Muốn chạy sau khi commit thì dùng @TransactionalEventListener, muốn async thì thêm @Async
       eventPublisher.publishEvent(new OrderCreatedEvent(this, saved));
 
       // 5. Map to DTO
       return OrderMapper.INSTANCE.toDTO(saved);
   }
   // If RuntimeException/Error → @Transactional proxy rollbacks
   //    (checked exception mặc định vẫn COMMIT, trừ khi khai báo rollbackFor)
   // If success → @Transactional proxy commits
}

public interface OrderRepository extends JpaRepository<Order, UUID> {
   // Spring Data generates implementation at runtime
}

@Transactional begin
 → Get JDBC connection from HikariCP pool, setAutoCommit(false)
repo.save(order)
 → isNew(order)? → EntityManager.persist(order)
 → else          → EntityManager.merge(order)
 → Hibernate:
   → Generate ID (UUID/sequence); IDENTITY thì phải INSERT ngay để lấy ID
   → Entity enters "managed" state (persistence context = first-level cache)
   → INSERT/UPDATE còn lại nằm trong action queue, chưa chạy
 → At TX commit:
   → Flush persistence context (dirty checking)
   → Execute pending SQLs (batch nếu bật hibernate.jdbc.batch_size)
   → JDBC connection.commit()
   → Return connection to pool

spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      idle-timeout: 300000
      connection-timeout: 20000
      max-lifetime: 1200000

Thread requests connection
 → Pool has idle connection? → Return immediately
 → Pool at max? → Wait (up to connection-timeout)
 → Timeout exceeded? → SQLTransientConnectionException

@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {
 
   // Validation errors
   @ExceptionHandler(MethodArgumentNotValidException.class)
   public ResponseEntity<APIResponse<?>> handleValidation(MethodArgumentNotValidException ex) {
       List<String> errors = ex.getBindingResult().getFieldErrors().stream()
           .map(e -> e.getField() + ": " + e.getDefaultMessage())
           .toList();
       return ResponseEntity.badRequest()
           .body(APIResponse.error("VALIDATION_ERROR", errors));
   }
 
   // Business exceptions
   @ExceptionHandler(BusinessException.class)
   public ResponseEntity<APIResponse<?>> handleBusiness(BusinessException ex) {
       log.warn("[traceId={}] Business error: {}", RequestContext.getRequestId(), ex.getMessage());
       return ResponseEntity.badRequest()
           .body(APIResponse.error(ex.getCode(), ex.getMessage()));
   }
 
   // Not found
   @ExceptionHandler(EntityNotFoundException.class)
   public ResponseEntity<APIResponse<?>> handleNotFound(EntityNotFoundException ex) {
       return ResponseEntity.status(404)
           .body(APIResponse.error("NOT_FOUND", ex.getMessage()));
   }
 
   // Catch-all
   @ExceptionHandler(Exception.class)
   public ResponseEntity<APIResponse<?>> handleUnexpected(Exception ex) {
       log.error("[traceId={}] Unexpected error", RequestContext.getRequestId(), ex);
       return ResponseEntity.status(500)
           .body(APIResponse.error("INTERNAL_ERROR", "An unexpected error occurred"));
   }
}

Exception thrown in Service/Repository
 → Bubbles up through AOP proxies
   → @Transactional catches → rollback TX
 → Reaches DispatcherServlet
 → DispatcherServlet delegates to HandlerExceptionResolver
 → @RestControllerAdvice @ExceptionHandler matched
 → Error response serialized → returned to client
 → HandlerInterceptor.afterCompletion called (ex = null vì exception đã được xử lý)
 → Filter chain unwinds (finally blocks)

// Controller returns object → Jackson serializes to JSON
@GetMapping("/orders/{id}")
public OrderDTO getOrder(@PathVariable UUID id) {
   return orderService.getById(id); // ← Jackson calls getters, serializes
}

Return value (OrderDTO)
 → ContentNegotiation (Accept header → application/json)
 → MappingJackson2HttpMessageConverter
   → Set Content-Type: application/json
   → ObjectMapper writes dto directly to response OutputStream
   → Custom serializers (@JsonSerialize)
   → @JsonIgnore, @JsonProperty handling
 → Response body written (and usually committed)

@Configuration
public class JacksonConfig {
   @Bean
   public ObjectMapper objectMapper() {
       return JsonMapper.builder()
           .addModule(new JavaTimeModule())
           .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
           .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
           .serializationInclusion(JsonInclude.Include.NON_NULL)
           .build();
   }
}

[0ms]    Request arrives at Tomcat
[1ms]    Filter: RequestTracingFilter (assign traceId)
[2ms]    Filter: SecurityFilterChain (JWT validation, JWKS cache hit)
[3ms]    DispatcherServlet: resolve handler
[3ms]    Interceptor: preHandle
[4ms]    Argument resolution: deserialize JSON body
[5ms]    Bean Validation: @Valid check
[5ms]    Controller method invoked
[6ms]    AOP: @Transactional begin (get connection from pool)
[7ms]    Service: business logic
[8ms]    Repository: load product, save order
[9ms]    Execute SQL query (DB round-trip)
[12ms]   Repository: return entity
[13ms]   Service: map to DTO, publish event
[14ms]   AOP: @Transactional commit (flush INSERT, commit)
[15ms]   Controller: return ResponseEntity
[16ms]   Jackson: serialize DTO → JSON
[16ms]   Interceptor: postHandle, afterCompletion
[17ms]   Filter chain: cleanup MDC
[17ms]   Response sent to client

Tomcat Thread (or Virtual Thread)
 ├── SecurityContext (Authentication object)
 ├── MDC (traceId, userId for logging)
 ├── ScopedValue (RequestContext.REQUEST_ID)
 ├── LocaleContext (i18n)
 └── Transaction (bound to thread via TransactionSynchronizationManager)

1. Filter.doFilter (before)
2. Security filters (authentication + authorization)
3. Interceptor.preHandle
4. Argument resolution + validation
5. Controller method
6. AOP around advice on service (before, begin TX)
7. Service method (within TX)
8. Repository → DB
9. Service returns
10. AOP around advice (after, commit TX)
11. Controller returns
12. Response serialization (@ResponseBody / ResponseEntity)
13. Interceptor.postHandle
14. Interceptor.afterCompletion
15. Filter.doFilter (after/finally)

1-7.  Same as happy path until exception
8.    Exception thrown
9.    @Transactional rollback
10.   AOP after-throwing advice
11.   Exception bubbles to DispatcherServlet
12.   @ExceptionHandler resolves error response
13.   Interceptor.afterCompletion (ex = null nếu đã được @ExceptionHandler xử lý)
14.   Filter finally blocks (MDC cleanup)
15.   Error response sent