Spring Boot Annotations Cheat Sheet: The Definitive Guide

package io.thecodeforge.annotations;

import org.springframework.web.bind.annotation.*;
import org.springframework.stereotype.*;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.ResponseEntity;
import org.springframework.dao.DataAccessException;

/**
 * io.thecodeforge: Stereotype annotations in a standard three-layer architecture.
 *
 * @RestController → web layer, handles HTTP
 * @Service        → business layer, contains logic
 * @Repository     → data layer, adds exception translation
 */
@RestController
@RequestMapping("/api/v1/forge")
public class ForgeController {

    private final ForgeService service;

    // Constructor injection: preferred over @Autowired on fields.
    // Dependencies are explicit, final, and testable without Spring context.
    public ForgeController(ForgeService service) {
        this.service = service;
    }

    @PostMapping("/process/{id}")
    public ResponseEntity<String> executeJob(
            @PathVariable("id") Long id,
            @RequestBody JobRequest request) {
        String result = service.process(id, request.getPayload());
        return ResponseEntity.ok(result);
    }
}

@Service
class ForgeService {

    // @Value injects property values from application.yml or environment variables.
    // The :production part is the default if the property is not defined.
    @Value("${forge.environment:production}")
    private String env;

    private final ForgeRepository repository;

    public ForgeService(ForgeRepository repository) {
        this.repository = repository;
    }

    public String process(Long id, String data) {
        try {
            repository.save(id, data);
            return String.format("Env: %s | Job %d processed: %s", env, id, data);
        } catch (DataAccessException ex) {
            // @Repository's exception translation means we catch DataAccessException
            // here regardless of whether the underlying store is JDBC, JPA, or MongoDB.
            // Without @Repository on ForgeRepository, this catch block gets SQLException instead.
            throw new RuntimeException("Failed to persist job " + id, ex);
        }
    }
}

// @Repository adds exception translation — SQLExceptions become DataAccessExceptions.
// Without this annotation, raw persistence exceptions leak into the service layer.
@Repository
class ForgeRepository {
    public void save(Long id, String data) {
        // JDBC or JPA persistence logic here
    }
}

class JobRequest {
    private String payload;
    public String getPayload() { return payload; }
    public void setPayload(String payload) { this.payload = payload; }
}

package io.thecodeforge.annotations.web;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import jakarta.validation.Valid;
import java.util.Map;

/**
 * io.thecodeforge: Web annotation reference — every annotation you use in a REST controller.
 */
@RestController  // = @Controller + @ResponseBody on every method
@RequestMapping("/api/v1/orders")
public class OrderController {

    // @GetMapping is shorthand for @RequestMapping(method = RequestMethod.GET)
    // Use shortcuts — they communicate intent faster than the verbose form.
    @GetMapping("/{orderId}")
    public ResponseEntity<OrderDto> getOrder(
            // @PathVariable: extracts {orderId} from the URI template
            @PathVariable Long orderId,
            // @RequestHeader: extracts a specific HTTP header — useful for correlation IDs
            @RequestHeader(value = "X-Correlation-Id", required = false) String correlationId) {

        // In real code: return orderService.findById(orderId)
        return ResponseEntity.ok(new OrderDto(orderId, "PENDING"));
    }

    @GetMapping
    public ResponseEntity<Object> searchOrders(
            // @RequestParam: extracts query string parameters
            // /api/v1/orders?status=PENDING&page=0
            @RequestParam(value = "status", required = false, defaultValue = "ALL") String status,
            @RequestParam(value = "page", defaultValue = "0") int page) {

        return ResponseEntity.ok(Map.of("status", status, "page", page));
    }

    // @ResponseStatus sets the default HTTP response code for this method.
    // Without it, POST endpoints return 200 OK — semantically wrong for a creation.
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)  // Returns 201 Created on success
    public OrderDto createOrder(
            // @RequestBody: deserializes JSON request body into OrderDto via Jackson
            // @Valid: triggers Bean Validation on the deserialized object
            @Valid @RequestBody OrderDto dto) {
        return dto;
    }

    @DeleteMapping("/{orderId}")
    @ResponseStatus(HttpStatus.NO_CONTENT)  // 204 No Content — no response body
    public void cancelOrder(@PathVariable Long orderId) {
        // orderService.cancel(orderId)
    }
}

// Record DTO — clean, immutable, no boilerplate
record OrderDto(Long id, String status) {}

// --- Global Exception Handler ---
// @RestControllerAdvice = @ControllerAdvice + @ResponseBody
// Applies to all @Controller and @RestController classes in the application.
// This is the right place for error handling — not try-catch in every controller.
@RestControllerAdvice
class GlobalExceptionHandler {

    // @ExceptionHandler intercepts this exception type thrown anywhere in any controller.
    // Spring matches the most specific handler — IllegalArgumentException before RuntimeException.
    @ExceptionHandler(IllegalArgumentException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public Map<String, String> handleBadRequest(IllegalArgumentException ex) {
        return Map.of(
            "error", "Bad Request",
            "message", ex.getMessage()
        );
    }

    // Catch-all for unhandled exceptions — always have this to prevent stack traces reaching clients
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public Map<String, String> handleGenericError(Exception ex) {
        // Log ex here — do not return stack trace to client
        return Map.of("error", "Internal Server Error");
    }
}

package io.thecodeforge.annotations.data;

import jakarta.persistence.*;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.repository.query.Param;
import org.springframework.stereotype.Repository;
import org.springframework.transaction.annotation.Transactional;

import java.math.BigDecimal;
import java.time.LocalDateTime;
import java.util.List;
import java.util.Optional;

/**
 * io.thecodeforge: JPA entity with relationship modeling.
 * Every annotation here maps to a specific SQL behavior — comments explain what.
 */
@Entity
@Table(name = "orders",
       indexes = @Index(name = "idx_orders_customer_id", columnList = "customer_id"),
       uniqueConstraints = @UniqueConstraint(columnNames = {"reference_number"}))
public class Order {

    // IDENTITY: database auto-increments; never set this field manually.
    // Use SEQUENCE for PostgreSQL high-throughput scenarios — IDENTITY locks the row on insert.
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    // Explicit column mapping: non-null, max length enforced at JPA layer.
    // JPA enforcement catches violations before a database round trip.
    @Column(name = "reference_number", nullable = false, length = 50, unique = true)
    private String referenceNumber;

    @Column(name = "customer_id", nullable = false)
    private Long customerId;

    // Precision and scale are critical for monetary values.
    // Without them, JPA defaults vary by database — never leave money columns to defaults.
    @Column(name = "total_amount", nullable = false, precision = 19, scale = 4)
    private BigDecimal totalAmount;

    @Enumerated(EnumType.STRING)  // Store 'PENDING' not '0' — readable in DB, survives enum reordering
    @Column(name = "status", nullable = false)
    private OrderStatus status;

    @Column(name = "created_at", nullable = false, updatable = false)
    private LocalDateTime createdAt;

    // @OneToMany with mappedBy: this side does not own the relationship.
    // The OrderItem side owns it via @ManyToOne @JoinColumn.
    // Without mappedBy, JPA creates a separate join table — not what you want.
    // CascadeType.ALL: persist/remove items when order is persisted/removed.
    // orphanRemoval: delete items from DB when removed from this collection.
    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<OrderItem> items;

    @PrePersist  // Lifecycle callback: runs before first save, not on updates
    protected void onCreate() {
        this.createdAt = LocalDateTime.now();
    }

    // Constructors, getters, setters omitted for brevity
    public Long getId() { return id; }
    public String getReferenceNumber() { return referenceNumber; }
    public OrderStatus getStatus() { return status; }
    public void setStatus(OrderStatus status) { this.status = status; }
}

@Entity
@Table(name = "order_items")
class OrderItem {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    // @ManyToOne is the owning side — this entity's table has the FK column.
    // @JoinColumn(name = "order_id") names the foreign key column explicitly.
    @ManyToOne(fetch = FetchType.LAZY)  // LAZY: do not load Order unless accessed
    @JoinColumn(name = "order_id", nullable = false)
    private Order order;

    @Column(name = "product_id", nullable = false)
    private Long productId;

    @Column(name = "quantity", nullable = false)
    private int quantity;

    public Order getOrder() { return order; }
    public void setOrder(Order order) { this.order = order; }
}

enum OrderStatus { PENDING, CONFIRMED, SHIPPED, CANCELLED }

// --- Spring Data JPA Repository ---
@Repository
public interface OrderRepository extends JpaRepository<Order, Long> {

    // Derived query: Spring generates the SQL from the method name.
    // Readable for simple cases — use @Query when the method name becomes a sentence.
    List<Order> findByCustomerIdAndStatus(Long customerId, OrderStatus status);

    // @Query with JPQL: use entity names and field names, not table/column names.
    // This is more readable than a 60-character method name.
    @Query("SELECT o FROM Order o WHERE o.customerId = :customerId "
         + "AND o.totalAmount >= :minAmount "
         + "AND o.createdAt >= :since "
         + "ORDER BY o.createdAt DESC")
    List<Order> findHighValueOrdersSince(
            @Param("customerId") Long customerId,
            @Param("minAmount") BigDecimal minAmount,
            @Param("since") LocalDateTime since);

    // @Modifying + @Transactional: required for UPDATE and DELETE queries.
    // Without @Modifying, Spring throws an exception.
    // Without @Transactional, the update executes but may not commit.
    // clearAutomatically=true: clears the persistence context after execution
    // to prevent stale cached entities being returned in the same transaction.
    @Modifying(clearAutomatically = true)
    @Transactional
    @Query("UPDATE Order o SET o.status = :status WHERE o.id = :id")
    int updateStatus(@Param("id") Long id, @Param("status") OrderStatus status);

    // Native SQL query: use when JPQL cannot express the query (window functions,
    // database-specific functions, complex subqueries).
    // nativeQuery=true: Spring passes the SQL directly to the database.
    @Query(value = "SELECT * FROM orders WHERE EXTRACT(MONTH FROM created_at) = :month",
           nativeQuery = true)
    List<Order> findOrdersForMonth(@Param("month") int month);

    Optional<Order> findByReferenceNumber(String referenceNumber);
}

package io.thecodeforge.annotations.data;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Isolation;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

import java.math.BigDecimal;

/**
 * io.thecodeforge: @Transactional propagation and isolation reference.
 * This single class demonstrates every propagation scenario that matters in production.
 */
@Service
public class PaymentService {

    private final AuditService auditService;

    public PaymentService(AuditService auditService) {
        this.auditService = auditService;
    }

    /**
     * REQUIRED (default): joins existing transaction or starts a new one.
     * This is correct for most service methods.
     *
     * rollbackFor = Exception.class: rolls back on ALL exceptions,
     * not just RuntimeException. Use this when your method can throw
     * checked exceptions that should also trigger rollback.
     */
    @Transactional(rollbackFor = Exception.class)
    public void processPayment(Long orderId, BigDecimal amount) throws Exception {
        // 1. Debit account
        // 2. Update order status
        // 3. Send to payment gateway

        // auditService.logPayment() runs in its OWN transaction (REQUIRES_NEW).
        // If processPayment() rolls back, the audit log is NOT rolled back.
        // This is intentional — you always want an audit trail, even for failures.
        auditService.logPayment(orderId, amount, "INITIATED");

        // Simulate a failure after audit has been written
        if (amount.compareTo(BigDecimal.ZERO) <= 0) {
            throw new IllegalArgumentException("Amount must be positive");
            // Transaction rolls back. auditService.logPayment() does NOT roll back
            // because it ran in REQUIRES_NEW — its transaction already committed.
        }
    }

    /**
     * REQUIRES_NEW: always starts a fresh transaction.
     * Suspends any calling transaction.
     * Use for: audit logging, retry-safe operations, independent operations
     * that should not roll back with the caller.
     *
     * WARNING: REQUIRES_NEW acquires a new connection from the pool.
     * Nested REQUIRES_NEW calls under heavy load can exhaust the connection pool.
     */
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void processPaymentIndependently(Long orderId, BigDecimal amount) {
        // Commits independently — caller's rollback does not affect this.
    }

    /**
     * READ_COMMITTED isolation: prevents dirty reads (seeing uncommitted data
     * from other transactions). Allows non-repeatable reads — the same query
     * run twice in the same transaction can return different results.
     *
     * Use READ_COMMITTED for most read operations where perfect consistency
     * is not required and throughput matters.
     */
    @Transactional(readOnly = true, isolation = Isolation.READ_COMMITTED)
    public BigDecimal getAccountBalance(Long accountId) {
        // readOnly=true: hint to JPA to skip dirty checking on entities
        // — meaningful performance improvement in read-heavy paths.
        // Does NOT prevent writes at the JDBC level — use for read-only methods.
        return BigDecimal.ZERO; // In real code: accountRepository.findBalance(accountId)
    }

    /**
     * NEVER: throws an exception if there IS an active transaction.
     * MANDATORY: throws an exception if there is NO active transaction.
     * SUPPORTS: joins existing transaction if present, runs non-transactionally if not.
     * NOT_SUPPORTED: always runs non-transactionally, suspends existing transaction.
     *
     * These four are rare — document why you are using them when you do.
     */
    @Transactional(propagation = Propagation.MANDATORY)
    public void mustRunInTransaction(Long orderId) {
        // Throws IllegalTransactionStateException if called without an active transaction.
        // Use when a method only makes sense inside a transaction boundary.
    }
}

@Service
class AuditService {

    /**
     * REQUIRES_NEW: this method always runs in its own independent transaction.
     * Even if the calling transaction (processPayment) rolls back,
     * this audit log entry is committed.
     */
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void logPayment(Long orderId, BigDecimal amount, String status) {
        // Persists audit record in its own committed transaction
    }
}

package io.thecodeforge.annotations.async;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.annotation.Async;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
import org.springframework.stereotype.Service;

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.Executor;

/**
 * io.thecodeforge: @Async configuration and usage reference.
 *
 * @EnableAsync is required — without it, @Async is silently ignored.
 * Never forget this annotation. Never.
 */
@Configuration
@EnableAsync
public class AsyncConfig {

    /**
     * Custom thread pool executor.
     * The default SimpleAsyncTaskExecutor creates a new thread per task — not acceptable
     * in production. It will exhaust OS thread limits under any meaningful load.
     *
     * This executor is bounded: max 20 threads, queue depth 500.
     * Tune these values based on your expected concurrent async task volume.
     *
     * Name the bean 'taskExecutor' to make it the default for all @Async calls,
     * or name it something descriptive and reference it in @Async("notificationExecutor").
     */
    @Bean(name = "notificationExecutor")
    public Executor notificationExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(5);
        executor.setMaxPoolSize(20);
        executor.setQueueCapacity(500);
        executor.setThreadNamePrefix("notification-");
        // RejectedExecutionHandler: what happens when queue is full and pool is at max
        // CallerRunsPolicy: run on the calling thread (back pressure)
        // AbortPolicy: throw RejectedExecutionException (default)
        executor.setRejectedExecutionHandler(new java.util.concurrent.ThreadPoolExecutor.CallerRunsPolicy());
        executor.initialize();
        return executor;
    }
}

@Service
public class NotificationService {

    /**
     * void return: fire-and-forget. Caller does not wait.
     * Exceptions thrown in this method are lost unless you configure
     * AsyncUncaughtExceptionHandler — configure one, always.
     *
     * "notificationExecutor" specifies which executor to use.
     * Without the name, Spring uses the default executor (SimpleAsyncTaskExecutor).
     */
    @Async("notificationExecutor")
    public void sendWelcomeEmail(String email) {
        // Runs on a thread from notificationExecutor pool
        // Caller returns immediately after the proxy submits this to the pool
        System.out.println("Sending welcome email to " + email
            + " on thread: " + Thread.currentThread().getName());
    }

    /**
     * CompletableFuture return: async with result.
     * Caller can chain .thenApply(), .thenAccept(), or .join() to get the result.
     * CompletableFuture.completedFuture() wraps the result for the proxy to return.
     */
    @Async("notificationExecutor")
    public CompletableFuture<String> generateReport(Long userId) {
        // Long-running report generation on background thread
        String report = "Report for user " + userId;
        return CompletableFuture.completedFuture(report);
    }

    // WRONG: calling sendWelcomeEmail from within the same class.
    // The call goes to 'this', not the proxy — @Async is bypassed.
    // sendWelcomeEmail() runs synchronously on the calling thread.
    public void registerUser(String email) {
        this.sendWelcomeEmail(email); // @Async bypassed — runs synchronously
    }
}

package io.thecodeforge.annotations.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.condition.*;
import org.springframework.context.annotation.*;

/**
 * io.thecodeforge: Configuration annotation reference.
 *
 * CGLIB proxy note: @Configuration classes are proxied by Spring.
 * Calling one @Bean method from another returns the existing singleton.
 * Using @Component instead of @Configuration breaks this — do not do it.
 */
@Configuration
public class CloudConfig {

    /**
     * @Profile: only creates this bean when spring.profiles.active=prod.
     * Use for environment-level switching of entire subsystem implementations.
     */
    @Bean
    @Profile("prod")
    public StorageService s3Storage() {
        return new S3StorageService();
    }

    /**
     * @Profile with multiple values: creates bean in dev OR test environments.
     * Useful for test doubles that should be available in both.
     */
    @Bean
    @Profile({"dev", "test"})
    public StorageService localStorageForDevAndTest() {
        return new LocalStorageService();
    }

    /**
     * @ConditionalOnProperty: creates bean when forge.mock.enabled=true.
     * matchIfMissing=false: if the property is absent, the bean is NOT created.
     * matchIfMissing=true: if the property is absent, the bean IS created (opt-out pattern).
     */
    @Bean
    @ConditionalOnProperty(
        name = "forge.cache.enabled",
        havingValue = "true",
        matchIfMissing = false
    )
    public CacheService redisCache() {
        return new RedisCacheService();
    }

    /**
     * @ConditionalOnMissingBean: creates this bean ONLY if no other CacheService
     * bean has been defined. This is the default/fallback pattern.
     * Spring Boot's auto-configuration uses this extensively.
     */
    @Bean
    @ConditionalOnMissingBean(CacheService.class)
    public CacheService noOpCache() {
        return new NoOpCacheService();
    }

    /**
     * @ConditionalOnClass: creates this bean only when a specific class is
     * on the classpath. Use for optional integrations.
     * If the class is present, the dependency is available — configure accordingly.
     */
    @Bean
    @ConditionalOnClass(name = "io.lettuce.core.RedisClient")
    public StorageService lettuceBackedStorage() {
        return new LocalStorageService(); // Would be Lettuce-based in real code
    }

    /**
     * @Value in @Bean methods: inject as a parameter, not a field.
     * Field @Value injection happens after @Bean methods run — the field is null
     * when the @Bean method executes. This is the correct pattern.
     */
    @Bean
    public StorageService configuredStorage(
            @Value("${storage.bucket:default-bucket}") String bucket,
            @Value("${storage.region:us-east-1}") String region) {
        // bucket and region are correctly injected as method parameters
        return new S3StorageService(bucket, region);
    }
}

interface StorageService {}
interface CacheService {}

class S3StorageService implements StorageService {
    private final String bucket;
    private final String region;
    S3StorageService() { this.bucket = "default"; this.region = "us-east-1"; }
    S3StorageService(String bucket, String region) { this.bucket = bucket; this.region = region; }
}
class LocalStorageService implements StorageService {}
class RedisCacheService implements CacheService {}
class NoOpCacheService implements CacheService {}