Dependency injection: constructor injection exclusively.
Banned: @Autowired on fields. @Autowired on setters.
Required: final fields. All dependencies injected via constructor.
Use: Lombok @RequiredArgsConstructor to reduce boilerplate.

// Banned — field injection
@Service
public class OrderService {
    @Autowired
    private OrderRepository orderRepository;  // Hidden dependency, untestable
}

// Required — constructor injection
@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderRepository orderRepository;  // Explicit, testable, immutable
}

Architecture layers (strict separation):
- @RestController: HTTP only — request mapping, validation, response shaping.
- @Service: business logic. No HTTP types. No JPA entity graph decisions.
- @Repository: data access. JPA queries, JDBC, caching.
- Domain: POJOs / records. No Spring annotations.
- Cross-layer: use DTOs. Never pass JPA entities to controllers.

// Wrong — business logic in controller
@PostMapping("/orders")
public ResponseEntity<Order> createOrder(@RequestBody OrderRequest req) {
    // 50 lines of business logic here
    if (inventory.getStock(req.getProductId()) < req.getQuantity()) {
        throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Insufficient stock");
    }
    // ...
}

// Right — controller delegates to service
@PostMapping("/orders")
public ResponseEntity<OrderResponse> createOrder(@Valid @RequestBody OrderRequest req) {
    OrderResponse order = orderService.createOrder(req);
    return ResponseEntity.status(HttpStatus.CREATED).body(order);
}

API contracts:
- Request: dedicated request DTO with @Valid validation annotations.
- Response: dedicated response DTO. Never return @Entity classes.
- Mapping: MapStruct for DTO-entity mapping. No manual getters/setters chains.
- Records: use Java records for immutable DTOs where appropriate.

// Banned — entity in response
@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
    return userRepository.findById(id).orElseThrow();  // Exposes everything
}

// Required — response DTO
public record UserResponse(Long id, String email, String displayName) {}

@GetMapping("/users/{id}")
public UserResponse getUser(@PathVariable Long id) {
    User user = userRepository.findById(id).orElseThrow(() -> new ResourceNotFoundException("User", id));
    return userMapper.toResponse(user);
}

Transactions:
- @Transactional on service methods, not controllers or repositories.
- Read-only queries: @Transactional(readOnly = true) — enables query optimizations.
- Never @Transactional on repository methods for business operations.
- Checked exceptions do NOT trigger rollback by default — use rollbackFor if needed.
- No @Transactional on private methods — Spring AOP won't intercept them.

// Wrong — @Transactional on private method (no effect)
@Service
public class PaymentService {
    @Transactional
    private void processPayment(Order order) { ... }  // AOP proxy can't intercept this
}

// Right — transaction on public service method
@Service
public class PaymentService {
    @Transactional(rollbackFor = PaymentException.class)
    public PaymentResult processPayment(Long orderId) {
        Order order = orderRepository.findById(orderId).orElseThrow();
        // business logic
    }

    @Transactional(readOnly = true)
    public List<PaymentSummary> getPaymentHistory(Long userId) { ... }
}

JPA fetch strategy:
- Default all associations to LAZY. Never EAGER on @ManyToOne or @OneToMany.
- Load what you need via JPQL JOIN FETCH or @EntityGraph.
- No accessing lazy collections outside a transaction (LazyInitializationException).
- Named queries or Spring Data specifications for complex queries.
- Pagination: always use Pageable — never load unbounded collections.

// Banned — EAGER by default (fetches User on every Order query)
@ManyToOne(fetch = FetchType.EAGER)
private User user;

// Required — LAZY, explicit when needed
@ManyToOne(fetch = FetchType.LAZY)
private User user;

// Load explicitly in the query that needs it
@Query("SELECT o FROM Order o JOIN FETCH o.user WHERE o.status = :status")
List<Order> findByStatusWithUser(@Param("status") OrderStatus status);

Validation:
- All input validation via Bean Validation annotations on DTOs (@NotNull, @Size, @Email, @Pattern).
- @Valid on controller method parameters — triggers validation automatically.
- @Validated on service beans for method-level validation.
- Custom validators: implement ConstraintValidator for business rules.
- Never validate in service layer what can be validated at the boundary.

public record CreateUserRequest(
    @NotBlank @Email String email,
    @NotBlank @Size(min = 8, max = 100) String password,
    @NotBlank @Size(min = 2, max = 50) String displayName
) {}

@PostMapping("/users")
public ResponseEntity<UserResponse> createUser(@Valid @RequestBody CreateUserRequest req) {
    // req is guaranteed valid here — no manual null checks needed
    return ResponseEntity.status(HttpStatus.CREATED).body(userService.createUser(req));
}

Error handling:
- Global exception handler: one @RestControllerAdvice class.
- Typed exception hierarchy: domain exceptions extend RuntimeException.
- Standard error response shape: { error, message, path, timestamp }.
- Never catch Exception broadly in service layer without rethrowing.
- HTTP status mapping in the advice class, not in service or repository.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ErrorResponse handleNotFound(ResourceNotFoundException ex, HttpServletRequest req) {
        return new ErrorResponse("not_found", ex.getMessage(), req.getRequestURI());
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ErrorResponse handleValidation(MethodArgumentNotValidException ex, HttpServletRequest req) {
        String message = ex.getBindingResult().getFieldErrors().stream()
            .map(e -> e.getField() + ": " + e.getDefaultMessage())
            .collect(Collectors.joining(", "));
        return new ErrorResponse("validation_failed", message, req.getRequestURI());
    }
}

Configuration:
- Group related config in @ConfigurationProperties classes.
- Validate with @Validated + Bean Validation annotations.
- No @Value on individual fields across multiple classes.
- Profiles: application-{profile}.yml for environment differences.
- Secrets: externalize via environment variables or secret manager — never in application.yml.

@ConfigurationProperties(prefix = "app.payment")
@Validated
public record PaymentConfig(
    @NotBlank String apiKey,
    @NotNull @Min(1) Integer timeoutSeconds,
    @NotBlank String webhookSecret
) {}

Security:
- Explicit SecurityFilterChain bean — no WebSecurityConfigurerAdapter (deprecated Spring Boot 3+).
- CSRF: disabled for stateless REST APIs using JWT. Enable for session-based apps.
- CORS: configure via CorsConfigurationSource bean, not annotations on controllers.
- Password encoding: BCryptPasswordEncoder only. Never store plain text or MD5.
- Method security: @PreAuthorize on service methods for business-level authorization.

Testing strategy:
- Unit tests: plain JUnit 5 + Mockito. No Spring context. Constructor injection makes this trivial.
- Web layer: @WebMvcTest for controllers. Mocks the service layer.
- Data layer: @DataJpaTest with H2 or Testcontainers for repositories.
- Integration: @SpringBootTest(webEnvironment = RANDOM_PORT) for full stack only.
- Never use @SpringBootTest for unit or slice tests — it's 10x slower.

// Web layer test — fast, no full context
@WebMvcTest(OrderController.class)
class OrderControllerTest {
    @Autowired MockMvc mockMvc;
    @MockBean OrderService orderService;

    @Test
    void createOrder_validRequest_returns201() throws Exception {
        given(orderService.createOrder(any())).willReturn(sampleOrderResponse());
        mockMvc.perform(post("/orders").contentType(APPLICATION_JSON).content(validOrderJson()))
            .andExpect(status().isCreated());
    }
}

Observability:
- Spring Boot Actuator: enabled with health, info, metrics endpoints.
- Health checks: custom HealthIndicator for external dependencies (DB, cache, external API).
- Metrics: Micrometer with Prometheus registry.
- Logging: structured JSON logging in production (logstash-logback-encoder).
- Correlation IDs: MDC for request tracing across log lines.

Async:
- @EnableAsync on configuration class.
- @Async methods: dedicated @Bean ThreadPoolTaskExecutor — not the default SimpleAsyncTaskExecutor.
- Return CompletableFuture<T> from async methods, not void (for error handling).
- Never call @Async methods from the same class — Spring AOP proxy won't intercept.
- Scheduled tasks: @Scheduled with fixedDelay or cron, with @EnableScheduling.

## Spring Boot Standards

**Version:** Spring Boot 3.x | Java 21+ | Gradle (Kotlin DSL)

### Architecture
- Strict layering: Controller → Service → Repository → Domain
- DTOs at every API boundary — never expose @Entity directly
- MapStruct for DTO-entity mapping

### Dependency Injection
- Constructor injection only. @Autowired on fields is banned.
- Use Lombok @RequiredArgsConstructor to reduce boilerplate.

### JPA / Database
- All associations: FetchType.LAZY by default
- Explicit JOIN FETCH or @EntityGraph when loading associations
- @Transactional(readOnly = true) on all read-only service methods
- Always paginate with Pageable — no unbounded findAll()

### Validation & Errors
- Bean Validation (@Valid) on all request DTOs
- One @RestControllerAdvice for all exception handling
- Typed exception hierarchy extending RuntimeException

### Security
- SecurityFilterChain bean (not WebSecurityConfigurerAdapter)
- BCryptPasswordEncoder for passwords
- @PreAuthorize on service methods for authorization

### Testing
- Unit tests: JUnit 5 + Mockito, no Spring context
- Controller tests: @WebMvcTest
- Repository tests: @DataJpaTest + Testcontainers
- @SpringBootTest only for integration tests