1---
2name: spring-boot-engineer
3description: Generates Spring Boot 3.x configurations, creates REST controllers, implements Spring Security 6 authentication flows, sets up Spring Data JPA repositories, and configures reactive WebFlux endpoints. Use when building Spring Boot 3.x applications, microservices, or reactive Java applications; invoke for Spring Data JPA, Spring Security 6, WebFlux, Spring Cloud integration, Java REST API design, or Microservices Java architecture.
4license: MIT
5metadata:
6  author: https://github.com/Jeffallan
7  version: "1.1.0"
8  domain: backend
9  triggers: Spring Boot, Spring Framework, Spring Cloud, Spring Security, Spring Data JPA, Spring WebFlux, Microservices Java, Java REST API, Reactive Java
10  role: specialist
11  scope: implementation
12  output-format: code
13  related-skills: java-architect, database-optimizer, microservices-architect, devops-engineer
14---
15 
16# Spring Boot Engineer
17 
18## Core Workflow
19 
201. **Analyze requirements** — Identify service boundaries, APIs, data models, security needs
212. **Design architecture** — Plan microservices, data access, cloud integration, security; confirm design before coding
223. **Implement** — Create services with constructor injection and layered architecture (see Quick Start below)
234. **Secure** — Add Spring Security, OAuth2, method security, CORS configuration; verify security rules compile and pass tests. If compilation or tests fail: review error output, fix the failing rule or configuration, and re-run before proceeding
245. **Test** — Write unit, integration, and slice tests; run `./mvnw test` (or `./gradlew test`) and confirm all pass before proceeding. If tests fail: review the stack trace, isolate the failing assertion or component, fix the issue, and re-run the full suite
256. **Deploy** — Configure health checks and observability via Actuator; validate `/actuator/health` returns `UP`. If health is `DOWN`: check the `components` detail in the response, resolve the failing component (e.g., datasource, broker), and re-validate
26 
27## Reference Guide
28 
29Load detailed guidance based on context:
30 
31| Topic | Reference | Load When |
32|-------|-----------|-----------|
33| Web Layer | `references/web.md` | Controllers, REST APIs, validation, exception handling |
34| Data Access | `references/data.md` | Spring Data JPA, repositories, transactions, projections |
35| Security | `references/security.md` | Spring Security 6, OAuth2, JWT, method security |
36| Cloud Native | `references/cloud.md` | Spring Cloud, Config, Discovery, Gateway, resilience |
37| Testing | `references/testing.md` | @SpringBootTest, MockMvc, Testcontainers, test slices |
38 
39## Quick Start — Minimal Working Structure
40 
41A standard Spring Boot feature consists of these layers. Use these as copy-paste starting points.
42 
43### Entity
44 
45```java
46@Entity
47@Table(name = "products")
48public class Product {
49    @Id
50    @GeneratedValue(strategy = GenerationType.IDENTITY)
51    private Long id;
52 
53    @NotBlank
54    private String name;
55 
56    @DecimalMin("0.0")
57    private BigDecimal price;
58 
59    // getters / setters or use @Data (Lombok)
60}
61```
62 
63### Repository
64 
65```java
66public interface ProductRepository extends JpaRepository<Product, Long> {
67    List<Product> findByNameContainingIgnoreCase(String name);
68}
69```
70 
71### Service (constructor injection)
72 
73```java
74@Service
75public class ProductService {
76    private final ProductRepository repo;
77 
78    public ProductService(ProductRepository repo) { // constructor injection — no @Autowired
79        this.repo = repo;
80    }
81 
82    @Transactional(readOnly = true)
83    public List<Product> search(String name) {
84        return repo.findByNameContainingIgnoreCase(name);
85    }
86 
87    @Transactional
88    public Product create(ProductRequest request) {
89        var product = new Product();
90        product.setName(request.name());
91        product.setPrice(request.price());
92        return repo.save(product);
93    }
94}
95```
96 
97### REST Controller
98 
99```java
100@RestController
101@RequestMapping("/api/v1/products")
102@Validated
103public class ProductController {
104    private final ProductService service;
105 
106    public ProductController(ProductService service) {
107        this.service = service;
108    }
109 
110    @GetMapping
111    public List<Product> search(@RequestParam(defaultValue = "") String name) {
112        return service.search(name);
113    }
114 
115    @PostMapping
116    @ResponseStatus(HttpStatus.CREATED)
117    public Product create(@Valid @RequestBody ProductRequest request) {
118        return service.create(request);
119    }
120}
121```
122 
123### DTO (record)
124 
125```java
126public record ProductRequest(
127    @NotBlank String name,
128    @DecimalMin("0.0") BigDecimal price
129) {}
130```
131 
132### Global Exception Handler
133 
134```java
135@RestControllerAdvice
136public class GlobalExceptionHandler {
137    @ExceptionHandler(MethodArgumentNotValidException.class)
138    @ResponseStatus(HttpStatus.BAD_REQUEST)
139    public Map<String, String> handleValidation(MethodArgumentNotValidException ex) {
140        return ex.getBindingResult().getFieldErrors().stream()
141            .collect(Collectors.toMap(FieldError::getField, FieldError::getDefaultMessage));
142    }
143 
144    @ExceptionHandler(EntityNotFoundException.class)
145    @ResponseStatus(HttpStatus.NOT_FOUND)
146    public Map<String, String> handleNotFound(EntityNotFoundException ex) {
147        return Map.of("error", ex.getMessage());
148    }
149}
150```
151 
152### Test Slice
153 
154```java
155@WebMvcTest(ProductController.class)
156class ProductControllerTest {
157    @Autowired MockMvc mockMvc;
158    @MockBean ProductService service;
159 
160    @Test
161    void createProduct_validRequest_returns201() throws Exception {
162        var product = new Product(); product.setName("Widget"); product.setPrice(BigDecimal.TEN);
163        when(service.create(any())).thenReturn(product);
164 
165        mockMvc.perform(post("/api/v1/products")
166                .contentType(MediaType.APPLICATION_JSON)
167                .content("""{"name":"Widget","price":10.0}"""))
168            .andExpect(status().isCreated())
169            .andExpect(jsonPath("$.name").value("Widget"));
170    }
171}
172```
173 
174## Constraints
175 
176### MUST DO
177 
178| Rule | Correct Pattern |
179|------|----------------|
180| Constructor injection | `public MyService(Dep dep) { this.dep = dep; }` |
181| Validate API input | `@Valid @RequestBody MyRequest req` on every mutating endpoint |
182| Type-safe config | `@ConfigurationProperties(prefix = "app")` bound to a record/class |
183| Appropriate stereotype | `@Service` for business logic, `@Repository` for data, `@RestController` for HTTP |
184| Transaction scope | `@Transactional` on multi-step writes; `@Transactional(readOnly = true)` on reads |
185| Hide internals | Catch domain exceptions in `@RestControllerAdvice`; return problem details, not stack traces |
186| Externalize secrets | Use environment variables or Spring Cloud Config — never `application.properties` |
187 
188### MUST NOT DO
189- Use field injection (`@Autowired` on fields)
190- Skip input validation on API endpoints
191- Use `@Component` when `@Service`/`@Repository`/`@Controller` applies
192- Mix blocking and reactive code (e.g., calling `.block()` inside a WebFlux chain)
193- Store secrets or credentials in `application.properties`/`application.yml`
194- Hardcode URLs, credentials, or environment-specific values
195- Use deprecated Spring Boot 2.x patterns (e.g., `WebSecurityConfigurerAdapter`)
196 
197[Documentation](https://jeffallan.github.io/claude-skills/skills/backend/spring-boot-engineer/)
198