spring-feature
Checklist for adding a backend endpoint or feature slice end to end (migration → entity → repository → service → DTO records → controller → errors → tests → OpenAPI). Use whenever adding or changing a
SKILL.md.claude/skills/spring-feature/SKILL.md
GitHub/spring-feature: add a backend slice
Follow backend/CLAUDE.md. Work top to bottom. Skip steps that don't apply, and say which ones you skipped.
- Contract first. Write the request/response record shapes and status codes, and confirm them with the user if they're non-trivial.
- Migration (if schema changes): new
V{n}__*.sql. Add indexes for the query you're about to write. Updatedocs/DATA_MODEL.md. - Entity: protected no-arg constructor, meaningful constructor, getters, intention-revealing methods,
@ManyToOne(fetch = LAZY),@Enumerated(EnumType.STRING). - Repository: user-scoped finders (
findByIdAndUserId). Use a projection record for read-heavy or aggregate queries. - Service: package-private unless another feature needs it.
@Transactional/@Transactional(readOnly = true). Map entity → DTO here. Throw domain exceptions (XNotFoundException) for the advice to translate. - DTOs: records with Bean Validation annotations on requests. Use a static
from(Entity)factory on the response record, or a small mapper method in the service. - Controller: thin.
@Valid @RequestBody, authenticated user via@AuthenticationPrincipal(once auth exists). Use 201 +Locationfor creates and 204 for empty responses. - Errors: new exception types registered in the global
@RestControllerAdvice→ProblemDetail. - Tests:
- pure logic → plain JUnit
- controller →
@WebMvcTest(happy path, validation 400, not-found 404, and 401/403 once auth exists) - repository/native SQL →
@DataJpaTest+ Testcontainers - one
@SpringBootTesthappy path if the slice crosses modules
- Security check: is every query scoped by user? Is anything sensitive logged or returned?
- OpenAPI: check
/v3/api-docslooks right, and remind the user to runnpm run gen:apiin mobile. - Run
./mvnw verifyand report results.