Spring Boot

---
name: spring-boot
description: "Expert skill for Spring Boot across all supported versions (3.x and 4.0). Provides deep expertise in IoC/DI, auto-configuration, Spring MVC, WebFlux, Spring Data, Spring Security, Actuator, configuration management, testing, and embedded servers. WHEN: \"Spring Boot\", \"Spring MVC\", \"WebFlux\", \"Spring Data\", \"Spring Security\", \"auto-configuration\", \"@SpringBootApplication\", \"Actuator\", \"Spring JPA\", \"Spring REST\", \"DispatcherServlet\", \"@RestController\", \"@ConfigurationProperties\", \"Spring profiles\", \"Spring testing\"."
license: MIT
---

# Spring Boot

This skill covers Spring Boot, the opinionated Java/Kotlin framework for building production-grade applications on the Spring ecosystem, across 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), see the `overview` skill.

## 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** -- Read the matching version reference (see Version-specific guidance 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 reference.

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):

```java
@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:

```java
@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+):

```java
@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

```java
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:

```java
@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`:

```java
@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-specific guidance

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

**Version-specific questions**: Read the matching reference above. Version references cover only what changed in that version -- fundamentals live here in this SKILL.md.

**Migration questions**:
- 2.x to 3.0: Read `references/versions/3.x.md` (Jakarta migration, Security 6, Java 17 baseline)
- 3.x to 4.0: Read `references/versions/4.0.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.