Home › Spring Boot (Java) › Spring Boot 4 CLAUDE.md

Spring Boot 4 CLAUDE.md

CLAUDE.md for Spring Boot 4 (Spring Framework 7) services on Java 25: null-safety, HTTP clients, testing, and migrations.

Claude Code (CLAUDE.md)Spring Boot (Java)

Copy CLAUDE.md

How to use

Save this as CLAUDE.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# CLAUDE.md: Spring Boot 4 service

## Commands
`./mvnw verify` (or `./gradlew check`) · run: `./mvnw spring-boot:run` · single test: `./mvnw test -Dtest=OrderServiceTest`
- Check `pom.xml`/`build.gradle.kts` for the exact Boot version; if it's still 3.x, follow 3.x APIs.

## Code rules
- Java 25, constructor injection, `record` DTOs, package-by-feature.
- Null-safety: packages annotated with JSpecify `@NullMarked`; mark optional values `@Nullable`. Don't return `null` collections.
- Outbound HTTP via `RestClient` or declarative HTTP service interfaces (`@HttpExchange`, `@GetExchange`) registered as clients; set timeouts.
- JSON is Jackson 3 in Boot 4 (`tools.jackson.*` packages); don't mix in Jackson 2 imports in new code.
- Validation with `@Valid` + Jakarta constraints; errors as `ProblemDetail` from `@RestControllerAdvice`.
- `@Transactional` on service methods only; read-only where possible. Avoid N+1 with fetch joins/entity graphs.
- Flyway migrations for every schema change; never `ddl-auto=update`.
- Config via `@ConfigurationProperties` records with validation.
- Observability: Micrometer + `spring-boot-starter-actuator`; expose only `health`/`info`/`prometheus` publicly.

## Testing
- Slices: `@WebMvcTest` with `MockMvcTester`, `@DataJpaTest` + Testcontainers (`@ServiceConnection`). Use `@MockitoBean` (not the removed `@MockBean`).
- Integration: a few `@SpringBootTest` tests for critical paths.

## Don't
Don't add Lombok to a project that doesn't use it, or catch-and-ignore exceptions.