spring-boot-patterns

name: spring-boot-patterns description: "Version-aware Spring Boot patterns (v2-v4), anti-patterns, and legacy detection. Constructor injection, SecurityFilterChain, RestClient, virtual threads, Micrometer, Spring Modulith, and GraalVM native image support." user-invocable: false allowed-tools: Read, Grep, Glob catalog_description: "Spring Boot patterns — injection, security, REST, testing slices, virtual threads, legacy detection."

Spring Boot Patterns & Anti-Patterns (v2-v4)

Legacy Anti-Pattern Detection

When analyzing a Spring Boot codebase, scan for these anti-patterns and quantify each category.

Critical Anti-Patterns (Must Fix)

Performance Anti-Patterns

Security Anti-Patterns

Version-Specific Patterns

Spring Boot 2.x Patterns (Java 8-17)

Standard patterns for v2.x (latest: 2.7.x):

// Security configuration with WebSecurityConfigurerAdapter (v2.x only)
@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .antMatchers("/api/public/**").permitAll()
                .antMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            .and()
            .oauth2ResourceServer()
                .jwt();
    }
}

// Service pattern with constructor injection (javax namespace)
import javax.persistence.EntityNotFoundException;
import javax.validation.Valid;

@Service
@Transactional(readOnly = true)
public class UserService {

    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;

    public UserService(UserRepository userRepository, PasswordEncoder passwordEncoder) {
        this.userRepository = userRepository;
        this.passwordEncoder = passwordEncoder;
    }

    @Transactional
    public User createUser(@Valid CreateUserRequest request) {
        var user = new User();
        user.setEmail(request.getEmail());
        user.setPassword(passwordEncoder.encode(request.getPassword()));
        return userRepository.save(user);
    }
}

// RestTemplate for HTTP calls (v2.x standard)
@Service
public class ExternalApiService {

    private final RestTemplate restTemplate;

    public ExternalApiService(RestTemplateBuilder builder) {
        this.restTemplate = builder
            .rootUri("https://api.example.com")
            .setConnectTimeout(Duration.ofSeconds(5))
            .setReadTimeout(Duration.ofSeconds(10))
            .build();
    }

    public UserDto fetchUser(String id) {
        return restTemplate.getForObject("/users/{id}", UserDto.class, id);
    }
}

Spring Boot 3.0 Patterns (Java 17+, Jakarta EE 10)

Key changes: javax to jakarta, Spring Security 6, native image support.

// Security with SecurityFilterChain (v3.0+ required)
@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
            .csrf(csrf -> csrf.ignoringRequestMatchers("/api/**"))
            .build();
    }
}

// Service pattern (jakarta namespace)
import jakarta.persistence.EntityNotFoundException;
import jakarta.validation.Valid;

@Service
@Transactional(readOnly = true)
public class UserService {

    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;

    public UserService(UserRepository userRepository, PasswordEncoder passwordEncoder) {
        this.userRepository = userRepository;
        this.passwordEncoder = passwordEncoder;
    }

    @Transactional
    public User createUser(@Valid CreateUserRequest request) {
        var user = new User();
        user.setEmail(request.getEmail());
        user.setPassword(passwordEncoder.encode(request.getPassword()));
        return userRepository.save(user);
    }

    public User getUser(Long id) {
        return userRepository.findById(id)
            .orElseThrow(() -> new EntityNotFoundException("User not found: " + id));
    }
}

// HTTP interfaces (v3.0+ declarative HTTP client)
public interface UserClient {

    @GetExchange("/users/{id}")
    UserDto getUser(@PathVariable String id);

    @PostExchange("/users")
    UserDto createUser(@RequestBody CreateUserRequest request);
}

// Configuration
@Configuration
public class HttpClientConfig {

    @Bean
    public UserClient userClient(RestClient.Builder builder) {
        RestClient restClient = builder.baseUrl("https://api.example.com").build();
        HttpServiceProxyFactory factory = HttpServiceProxyFactory
            .builderFor(RestClientAdapter.create(restClient))
            .build();
        return factory.createClient(UserClient.class);
    }
}

// Micrometer observation API (auto-configured in v3.0+)
@Service
public class OrderService {

    private final ObservationRegistry observationRegistry;
    private final OrderRepository orderRepository;

    public OrderService(ObservationRegistry observationRegistry, OrderRepository orderRepository) {
        this.observationRegistry = observationRegistry;
        this.orderRepository = orderRepository;
    }

    public Order createOrder(CreateOrderRequest request) {
        return Observation.createNotStarted("order.create", observationRegistry)
            .observe(() -> {
                var order = new Order(request);
                return orderRepository.save(order);
            });
    }
}

Spring Boot 3.2+ Patterns (Java 17+, Virtual Threads, RestClient)

Key changes: RestClient, virtual threads support, @ServiceConnection Testcontainers, SSL bundles.

// RestClient (v3.2+ replacement for RestTemplate)
@Service
public class ExternalApiService {

    private final RestClient restClient;

    public ExternalApiService(RestClient.Builder builder) {
        this.restClient = builder
            .baseUrl("https://api.example.com")
            .defaultHeader(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_VALUE)
            .build();
    }

    public UserDto fetchUser(String id) {
        return restClient.get()
            .uri("/users/{id}", id)
            .retrieve()
            .body(UserDto.class);
    }

    public List<UserDto> searchUsers(String query) {
        return restClient.get()
            .uri(uriBuilder -> uriBuilder
                .path("/users")
                .queryParam("q", query)
                .build())
            .retrieve()
            .body(new ParameterizedTypeReference<>() {});
    }

    public UserDto createUser(CreateUserRequest request) {
        return restClient.post()
            .uri("/users")
            .contentType(MediaType.APPLICATION_JSON)
            .body(request)
            .retrieve()
            .body(UserDto.class);
    }
}

# Virtual threads (application.yml, v3.2+)
spring:
  threads:
    virtual:
      enabled: true

// SSL bundles (v3.2+)
@Configuration
public class HttpClientConfig {

    @Bean
    public RestClient restClient(RestClient.Builder builder, SslBundles sslBundles) {
        return builder
            .baseUrl("https://secure-api.example.com")
            .apply(sslBundles.getBundle("my-cert").stores()::applyTo)
            .build();
    }
}

Spring Boot 4.0 Patterns (Nov 2025 — Spring Framework 7, Jakarta EE 11)

Key changes: Java 21 baseline, virtual threads default, structured concurrency, Spring Security 7, Spring Modulith default, built-in resilience (@Retryable/@ConcurrencyLimit), Jackson 3, API versioning, JSpecify null safety, RestTemplate deprecated.

// Virtual threads enabled by default (no configuration needed in v4)
// Platform threads only needed for thread-local-dependent code

// Structured concurrency (Java 21, v4.0)
@Service
public class OrderAggregationService {

    private final UserClient userClient;
    private final InventoryClient inventoryClient;
    private final PricingClient pricingClient;

    public OrderSummary getOrderSummary(String orderId) throws Exception {
        try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
            var userTask = scope.fork(() -> userClient.getUser(orderId));
            var inventoryTask = scope.fork(() -> inventoryClient.getStock(orderId));
            var pricingTask = scope.fork(() -> pricingClient.getPrice(orderId));

            scope.join().throwIfFailed();

            return new OrderSummary(
                userTask.get(),
                inventoryTask.get(),
                pricingTask.get()
            );
        }
    }
}

// Spring Security 7 (v4.0) — SecurityFilterChain for SPA (Angular/React)
// Note: @Bean no longer needs `throws Exception` — Security 7 removed it
@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) {
        return http
            .csrf(csrf -> csrf
                .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
                .csrfTokenRequestHandler(new SpaCsrfTokenRequestHandler()))
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/v1/**").permitAll()
                .anyRequest().authenticated())
            .build();
    }
}

// SPA CSRF helper — reads token from cookie, sends in X-XSRF-TOKEN header
// Required for Angular/React frontends that send CSRF via header, not form field
final class SpaCsrfTokenRequestHandler extends CsrfTokenRequestAttributeHandler {
    private final CsrfTokenRequestHandler delegate = new XorCsrfTokenRequestAttributeHandler();

    @Override
    public void handle(HttpServletRequest request, HttpServletResponse response,
                       Supplier<CsrfToken> csrfToken) {
        delegate.handle(request, response, csrfToken);
    }

    @Override
    public String resolveCsrfTokenValue(HttpServletRequest request, CsrfToken csrfToken) {
        return (request.getHeader(csrfToken.getHeaderName()) != null)
            ? super.resolveCsrfTokenValue(request, csrfToken)
            : delegate.resolveCsrfTokenValue(request, csrfToken);
    }
}

// Spring Security 7 (v4.0) — method-level authorization
@Service
@PreAuthorize("hasRole('USER')")
public class DocumentService {

    private final DocumentRepository documentRepository;

    public DocumentService(DocumentRepository documentRepository) {
        this.documentRepository = documentRepository;
    }

    @PostAuthorize("returnObject.owner == authentication.name")
    public Document getDocument(Long id) {
        return documentRepository.findById(id)
            .orElseThrow(() -> new EntityNotFoundException("Document not found"));
    }

    @PreAuthorize("hasRole('ADMIN') or #request.owner == authentication.name")
    public Document createDocument(CreateDocumentRequest request) {
        return documentRepository.save(new Document(request));
    }
}

// Spring Modulith (default in v4.0)
// Enforces module boundaries within a monolith

// Module structure:
// com.example.app.order/   — OrderService, OrderRepository, OrderController
// com.example.app.user/    — UserService, UserRepository
// com.example.app.payment/ — PaymentService

// Inter-module communication via ApplicationEventPublisher
@Service
@Transactional
public class OrderService {

    private final OrderRepository orderRepository;
    private final ApplicationEventPublisher events;

    public OrderService(OrderRepository orderRepository, ApplicationEventPublisher events) {
        this.orderRepository = orderRepository;
        this.events = events;
    }

    public Order placeOrder(CreateOrderRequest request) {
        var order = orderRepository.save(new Order(request));
        events.publishEvent(new OrderPlacedEvent(order.getId(), order.getUserId()));
        return order;
    }
}

// Listener in payment module
@Component
public class PaymentEventHandler {

    @ApplicationModuleListener
    public void onOrderPlaced(OrderPlacedEvent event) {
        // Process payment for the order
    }
}

// Built-in resilience — @Retryable and @ConcurrencyLimit (v4.0, no external dependency)
@Configuration
@EnableResilientMethods
public class ResilienceConfig {
}

@Service
public class PaymentService {

    private final PaymentGateway gateway;

    public PaymentService(PaymentGateway gateway) {
        this.gateway = gateway;
    }

    @Retryable  // Default: 3 attempts, 1s delay, exponential backoff with jitter
    @ConcurrencyLimit(10)  // Bulkhead: max 10 concurrent invocations
    public PaymentResult processPayment(PaymentRequest request) {
        return gateway.charge(request);
    }

    @Retryable(maxAttempts = 5, delay = 2000, multiplier = 2.0)
    public RefundResult processRefund(String transactionId) {
        return gateway.refund(transactionId);
    }
}

// API versioning — built-in (v4.0, first-class support)
@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping(url = "/{id}", version = "1.0")
    public UserV1Response getUserV1(@PathVariable Long id) {
        return userService.getUserV1(id);
    }

    @GetMapping(url = "/{id}", version = "1.1")
    public UserV2Response getUserV2(@PathVariable Long id) {
        return userService.getUserV2(id);  // Includes additional fields
    }
}

// Configure versioning strategy in app config
@Configuration
public class ApiVersionConfig {
    @Bean
    public ApiVersionStrategy apiVersionStrategy() {
        return ApiVersionStrategy.path();  // or .header(), .queryParam(), .mediaType()
    }
}

// Jackson 3 (v4.0 default — package changed from com.fasterxml.jackson to tools.jackson)
// Use JsonMapper instead of ObjectMapper
import tools.jackson.databind.json.JsonMapper;

@Configuration
public class JacksonConfig {

    @Bean
    public JsonMapper jsonMapper() {
        return JsonMapper.builder()
            .findAndAddModules()
            .build();
    }
}

// Jackson 3 defaults changed:
//   SORT_PROPERTIES_ALPHABETICALLY = true (was false)
//   WRITE_DATES_AS_TIMESTAMPS = false (ISO-8601 strings, was true)
// Backward compat flag: spring.jackson.use-jackson2-defaults=true

// JSpecify null safety (v4.0 — portfolio-wide adoption)
import org.jspecify.annotations.Nullable;
import org.jspecify.annotations.NonNull;

@Service
public class UserService {

    public @Nullable User findByEmail(String email) {
        return userRepository.findByEmail(email).orElse(null);
    }

    public @NonNull User getUser(Long id) {
        return userRepository.findById(id)
            .orElseThrow(() -> new EntityNotFoundException("User not found: " + id));
    }
}
// JSpecify replaces org.springframework.lang.Nullable
// Kotlin 2 auto-translates to Kotlin nullability
// IntelliJ 2025.3+ provides full data-flow analysis

// GraalVM native image support (matured in v3.0+, default tooling in v4.0)
// No code changes needed for most Spring Boot apps.
// Build native image:
//   Maven:  ./mvnw -Pnative native:compile
//   Gradle: ./gradlew nativeCompile

// Runtime hints for reflection (when needed)
@ImportRuntimeHints(MyRuntimeHints.class)
@Configuration
public class NativeConfig {
}

public class MyRuntimeHints implements RuntimeHintsRegistrar {
    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
        hints.reflection().registerType(ExternalDto.class,
            MemberCategory.INVOKE_DECLARED_CONSTRUCTORS,
            MemberCategory.INVOKE_DECLARED_METHODS);
    }
}

Controller Architecture

Modern REST Controller Pattern

@RestController
@RequestMapping("/api/v1/users")
@RequiredArgsConstructor  // Lombok for constructor injection
@Validated
public class UserController {

    private final UserService userService;

    @GetMapping
    public Page<UserResponse> listUsers(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size) {
        return userService.findAll(PageRequest.of(page, size))
            .map(UserResponse::from);
    }

    @GetMapping("/{id}")
    public UserResponse getUser(@PathVariable Long id) {
        return UserResponse.from(userService.getUser(id));
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public UserResponse createUser(@Valid @RequestBody CreateUserRequest request) {
        return UserResponse.from(userService.createUser(request));
    }

    @PutMapping("/{id}")
    public UserResponse updateUser(
            @PathVariable Long id,
            @Valid @RequestBody UpdateUserRequest request) {
        return UserResponse.from(userService.updateUser(id, request));
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void deleteUser(@PathVariable Long id) {
        userService.deleteUser(id);
    }
}

Repository Pattern

public interface UserRepository extends JpaRepository<User, Long> {

    Optional<User> findByEmail(String email);

    @Query("SELECT u FROM User u WHERE u.status = :status")
    Page<User> findByStatus(@Param("status") UserStatus status, Pageable pageable);

    @EntityGraph(attributePaths = {"roles", "department"})
    Optional<User> findWithRolesById(Long id);

    boolean existsByEmail(String email);

    @Modifying
    @Query("UPDATE User u SET u.status = :status WHERE u.id = :id")
    int updateStatus(@Param("id") Long id, @Param("status") UserStatus status);
}

State Management Decision Matrix

Technical Debt Scoring

When analyzing a Spring Boot project, generate scores in these categories:

Output format:

TECHNICAL DEBT REPORT: [Project Name]
=====================================
Overall Score: XX/100

Injection Pattern:    XX/15  (constructor: XX%, field @Autowired: XX)
Security Config:      XX/20  (filterchain: yes|no, csrf: ok|disabled, actuator: restricted|exposed)
API Design:           XX/15  (advice: yes|no, validation: XX%, error handling: rfc7807|stacktrace)
Testing:              XX/20  (ratio: XX%, slices: XX%, testcontainers: yes|no)
Version Compliance:   XX/15  (namespace: javax|jakarta, http client: template|restclient, boot: vX.X)
Code Quality:         XX/10  (sysout: XX, logging: param|concat, exceptions: specific|generic)
Tooling:              XX/5   (build: maven|gradle, lint: checkstyle|none, ci: yes|no)

Priority Migration Path:
1. [Highest impact item]
2. [Second highest]
3. ...