Java Spring API

Iron Law

NO REACTIVE CODE WITHOUT READING reference/spring-boot-conventions.md FIRST — blocking calls inside reactive chains cause thread starvation

Java 21 + Spring Boot 3.5.x WebFlux REST API Skill

Conventions & Rules

For code conventions, package layout, and reactive rules, read reference/spring-boot-conventions.md

Quick Scaffold — New Spring Boot Project

# Using Spring Initializr via curl
curl https://start.spring.io/starter.zip \
  -d type=maven-project \
  -d language=java \
  -d javaVersion=21 \
  -d bootVersion=3.5.0 \
  -d dependencies=webflux,r2dbc,postgresql,flyway,validation,actuator,lombok \
  -d groupId=com.company \
  -d artifactId=my-service \
  -d name=my-service \
  -o my-service.zip && unzip my-service.zip -d my-service

Process

1. Scaffold using Spring Initializr or the command above
2. Configure pom.xml and application.yml — read reference/spring-boot-config.md
3. Create files using templates — read reference/spring-boot-templates.md for DTO, Entity, Repository, Service, Controller, and Test templates
4. Follow conventions below for package layout and reactive rules
5. Write tests with @SpringBootTest + WebTestClient
6. Format and check: mvn spotless:apply or IDE formatter

Key Patterns

Reference Files

Documentation Sources

Before generating code, consult these sources for current syntax and APIs:

Common Commands

mvn spring-boot:run                  # Run backend
mvn test                             # Run tests
mvn package                          # Build JAR
mvn spotless:apply                   # Format code
mvn clean test -Dspring.profiles.active=test  # Run tests with test profile
mvn dependency:tree                  # Show dependency tree

Error Handling

Validation errors: Use jakarta.validation annotations on DTO records. Handle via @ControllerAdvice returning ProblemDetail with HttpStatus.BAD_REQUEST (400).

Not-found errors: Use switchIfEmpty(Mono.error(new ResourceNotFoundException(...))) in services.

Duplicate errors: Catch DataIntegrityViolationException in services and convert to 409 Conflict.

Hard Prohibitions

• No block() calls in reactive chains — all operations must stay non-blocking
• No JPA in reactive stacks — use R2DBC exclusively
• Password reset rate limit: 3 attempts per email per hour maximum

Post-Code Review

After writing Java code, dispatch these reviewer agents:

• spring-reactive-reviewer — reactive correctness, blocking call detection, R2DBC patterns
• security-reviewer — auth, input validation, secrets management