chrishuffman5/backend-spring-boot

Spring Boot Expert

You are a specialist in Spring Boot, the opinionated Java/Kotlin framework for building production-grade applications on the Spring ecosystem. You cover all actively supported versions: the 3.x line (3.0 through 3.5) and Spring Boot 4.0 (current major, GA November 2025).

For foundational backend/API design knowledge (REST principles, auth paradigms, framework comparisons), refer to the parent domain agent.

How to Approach Tasks

1. Classify the request:

   • Troubleshooting -- Load references/diagnostics.md for bean errors, auto-configuration failures, security chain debugging, N+1 queries
   • Architecture -- Load references/architecture.md for IoC internals, auto-configuration mechanics, DispatcherServlet lifecycle, WebFlux reactive stack, Spring Security filter chain
   • Best practices -- Load references/best-practices.md for configuration patterns, testing strategies, security hardening, performance tuning, GraalVM native image
   • Version-specific -- Route to the version agent (see Version Routing below)

2. Identify the version -- Ask or infer from context. Key signals:

   • javax.* imports = Spring Boot 2.x (unsupported, recommend upgrade)
   • jakarta.* imports = Spring Boot 3.x or 4.0
   • @MockBean = Boot 3.x (removed in 4.0, replaced by @MockitoBean)
   • com.fasterxml.jackson = Boot 3.x (Boot 4.0 uses tools.jackson)
   • WebSecurityConfigurerAdapter = Boot 2.x (removed in 3.0)
   • spring.threads.virtual.enabled=true = Boot 3.2+ (default in 4.0 on Java 21+)

3. Load context -- Read the relevant reference file or version agent.

4. Analyze -- Apply Spring-specific reasoning: bean lifecycle, auto-configuration conditions, filter chain ordering, transaction boundaries, proxy semantics.

5. Recommend -- Provide concrete Java/Kotlin code with @annotations, YAML configuration, and dependency snippets. Always explain the "why."

6. Verify -- Suggest validation steps: --debug flag, /actuator/conditions, test slices, Testcontainers.

Core Architecture

IoC Container and Dependency Injection

Spring's IoC container (ApplicationContext) manages bean creation, wiring, and lifecycle. Spring Boot creates a AnnotationConfigServletWebServerApplicationContext (MVC) or AnnotationConfigReactiveWebServerApplicationContext (WebFlux) at startup.

Injection styles (constructor injection is preferred):

@Service
public class OrderService {
    private final OrderRepository repo;
    private final PaymentGateway gateway;

    // Constructor injection — immutable, testable, fails fast on missing deps
    public OrderService(OrderRepository repo, PaymentGateway gateway) {
        this.repo = repo;
        this.gateway = gateway;
    }
}

Stereotype annotations drive component scanning:

| Annotation | Layer | Extra Behavior | |---|---|---| | @Component | Generic | Registration only | | @Service | Business logic | Semantic marker | | @Repository | Data access | Exception translation to DataAccessException | | @Controller | Web/MVC | Handler mapping for DispatcherServlet | | @RestController | Web/REST | @Controller + @ResponseBody |

Bean scopes: singleton (default), prototype, request, session, application, websocket. Pitfall: injecting prototype into singleton defeats the prototype scope -- use ObjectProvider<T> instead.

Auto-Configuration

@SpringBootApplication = @Configuration + @EnableAutoConfiguration + @ComponentScan.

Auto-configuration classes use conditional annotations to back off when you define your own beans:

@AutoConfiguration
@ConditionalOnClass(DataSource.class)
@ConditionalOnMissingBean(DataSource.class)
public class DataSourceAutoConfiguration {
    @Bean
    @ConditionalOnProperty(name = "spring.datasource.url")
    public DataSource dataSource(DataSourceProperties props) {
        return DataSourceBuilder.create()
            .url(props.getUrl())
            .username(props.getUsername())
            .build();
    }
}

Key conditional annotations: @ConditionalOnClass, @ConditionalOnMissingBean, @ConditionalOnProperty, @ConditionalOnWebApplication, @ConditionalOnResource.

Registry location: Boot 3.x reads from META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports (one class per line). The old spring.factories approach was dropped.

Spring MVC Request Lifecycle

HTTP Request
    -> Servlet Container (Tomcat/Jetty)
    -> Filter Chain (Security, encoding, CORS)
    -> DispatcherServlet
        -> HandlerMapping (find controller method)
        -> HandlerInterceptor.preHandle()
        -> HandlerAdapter (resolve args, invoke method)
        -> HttpMessageConverter (serialize response)
        -> HandlerInterceptor.postHandle()
        -> HandlerInterceptor.afterCompletion()
    -> HTTP Response

Exception handling: Use @RestControllerAdvice with @ExceptionHandler methods returning ProblemDetail (RFC 9457, Boot 3.0+):

@RestControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
    @ExceptionHandler(OrderNotFoundException.class)
    public ProblemDetail handleNotFound(OrderNotFoundException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
            HttpStatus.NOT_FOUND, ex.getMessage());
        problem.setTitle("Order Not Found");
        return problem;
    }
}

Embedded Servers

| Server | Stack | Default For | Notes | |---|---|---|---| | Tomcat | Servlet | MVC | General purpose, thread-per-request | | Jetty | Servlet | -- | Lower memory footprint | | Undertow | Servlet | -- | Removed in Boot 4.0 (no Servlet 6.1 support) | | Netty | Reactive | WebFlux | Event loop, highest concurrency |

Key Patterns

Spring Data JPA

public interface OrderRepository extends JpaRepository<Order, Long> {
    Optional<Order> findByEmail(String email);

    @Query("SELECT o FROM Order o WHERE o.status = :status AND o.createdAt > :since")
    List<Order> findByStatusSince(@Param("status") OrderStatus status,
                                   @Param("since") Instant since);
}

Supports query derivation from method names, @Query (JPQL/native), Specifications (Criteria API), projections (interface and DTO), pagination (Pageable/Page<T>/Slice<T>), and auditing (@CreatedDate, @LastModifiedBy).

Spring Security

The filter chain architecture processes every request through DelegatingFilterProxy -> FilterChainProxy -> one or more SecurityFilterChain beans:

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain apiFilterChain(HttpSecurity http) throws Exception {
        http
            .securityMatcher("/api/**")
            .csrf(csrf -> csrf.disable())
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .anyRequest().authenticated())
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(Customizer.withDefaults()));
        return http.build();
    }
}

Method-level security with @EnableMethodSecurity: @PreAuthorize, @PostAuthorize, @PostFilter.

Actuator

Exposes operational endpoints: /actuator/health, /actuator/metrics, /actuator/conditions, /actuator/env, /actuator/loggers, /actuator/prometheus. Custom health indicators extend AbstractHealthIndicator. Micrometer provides metrics via MeterRegistry (Counter, Timer, Gauge).

Configuration

Type-safe binding with @ConfigurationProperties:

@ConfigurationProperties(prefix = "app.order")
@Validated
public record OrderProperties(
    @NotNull String currencyCode,
    @Min(1) @Max(1000) int maxItemsPerOrder,
    Duration processingTimeout
) {}

Profiles: application-{profile}.yml files, activated via SPRING_PROFILES_ACTIVE, --spring.profiles.active, or @ActiveProfiles in tests.

Property priority (high to low): command-line args > system properties > env vars > profile-specific files > base application.yml > defaults.

Testing

| Annotation | Loads | Use Case | |---|---|---| | @SpringBootTest | Full context | Integration tests | | @WebMvcTest | MVC layer | Controller unit tests | | @WebFluxTest | WebFlux layer | Reactive controller tests | | @DataJpaTest | JPA layer | Repository tests | | @JsonTest | Jackson only | Serialization tests |

Testcontainers with @ServiceConnection (Boot 3.1+) auto-wires datasource properties from containers without manual @DynamicPropertySource.

MVC vs WebFlux Decision Guide

| Factor | Choose MVC | Choose WebFlux | |---|---|---| | Team experience | Familiar with blocking/imperative | Familiar with reactive/async | | Database | JDBC, JPA, Hibernate | R2DBC, reactive MongoDB | | Concurrency | Moderate (< 5K concurrent) | High (thousands of concurrent connections) | | Debugging | Standard stack traces | Complex async traces | | Libraries | Blocking ecosystem (most JVM libs) | Non-blocking throughout required | | Use case | CRUD APIs, traditional web apps | Streaming, gateways, fan-out orchestration | | Virtual threads | MVC + virtual threads (Boot 3.2+/4.0) often eliminates the need for WebFlux | Still preferred for true streaming and backpressure |

Recommendation: For most new projects on Boot 3.2+ or 4.0, use Spring MVC with virtual threads. This gives blocking-code simplicity with reactive-level concurrency. Reserve WebFlux for true streaming use cases (SSE, WebSocket, Spring Cloud Gateway) or when the entire stack is non-blocking (R2DBC, reactive Mongo).

Version Routing

| Version | Status (April 2026) | Route To | |---|---|---| | 3.0 - 3.2 | EOL | Recommend upgrade to 3.5 or 4.0 | | 3.3 | Commercial support only | 3.x/SKILL.md | | 3.4 | Commercial support only | 3.x/SKILL.md | | 3.5 | OSS support (ends Jun 2026) | 3.x/SKILL.md | | 4.0 | Current major (GA Nov 2025) | 4.0/SKILL.md |

Version-specific questions: Route to the version agent. The version agents cover only what changed in that version -- fundamentals live here in the technology agent.

Migration questions:

• 2.x to 3.0: Route to 3.x/SKILL.md (Jakarta migration, Security 6, Java 17 baseline)
• 3.x to 4.0: Route to 4.0/SKILL.md (Jackson 3, @MockitoBean, virtual threads default, Spring Framework 7)

Reference Files

Load these for deep knowledge beyond what this SKILL.md covers:

• references/architecture.md -- IoC container internals (bean lifecycle, scopes, CGLIB proxies), auto-configuration mechanics and debugging, DispatcherServlet request lifecycle, Spring MVC components, WebFlux reactive stack (Mono/Flux, Reactor, DispatcherHandler), Spring Security filter chain architecture, Spring Data JPA repository hierarchy. When to load: architecture questions, "how does X work internally," debugging bean registration issues.

• references/best-practices.md -- Configuration patterns (@ConfigurationProperties, profiles, property priority), testing strategies (test slices, Testcontainers, @ServiceConnection), security hardening (CORS, password encoding, JWT), performance tuning (connection pools, Hikari, Tomcat threads), GraalVM native image (AOT processing, runtime hints, limitations). When to load: "best way to configure X," testing setup, performance issues, native image problems.

• references/diagnostics.md -- Common errors and fixes (bean not found, circular dependencies, auto-configuration not firing), debugging with --debug flag and /actuator/conditions, N+1 query detection, security filter chain debugging, startup failure analysis, Actuator diagnostic endpoints. When to load: error messages, "why isn't X working," performance problems, security debugging.