Spring Boot Cheat Sheet

The main class

package com.example.shop;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class ShopApplication {

    public static void main(String[] args) {
        SpringApplication.run(ShopApplication.class, args);
    }

}

Build and run it

./mvnw package
java -jar target/shop-1.0.0.jar

From the command line

curl -s https://start.spring.io/starter.zip -d type=maven-project -d javaVersion=25 -d dependencies=web,actuator,data-jpa,validation -d artifactId=shop -o shop.zip && unzip -Z1 shop.zip | sort

Modular starters, each with a test companion

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.1.1</version>
</parent>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webmvc</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webmvc-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

Renamed starters

build.gradle.kts

plugins {
    java
    id("org.springframework.boot") version "4.1.1"
    id("io.spring.dependency-management") version "1.1.7"
}

java {
    toolchain { languageVersion = JavaLanguageVersion.of(25) }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-webmvc")
    implementation("org.springframework.boot:spring-boot-starter-actuator")
    testImplementation("org.springframework.boot:spring-boot-starter-webmvc-test")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

Maven and Gradle side by side

application.properties and its YAML twin

spring.application.name=shop
server.port=8080
spring.datasource.url=jdbc:postgresql://localhost:5432/shop
spring.jpa.open-in-view=false
shop.currency=EUR
shop.countries=RO,DE,FR

Precedence, highest first

One property, four spellings

An environment variable that fails validation

SHOP_MAX_ITEMS=200 java -jar target/shop-1.0.0.jar

How Boot parses 30s and 10MB

import org.springframework.boot.convert.DurationStyle;
import org.springframework.util.unit.DataSize;
System.out.println(DurationStyle.detectAndParse("30s"));
System.out.println(DurationStyle.detectAndParse("PT1H30M"));
System.out.println(DurationStyle.detectAndParse("PT0.5S"));
System.out.println(DurationStyle.detectAndParse("250"));
System.out.println(DataSize.parse("10MB").toBytes());
System.out.println(DataSize.parse("512KB").toBytes());

A UTF-8 é in application.properties

import java.nio.file.Files;
import java.nio.charset.StandardCharsets;
import org.springframework.boot.env.PropertiesPropertySourceLoader;
import org.springframework.core.io.FileSystemResource;

var file = Files.createTempFile("app", ".properties");
Files.writeString(file, "shop.note=café\nshop.escaped=caf\\u00e9\n", StandardCharsets.UTF_8);
var source = new PropertiesPropertySourceLoader().load("app", new FileSystemResource(file)).get(0);
for (String key : new String[] {"shop.note", "shop.escaped"}) {
    String value = (String) source.getProperty(key);
    System.out.println(key + ": " + value.length() + " chars " + value.chars().mapToObj(Integer::toHexString).toList());
}

Unquoted values YAML 1.1 rewrites

import org.springframework.boot.env.YamlPropertySourceLoader;
import org.springframework.core.io.ByteArrayResource;
import org.springframework.core.env.EnumerablePropertySource;

var yaml = """
    shop:
      file-mode: 0755
      opens-at: 8:30
      gift-wrap: on
      country: NO
      quoted-mode: "0755"
    """;
var source = (EnumerablePropertySource<?>) new YamlPropertySourceLoader().load("demo", new ByteArrayResource(yaml.getBytes())).get(0);
for (String name : source.getPropertyNames()) System.out.println(name + " = " + source.getProperty(name));

A record bound to shop.*

@Validated
@ConfigurationProperties("shop")
public record ShopProperties(
        @NotBlank String currency,
        @Min(1) @Max(100) int maxItems,
        @DefaultValue("50") BigDecimal freeShippingOver,
        @DefaultValue("30s") Duration paymentTimeout,
        List<String> countries) {
}

What the record receives

shop.currency=EUR
shop.max-items=10
shop.countries=RO,DE,FR

Pick the right one

Three ways to switch

java -jar target/shop-1.0.0.jar --spring.profiles.active=prod
SPRING_PROFILES_ACTIVE=prod java -jar target/shop-1.0.0.jar
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

Beans for one profile

@Component
@Profile("demo")
public class DemoRunner implements ApplicationRunner {

    @Override
    public void run(ApplicationArguments args) {
        System.out.println("only in the demo profile");
    }

}

One file, several profiles

spring.profiles.group.prod=postgres,json-logs
logging.level.root=info
#---
spring.config.activate.on-profile=json-logs
logging.structured.format.console=ecs
#---
spring.config.activate.on-profile=dev
logging.level.com.example=debug

Component scanning and constructor injection

@Service
public class OrderService {

    private final OrderRepository orders;
    private final ShopProperties shop;

    public OrderService(OrderRepository orders, ShopProperties shop) {
        this.orders = orders;
        this.shop = shop;
    }

}

@Bean methods for classes you do not own

@Configuration
public class ClockConfig {

    @Bean
    Clock clock() {
        return Clock.systemUTC();
    }

}

Two beans of the same type

Scopes and lifecycle

Ask Boot why

java -jar target/shop-1.0.0.jar --debug

A positive match from the same report

Exclude an auto-configuration

spring.autoconfigure.exclude=org.springframework.boot.security.autoconfigure.UserDetailsServiceAutoConfiguration

An auto-configuration class and its registration

@AutoConfiguration
@ConditionalOnClass(AuditClient.class)
@EnableConfigurationProperties(AuditProperties.class)
public class AuditAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    AuditClient auditClient(AuditProperties properties) {
        return new AuditClient(properties.url());
    }

}

Read, list and create orders

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    private final OrderService service;

    public OrderController(OrderService service) {
        this.service = service;
    }

    @GetMapping
    public PagedModel<Order> list(@RequestParam(required = false) Order.Status status,
            @PageableDefault(size = 2, sort = "id") Pageable pageable) {
        return new PagedModel<>(service.list(status, pageable));
    }

    @GetMapping("/{id}")
    public Order get(@PathVariable long id) {
        return service.find(id);
    }

    @PostMapping
    public ResponseEntity<Order> create(@Valid @RequestBody NewOrder request) {
        Order order = service.create(request);
        return ResponseEntity.created(URI.create("/api/orders/" + order.getId())).body(order);
    }

}

GET one order

curl -s localhost:8080/api/orders/1

POST returns 201 and a Location header

curl -s -i -u admin:change-me -X POST localhost:8080/api/orders -H "Content-Type: application/json" -d '{"sku":"LAMP-01","qty":2}'

Where each annotation reads from

Constraints on a record

public record NewOrder(
        @NotBlank @Pattern(regexp = "[A-Z]+-\\d+") String sku,
        @Min(1) @Max(10) int qty) {
}

An invalid request

curl -s -u admin:change-me -X POST localhost:8080/api/orders -H "Content-Type: application/json" -d '{"sku":"lamp","qty":0}'

jakarta.validation.constraints

Turn them on for Spring MVC exceptions

spring.mvc.problemdetails.enabled=true

Map your exceptions with @RestControllerAdvice

@RestControllerAdvice
public class ApiErrors extends ResponseEntityExceptionHandler {

    @ExceptionHandler(OrderNotFoundException.class)
    ProblemDetail notFound(OrderNotFoundException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
        problem.setType(URI.create("https://example.com/problems/order-not-found"));
        problem.setTitle("Order not found");
        problem.setProperty("orderId", ex.getId());
        return problem;
    }

    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(MethodArgumentNotValidException ex,
            HttpHeaders headers, HttpStatusCode status, WebRequest request) {
        ProblemDetail problem = ex.getBody();
        Map<String, String> errors = ex.getBindingResult().getFieldErrors().stream()
                .collect(Collectors.toMap(e -> e.getField(), e -> e.getDefaultMessage(), (a, b) -> a + "; " + b));
        problem.setProperty("errors", errors);
        return handleExceptionInternal(ex, problem, headers, status, request);
    }

}

The response for a missing order

curl -s -i localhost:8080/api/orders/9

A body that is not valid JSON

curl -s -u admin:change-me -X POST localhost:8080/api/orders -H "Content-Type: application/json" -d '{"sku":"LAMP-01","qty":2'

Configure how the version is read

spring.mvc.apiversion.use.header=API-Version
spring.mvc.apiversion.default=1

Two versions of one endpoint

@GetMapping(path = "/{id}", version = "1")
public Order get(@PathVariable long id) {
    return service.find(id);
}

@GetMapping(path = "/{id}", version = "2")
public OrderView getV2(@PathVariable long id) {
    return OrderView.of(service.find(id));
}

Ask for version 2

curl -s -H "API-Version: 2" localhost:8080/api/orders/1

An unsupported version

curl -s -H "API-Version: 3" localhost:8080/api/orders/1

A fluent, synchronous client

import org.springframework.web.client.RestClient;
import org.springframework.web.client.HttpClientErrorException;
import java.util.Map;

var client = RestClient.builder().baseUrl("https://httpbingo.org").build();
Map<?, ?> body = client.get().uri("/get?shop={name}", "demo").retrieve().body(Map.class);
System.out.println(body.get("args"));

try {
    client.get().uri("/status/404").retrieve().toBodilessEntity();
} catch (HttpClientErrorException.NotFound e) {
    System.out.println(e.getStatusCode() + " " + e.getClass().getSimpleName());
}

Declare the API as an interface

@HttpExchange("/anything")
public interface EchoClient {

    @GetExchange
    Map<String, Object> echo(@RequestParam String q);

}

@Configuration
@ImportHttpServices(group = "echo", types = EchoClient.class)
public class ClientsConfig {
}

Point the group at a server and call it

spring.http.serviceclient.echo.base-url=https://httpbingo.org
spring.http.serviceclient.echo.read-timeout=5s

RestClient, WebClient, RestTemplate

An entity

@Entity
@Table(name = "orders")
public class Order {

    public enum Status { PENDING, PAID, SHIPPED }

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

    @Column(nullable = false)
    private String sku;

    private int qty;

    @Enumerated(EnumType.STRING)
    private Status status = Status.PENDING;

    private BigDecimal total;

    private Instant createdAt = Instant.now();

    protected Order() {
    }

}

A repository with derived and custom queries

public interface OrderRepository extends JpaRepository<Order, Long> {

    Page<Order> findByStatus(Order.Status status, Pageable pageable);

    long countByStatus(Order.Status status);

    @Query("select o from Order o where o.total >= :min order by o.total desc")
    List<Order> findLarge(BigDecimal min);

}

Paging and sorting from the URL

curl -s "localhost:8080/api/orders?status=PAID&page=0&size=5&sort=total,desc"

Method names Spring Data understands

application.properties for JPA

spring.jpa.open-in-view=false
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.show-sql=false
logging.level.org.hibernate.SQL=debug

On service methods

@Transactional(readOnly = true)
public Order find(long id) {
    return orders.findById(id).orElseThrow(() -> new OrderNotFoundException(id));
}

@Transactional
public Order create(NewOrder request) {
    return orders.save(new Order(request.sku(), request.qty(), priceFor(request)));
}

The classic traps

Add the starter and a first script

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-flyway</artifactId>
</dependency>
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-database-postgresql</artifactId>
</dependency>

src/main/resources/db/migration/V1__create_orders.sql

create table orders (
    id bigint generated by default as identity primary key,
    sku varchar(40) not null,
    qty int not null,
    status varchar(16) not null,
    total numeric(10, 2) not null,
    created_at timestamp with time zone not null
);

What keeps deployments safe

Public reads, admin writes

@Configuration
public class SecurityConfig {

    @Bean
    SecurityFilterChain api(HttpSecurity http) throws Exception {
        return http
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/actuator/health/**", "/actuator/info").permitAll()
                        .requestMatchers(HttpMethod.GET, "/api/**").permitAll()
                        .requestMatchers("/error").permitAll()
                        .anyRequest().hasRole("ADMIN"))
                .httpBasic(Customizer.withDefaults())
                .csrf(csrf -> csrf.disable())
                .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                .build();
    }

}

An anonymous write

curl -s -i -X POST localhost:8080/api/orders -H "Content-Type: application/json" -d '{"sku":"LAMP-01","qty":2}'

Development user from properties

spring.security.user.name=admin
spring.security.user.password=change-me
spring.security.user.roles=ADMIN

A JWT resource server

spring.security.oauth2.resourceserver.jwt.issuer-uri=https://login.example.com/realms/shop

Passwords

@Bean
PasswordEncoder passwordEncoder() {
    return PasswordEncoderFactories.createDelegatingPasswordEncoder();
}

Choose what is reachable over HTTP

management.endpoints.web.exposure.include=health,info,metrics
management.endpoint.health.show-details=when-authorized
management.info.env.enabled=true
management.info.java.enabled=true
management.info.os.enabled=true
info.app.version=@project.version@

Health for anonymous callers

curl -s localhost:8080/actuator/health

One component, with credentials

curl -s -u admin:change-me localhost:8080/actuator/health/db

Build and runtime info

curl -s localhost:8080/actuator/info

Request timings for one URI

curl -s -u admin:change-me "localhost:8080/actuator/metrics/http.server.requests?tag=uri:/api/orders/%7Bid%7D"

Endpoints worth knowing

Common settings

logging.level.root=info
logging.level.com.example.shop=debug
logging.level.org.hibernate.SQL=debug
logging.file.name=logs/shop.log
logging.group.persistence=org.hibernate,com.zaxxer.hikari
logging.level.persistence=warn

JSON logs in Elastic Common Schema

java -jar target/shop-1.0.0.jar --logging.structured.format.console=ecs

Export traces and metrics over OTLP

management.tracing.sampling.probability=0.1
management.opentelemetry.tracing.export.otlp.endpoint=http://otel-collector:4318/v1/traces

What gets instrumented

Load only what a test needs

A controller test with MockMvcTester and @MockitoBean

@WebMvcTest(OrderController.class)
@Import(SecurityConfig.class)
class OrderControllerTest {

    @Autowired
    MockMvcTester mvc;

    @MockitoBean
    OrderService service;

    @Test
    void returnsOrder() {
        given(service.find(1)).willReturn(new Order("LAMP-01", 1, new BigDecimal("39.50")));
        assertThat(mvc.get().uri("/api/orders/1"))
                .hasStatusOk()
                .bodyJson().extractingPath("$.sku").isEqualTo("LAMP-01");
    }

    @Test
    void missingOrderIsProblemJson() {
        given(service.find(9)).willThrow(new OrderNotFoundException(9));
        assertThat(mvc.get().uri("/api/orders/9"))
                .hasStatus(HttpStatus.NOT_FOUND)
                .bodyJson().extractingPath("$.title").isEqualTo("Order not found");
    }

}

A full HTTP test with RestTestClient

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@AutoConfigureRestTestClient
class ShopApplicationTests {

    @Autowired
    RestTestClient client;

    @Test
    void ordersEndpointWorksOverHttp() {
        client.get().uri("/api/orders/1").header("API-Version", "2")
                .exchange()
                .expectStatus().isOk()
                .expectBody().jsonPath("$.total.currency").isEqualTo("EUR");
    }

}

Run the suite

./mvnw test

A real database with @ServiceConnection

@TestConfiguration(proxyBeanMethods = false)
class TestcontainersConfig {

    @Bean
    @ServiceConnection
    PostgreSQLContainer postgres() {
        return new PostgreSQLContainer("postgres:18");
    }

}

Run a method on a schedule

@Configuration
@EnableScheduling
class SchedulingConfig {
}

@Component
class ReportJob {

    @Scheduled(cron = "0 0 9 * * MON-FRI", zone = "Europe/Bucharest")
    void dailyReport() {
    }

    @Scheduled(fixedDelayString = "${shop.sync-interval:5m}")
    void syncStock() {
    }

}

Spring cron has six fields

import org.springframework.scheduling.support.CronExpression;
import java.time.LocalDateTime;

var cron = CronExpression.parse("0 0 9 * * MON-FRI");
var t = LocalDateTime.of(2026, 10, 16, 10, 0);
for (int i = 0; i < 3; i++) {
    t = cron.next(t);
    System.out.println(t + " " + t.getDayOfWeek());
}
System.out.println(CronExpression.parse("@hourly").next(LocalDateTime.of(2026, 10, 16, 10, 20)));

@Retryable with backoff

@SpringBootApplication
@EnableResilientMethods
public class ShopApplication {
}

@Component
public class InventoryClient {

    @Retryable(includes = IllegalStateException.class, maxRetries = 3, delay = 100, multiplier = 2)
    public int stockFor(String sku) {
        return callInventoryService(sku);
    }

}

Two failures, then success

java -jar target/shop-1.0.0.jar --spring.profiles.active=demo

Limit concurrent calls

@ConcurrencyLimit(10)
public Report render(long id) {
    return renderer.render(id);
}

Turn them on

spring.threads.virtual.enabled=true

What to watch

Build it and look inside

./mvnw -q package -Dmaven.test.skip=true
ls -l --block-size=M target/shop-1.0.0.jar

The tools jar mode

java -Djarmode=tools -jar target/shop-1.0.0.jar help

Layers for container images

java -Djarmode=tools -jar target/shop-1.0.0.jar list-layers

Multi-stage build with extracted layers

FROM eclipse-temurin:25-jre AS builder
WORKDIR /builder
COPY target/*.jar application.jar
RUN java -Djarmode=tools -jar application.jar extract --layers --destination extracted

FROM eclipse-temurin:25-jre
WORKDIR /application
COPY --from=builder /builder/extracted/dependencies/ ./
COPY --from=builder /builder/extracted/spring-boot-loader/ ./
COPY --from=builder /builder/extracted/snapshot-dependencies/ ./
COPY --from=builder /builder/extracted/application/ ./
ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75", "-jar", "application.jar"]

No Dockerfile at all

./mvnw spring-boot:build-image -Dspring-boot.build-image.imageName=shop:1.0.0

Build a native executable

./mvnw -Pnative native:compile
./target/shop

JVM or native

The changes most applications hit

Let Boot report renamed properties

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-properties-migrator</artifactId>
    <scope>runtime</scope>
</dependency>

Jackson 2 as a stop-gap

spring.jackson.use-jackson2-defaults=true

Port already in use

java -jar target/shop-1.0.0.jar

Messages and fixes

401 for a URL that does not exist

curl -s localhost:8080/nope

A primary key conflict after seeding data.sql

More symptoms

Generations and open-source support

Managed versions in the shop app