Java & Spring Boot Patterns

Your Spring Boot service compiles, but the AI scaffolded field injection, a leaky @Transactional boundary, and no @ControllerAdvice — and it falls over the first time two requests race on the same order. Generated Java looks idiomatic until production traffic finds the seams: N+1 queries, swallowed exceptions, a KafkaTemplate call that no longer compiles on Spring Boot 3. These recipes produce Spring Boot 3.x code on Java 21 that holds up, and — just as important — show you how to catch the failure modes the model still gets wrong.

What You Will Walk Away With

• A paste-ready prompt for a REST resource with validation, pagination, and a single global exception handler
• A JPA prompt that uses Hibernate 6.4’s managed soft-delete instead of the legacy @Where pattern
• A resilient downstream-client prompt (Resilience4j circuit breaker + the current CompletableFuture Kafka API)
• A Spring Security 6 prompt for stateless JWT auth that survives review
• A testing prompt that produces Testcontainers integration tests, not happy-path mocks
• The Spring-specific gotchas to check on every generation, plus the MCP servers that tighten the loop

Note

Most prompts below are tool-agnostic — paste them identically into Cursor agent mode, Claude Code (claude "<prompt>"), or Codex (codex "<prompt>", the IDE extension, or a Cloud task on a worktree). Only project scaffolding differs meaningfully per tool, so that one step uses tabs.

The Workflow

Step 1: Scaffold the project (this part differs per tool)

Spring Initializr is the source of truth for the dependency tree, so the useful move is having the agent call it and then wire your conventions on top.

Cursor

In agent mode, point Cursor at a fresh directory:

Generate a Spring Boot 3.4 project on Java 21 using start.spring.io with
dependencies: web, data-jpa, validation, security, actuator, postgresql,
flyway. Maven build. Then add a CLAUDE.md-style conventions file documenting
the rules below and apply them to the generated code.

Cursor scaffolds in the workspace, shows a diff, and you accept per file. Keep the conventions in a .cursor/rules/ file so every later edit inherits them.

Claude Code

claude "Create a Spring Boot 3.4 project on Java 21 via start.spring.io with
web, data-jpa, validation, security, actuator, postgresql, and flyway. Maven.
Write a CLAUDE.md capturing our conventions, then make the generated code follow it."

Claude Code runs the curl against start.spring.io, unzips, and edits in place. The CLAUDE.md it writes is reused automatically on every subsequent run in the repo.

Codex

codex "Scaffold a Spring Boot 3.4 / Java 21 Maven project from start.spring.io
(web, data-jpa, validation, security, actuator, postgresql, flyway). Add an
AGENTS.md with our conventions and apply them."

For larger refactors, kick this off as a Codex Cloud task on a worktree so the scaffold and your existing branch do not collide. Codex reads AGENTS.md on each task.

Whichever tool you use, give it these conventions up front — they prevent the most common review-blocking output:

- Java 21: records for DTOs, pattern matching, virtual threads where I/O-bound
- Constructor injection only (never @Autowired field injection)
- One @ControllerAdvice for the whole app; never catch-and-swallow
- @Transactional only on service methods, readOnly=true by default
- No business logic in controllers; no entities returned from controllers (DTOs only)
- Every new endpoint ships with a Testcontainers integration test

Step 2: Generate a REST resource

Now the part that is identical across all three tools. The trick is to specify the response envelope and the failure behavior, not just “CRUD” — otherwise you get a happy-path controller that leaks entities and returns stack traces.

Tip

Create a REST resource for Product at /api/v1/products in our Spring Boot 3.4 app. (1) Product JPA entity (id, name, slug unique, description, price BigDecimal, stock int, version for optimistic locking) and a ProductResponse record DTO — never return the entity from the controller. (2) Controller endpoints: GET / (paginated via Pageable, default size 20, plus optional ?search= filtering name and description), GET /{id}, POST / (returns 201 with Location header), PUT /{id}, DELETE /{id} (returns 204). (3) CreateProductRequest / UpdateProductRequest records with Jakarta Validation (@NotBlank name 2-200, @Positive price, @PositiveOrZero stock). (4) A single @RestControllerAdvice that maps MethodArgumentNotValidException to 422 with field-level errors [{field, message}], EntityNotFoundException to 404, DataIntegrityViolationException (duplicate slug) to 409, and everything else to 500 with a generic body in prod and full detail in dev. (5) Service layer with constructor injection, @Transactional(readOnly = true) on reads and @Transactional on writes. Write a Testcontainers integration test (@SpringBootTest + @Testcontainers with postgres:16) covering create, the 422 validation case, and the 409 duplicate case.

Then read what comes back against the conventions. The high-value check is the exception handler: models love to scatter try/catch blocks that log and return null. You want exactly one advice class and zero swallowed exceptions. A correct controller stays this thin:

@RestController
@RequestMapping("/api/v1/products")
class ProductController {
    private final ProductService products;

    ProductController(ProductService products) { // constructor injection, no @Autowired
        this.products = products;
    }

    @GetMapping
    Page<ProductResponse> list(@PageableDefault(size = 20) Pageable pageable,
                               @RequestParam(required = false) String search) {
        return products.search(search, pageable); // validation + mapping live in the service
    }
}

If the generated controller is fatter than this — mapping logic, try/catch, an injected EntityManager — send it back: “Move all mapping and error handling out of the controller; rely on the @RestControllerAdvice.”

Step 3: Persistence without the legacy soft-delete trap

Ask for soft delete and most models still emit Hibernate 5’s @SQLDelete + @Where pair. @Where is deprecated in Hibernate 6 (replaced by @SQLRestriction), and Spring Boot 3.2+ ships Hibernate 6.4, which has a fully managed @SoftDelete annotation. Name the version so you get the modern path.

Tip

Add soft delete to the Order entity using Hibernate 6.4’s managed @SoftDelete annotation (we are on Spring Boot 3.4, Hibernate 6.6). Do not use @SQLDelete/@Where — those are the legacy pattern. The entity should map a OneToMany to OrderItem (cascade ALL, orphanRemoval), a ManyToOne to Customer (LAZY), an OrderStatus enum stored as STRING, and JPA auditing fields (@CreatedDate, @LastModifiedDate) via AuditingEntityListener. Add a JpaSpecificationExecutor-based repository with a search(criteria, pageable) default method, and confirm soft-deleted rows are excluded from queries automatically. Write a test proving a deleted order disappears from findAll() but the row still exists in the table.

The managed annotation collapses the old two-annotation dance to one line, and Hibernate filters soft-deleted rows everywhere automatically:

@Entity
@Table(name = "orders")
@SoftDelete // Hibernate 6.4+: replaces @SQLDelete + @Where, applied to every query
@EntityListeners(AuditingEntityListener.class)
class Order {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "customer_id", nullable = false)
    private Customer customer;
    // ... items, status, auditing fields
}

Caution

The single biggest production risk in AI-generated JPA is the N+1 query. A LAZY association iterated in a loop fires one query per row. After any entity work, ask the agent to “log the generated SQL and add a Testcontainers test asserting the list endpoint runs in a fixed number of queries,” then have it switch the hot path to a JOIN FETCH or an @EntityGraph. Do not trust a clean-looking entity until you have seen the SQL.

Note

Connect the Postgres MCP server so the agent reads your real schema and indexes instead of guessing: claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server-postgres "$DATABASE_URL" (same package via .mcp.json in Cursor and Codex; the package is archived upstream but still installs and runs). With it attached, “add an index for the product search” becomes the agent checking which columns the query actually filters and whether an index already exists — not a blind CREATE INDEX. Use a read-only connection string in development.

Step 4: Resilient downstream calls

A microservice that calls payment or inventory synchronously needs a circuit breaker, and any code touching Kafka must use the current API. On Spring Kafka 3.x (Spring Boot 3.x), KafkaTemplate.send() returns a CompletableFuture — the old ListenableFuture.addCallback(...) no longer exists and will not compile.

Tip

Implement a resilient PaymentServiceClient for our Spring Boot 3.4 service. (1) Use a Spring 6 RestClient (or WebClient if the call is reactive) with connect timeout 2s, read timeout 5s. (2) Wrap processPayment(PaymentRequest) with Resilience4j: @CircuitBreaker(name = "payment", fallbackMethod = "fallback"), @Retry(name = "payment") (3 attempts, exponential backoff, retry only on 5xx and connection errors — never on 4xx). The fallback returns a PENDING payment and logs at WARN. (3) Configure the circuit breaker in application.yml (sliding window 10, failure-rate threshold 50%, wait-duration-in-open-state 30s) and expose its state via Actuator health. (4) For the order-created Kafka publisher, use the current CompletableFuture API — kafkaTemplate.send(...).whenComplete(...), NOT the removed .addCallback(...). Add a test using Resilience4j’s test support that proves the circuit opens after the threshold and the fallback fires.

The Kafka publisher should look like this — whenComplete, not addCallback:

@Component
class OrderEventPublisher {
    private final KafkaTemplate<String, OrderEvent> kafkaTemplate;

    OrderEventPublisher(KafkaTemplate<String, OrderEvent> kafkaTemplate) {
        this.kafkaTemplate = kafkaTemplate;
    }

    @EventListener
    void onOrderCreated(OrderCreatedEvent event) {
        var kafkaEvent = OrderEvent.from(event);
        // Spring Kafka 3.x returns CompletableFuture; .addCallback was removed
        kafkaTemplate.send("order-events", kafkaEvent).whenComplete((result, ex) -> {
            if (ex == null) log.info("Event sent: {}", kafkaEvent.eventId());
            else log.error("Failed to send event {}", kafkaEvent.eventId(), ex);
        });
    }
}

Step 5: Stateless JWT security

Spring Security 6 dropped WebSecurityConfigurerAdapter and the old DSL. Pin the version so the agent produces the lambda DSL with a SecurityFilterChain bean rather than resurrecting the deprecated base class.

Tip

Configure Spring Security 6 (Spring Boot 3.4) for stateless JWT auth. Produce a SecurityFilterChain bean using the lambda DSL — do NOT extend WebSecurityConfigurerAdapter (removed in Spring Security 6). (1) Disable CSRF (stateless API), set SessionCreationPolicy.STATELESS. (2) Permit /api/auth/** and /actuator/health, require ROLE_ADMIN for /api/admin/**, authenticate everything else. (3) Add a OncePerRequestFilter that validates a Bearer JWT (signature + expiry), loads authorities from the roles claim, and sets the SecurityContext. (4) Use @EnableMethodSecurity so @PreAuthorize works on service methods. (5) Return 401 (unauthenticated) and 403 (forbidden) as JSON via a custom AuthenticationEntryPoint and AccessDeniedHandler, consistent with the @RestControllerAdvice error envelope. Write @WebMvcTest slices proving a missing token returns 401 and a non-admin hitting /api/admin/** returns 403.

Step 6: Tests that prove behavior, not coverage theater

The reason to insist on Testcontainers in the conventions is that mocked-repository tests pass while the real query is broken. A generation is not done until it ships an integration test that exercises a real database.

Tip

Add an integration test suite for the Product and Order features. Use @SpringBootTest(webEnvironment = RANDOM_PORT) with @Testcontainers and a singleton PostgreSQLContainer("postgres:16") shared across the suite (start it in a base class, not per test). Use MockMvc (or TestRestTemplate) for HTTP, and reset state between tests with a transactional rollback or a truncate. Cover: the happy path, the 422 validation case, the 409 duplicate-slug case, and — critically — a test that asserts the product list endpoint executes a bounded number of SQL statements (use Hibernate statistics) so an N+1 regression fails the build. Add the JaCoCo plugin with a 75% line-coverage gate, but make the N+1 assertion the test that actually matters.

When This Breaks

Caution

Spring-specific failure modes to check on every generation:

• Field injection sneaks back in. Models default to @Autowired private Foo foo;. It breaks constructor-based testing and hides required dependencies. Reject it — demand constructor injection.
• @Transactional on the wrong layer. Annotating a controller, a private method, or a self-invoked method silently does nothing (Spring’s proxy never sees the call). Keep it on public service methods only.
• The N+1 query. The most common performance bug in generated JPA. Always log SQL and assert query counts; fix with JOIN FETCH or @EntityGraph.
• Deprecated/removed APIs from stale training data. WebSecurityConfigurerAdapter (gone in Security 6), @Where (deprecated, use @SQLRestriction or @SoftDelete), and ListenableFuture.addCallback on KafkaTemplate (removed in Spring Kafka 3.x — use CompletableFuture.whenComplete). Pin “Spring Boot 3.4 / Java 21” in the prompt so the model targets current versions.
• @Async swallowing exceptions. A void @Async method that throws drops the exception on the floor. Return CompletableFuture or register an AsyncUncaughtExceptionHandler.
• Validation that never runs. @Valid is missing on the @RequestBody, so the constraints are decorative. Verify the controller parameter is annotated and a 422 test exists.

What’s Next

• Database patterns for deeper JPA, query tuning, and migration workflows
• API patterns for cross-language REST and error-envelope design
• ORM patterns for the N+1 and lazy-loading playbook across ORMs
• Kubernetes patterns for deploying these services to a cluster