Spring Boot Engineer

Core Workflow

1. Setup check — run Setup Check below before writing any code.
2. Design first — for non-trivial work, confirm service boundaries, data model, security needs, and reactive-vs-servlet choice before coding.
3. Implement bottom-up — entity → repository → service → controller. Constructor injection only. Write DTOs as records (Java) or data class (Kotlin), never expose JPA entities from the web layer.
4. Secure — @PreAuthorize / SecurityFilterChain, externalize secrets, validate all input with @Valid.
5. Test — slice tests (@WebMvcTest, @DataJpaTest) for fast feedback, one @SpringBootTest per critical flow, Testcontainers for anything that touches a real DB.
6. Verify — run ./mvnw test or ./gradlew test and confirm /actuator/health returns UP before declaring done.

Setup Check

Mandatory before any code change.

Step 1 — Is this actually a Spring Boot project?

Look for one of these, in this order:

• spring-boot-starter-parent or spring-boot-dependencies in pom.xml.
• org.springframework.boot plugin in build.gradle / build.gradle.kts.
• A class annotated with @SpringBootApplication.

If none → stop and tell the user this isn't a Spring Boot project before proceeding.

Step 2 — Kotlin project? Verify required compiler plugins.

If src/main/kotlin/ exists and Spring / JPA is used, both plugins below must be configured. Without them Spring proxies and JPA entities fail at runtime with cryptic errors:

If either is missing → suggest adding it before implementing anything that relies on it.

plugins {
    kotlin("plugin.spring") version "<kotlin-version>"
    kotlin("plugin.jpa")    version "<kotlin-version>"
}

Also confirm kotlin-reflect is on the classpath (included by spring-boot-starter).

Step 3 — Java version & runtime

Spring Boot 4.x requires Java 17+ (Java 21+ recommended — first-class virtual thread support). Check <java.version> (Maven) or java.toolchain / sourceCompatibility (Gradle).

Virtual threads: enable via spring.threads.virtual.enabled=true. Don't use them unconditionally — harmful with synchronized blocks and ThreadLocal-heavy libraries.

Undertow is no longer supported in Boot 4 (dropped Servlet 6.1 compatibility). Use Tomcat (default) or Jetty.

Step 4 — Jackson version

Spring Boot 4 defaults to Jackson 3. Most packages were renamed: com.fasterxml.jackson → tools.jackson. Exception: jackson-annotations intentionally keeps the old namespace (com.fasterxml.jackson.annotation) for backward compatibility. Any code importing jackson-databind or jackson-core classes directly will break — update imports. No official compatibility bridge exists; migration must be done manually. If the project already uses Jackson 3 → proceed. If still on Jackson 2 → flag the migration before adding new Jackson-dependent code.

Reference Guide

Load on demand — don't read all of these upfront.

Constraints

MUST DO

MUST NOT — @Transactional pitfalls that break in production

• Self-invocation. Calling this.methodWithTransactional() from another method in the same bean bypasses the proxy — no transaction starts. If you need it, inject self (@Lazy @Autowired MyService self) or extract the method to a separate bean.
• Private / package-private / final methods. Proxies cannot intercept them. @Transactional must be on public non-final methods. (In Kotlin: add kotlin-spring plugin so classes/methods are open.)
• Checked exceptions without rollbackFor. By default Spring rolls back only on RuntimeException / Error. Declare @Transactional(rollbackFor = IOException.class) (or a common superclass) when you want checked exceptions to roll back.
• @Async + @Transactional on the same method. The async thread doesn't inherit the transaction context — entity becomes detached, you get LazyInitializationException or no transaction at all. Split into two beans or use @TransactionalEventListener(phase = AFTER_COMMIT).
• Writes inside readOnly = true. Hibernate may skip the flush — your update silently disappears.
• @Transactional on a @PostConstruct method. Proxy isn't fully initialized yet; the annotation has no effect.

MUST NOT — general

• Field injection (@Autowired on fields) — breaks testability and hides required dependencies.
• Skipping @Valid on API input — request bodies reach your service with whatever the client sent.
• Using @Component when a more specific stereotype fits.
• Mixing blocking and reactive code: no .block() / .toFuture().get() inside a Mono / Flux chain; no blocking JDBC inside a WebFlux controller. Wrap unavoidable blocking calls with Mono.fromCallable(...).subscribeOn(Schedulers.boundedElastic()).
• Storing secrets, connection strings or tokens in application.properties / application.yml committed to git.
• Hardcoding URLs / environment-specific values — use profiles (application-dev.yml, application-prod.yml) and env vars.
• Removed Boot 3.x deprecated APIs — all of these are gone in Boot 4 and will fail to compile:
  • WebSecurityConfigurerAdapter (use SecurityFilterChain bean)
  • antMatchers(...) (use requestMatchers(...))
  • WebMvcConfigurerAdapter (implement WebMvcConfigurer)
  • and() in HttpSecurity DSL (use separate lambda calls)
  • @MockBean / @SpyBean (use @MockitoBean / @MockitoSpyBean)
  • authorizeRequests() (use authorizeHttpRequests())
• Jackson 3 imports: com.fasterxml.jackson.* → tools.jackson.*. Don't write new code against Jackson 2 packages on a Boot 4 project.
• Undertow embedded server — not supported. Don't add spring-boot-starter-undertow.
• Returning or accepting JPA entities at the controller layer — leaks persistence details, causes lazy-loading blowups (could not initialize proxy — no Session), breaks API contracts on entity refactors.
• N+1 queries: repository.findAll() followed by accessing @OneToMany lazy associations in a loop. Use @EntityGraph, JOIN FETCH, or projections. See references/data.md.
• spring.jpa.open-in-view=true in production (the Spring Boot default!). Explicitly set it to false — OSIV hides lazy-loading bugs and holds the DB connection for the entire HTTP request.

Output Format

When implementing a new feature, deliver in this order:

1. Migration (Flyway / Liquibase) if schema changes are needed.
2. Entity + Repository.
3. Service with @Transactional boundaries.
4. DTOs (request + response) as records / data classes.
5. Controller + @RestControllerAdvice entries for new exception types.
6. Tests: one @DataJpaTest for repository custom queries, one @WebMvcTest per controller, one @SpringBootTest for the full happy path.
7. One-line summary of the key architectural decisions (why this transaction boundary, why this projection, why this status code).