spring-conventions

Project Spring Boot & Security Conventions

Context

• Apply when writing or modifying Spring Boot application code, especially configuration, controllers, services, and exception handlers within this project.
• Ensures adherence to established patterns for security, dependency injection, validation, transaction management, exception handling, and configuration.
• Note: This project uses Gradle for build automation and dependency management.
• Note: Some requirements are Spring Boot 4+ specific (marked accordingly). This project supports both Spring Boot 3.5 and 4.0.
• For comprehensive security best practices, see [security.mdc](mdc:rules/common/security.mdc).
• For jOOQ DSL usage, see mdc:rules/java-common/jooq-database-access.mdc.
• For database retry logic, see mdc:rules/java-spring-boot/spring-retry-conventions.mdc.

Requirements

• Dependency Injection: Use constructor injection for all Spring-managed dependencies.
• Transaction Management: Define transactions at service method level using @Transactional. Use @Transactional(readOnly = true) for read-only methods and default @Transactional for write operations.
• Input Validation:
  • Annotate fields within request DTOs/models with Jakarta Bean Validation annotations (e.g., @NotNull, @Size, @Pattern, @Email, @Valid for nested objects).
  • Use the @Valid annotation on @RequestBody parameters in controller methods to trigger validation.
• Security Configuration: Configure SecurityFilterChain beans using the lambda DSL within an @Configuration class annotated with @EnableWebSecurity.
• Stateless Security: Disable CSRF and use SessionCreationPolicy.STATELESS for stateless JWT-based APIs.
• Authorization: Define authorization rules using authorizeHttpRequests with specific requestMatchers. Use anyRequest().authenticated() as a fallback. Ensure non-public Actuator endpoints (beyond /health) are appropriately secured (e.g., require authentication or specific roles).
• Method-Level Security: Use @PreAuthorize and @PostAuthorize for fine-grained method-level access control when needed.
• Enable Method Security: Enable method security via @EnableMethodSecurity in a configuration class.
• Exception Handling: Implement centralized exception handling using @ControllerAdvice. Include an @ExceptionHandler for MethodArgumentNotValidException to return 400 Bad Request for validation failures (preferably using RFC 7807 Problem details).
• Configuration Properties: Use @ConfigurationProperties for type-safe property binding. Enable validation with @Validated and Jakarta Bean Validation annotations.
• HTTP Clients: Prefer RestClient (Spring Boot 3.2+) for synchronous clients and WebClient for reactive. Spring Boot 4+: RestTemplate is deprecated; migrate to RestClient. Spring Boot 3.5: RestTemplate is still available but RestClient is preferred. Configure proper timeouts, error handling, and connection pooling. Use @RestClientTest/@WebFluxTest as appropriate.
• Caching: Use Spring Cache abstraction (@Cacheable, @CacheEvict, @CachePut) for expensive operations. Configure cache managers appropriately.
• Async Processing: Use @Async for non-blocking operations. Configure custom TaskExecutor beans for better thread management.
• Event Publishing: Use ApplicationEventPublisher to publish domain events for loose coupling. Handle events with @EventListener methods. Consider @TransactionalEventListener for events that should only fire after successful transaction commits.
• Logging: Use SLF4J (org.slf4j.Logger) for logging within application components.
• API Implementation: Implement OpenAPI generated interfaces in Controllers when applicable. NEVER modify files in src/generated/ — they are overwritten on every build.
• JWT Converters: Define custom JwtAuthenticationConverter beans when needing specific authority extraction logic (e.g., from scopes).
• Controllers: Keep controllers lean, delegating business logic to services. Use ResponseEntity for explicit response control.