Spring Boot copilot-instructions.md Template

Description

## copilot-instructions.md for Spring Boot Projects

This is a Spring Boot 3.3 project with Java 21. Follow these conventions:

### Architecture (Hexagonal)
- Domain layer: entities, value objects, domain services, repository interfaces
- Application layer: use cases, DTOs, mappers, port interfaces
- Infrastructure layer: JPA repositories, REST controllers, external service clients
- No Spring annotations in domain layer; keep it framework-agnostic

### Controllers
- `@RestController` with `@RequestMapping("/api/v1/resources")`
- Return `ResponseEntity<ApiResponse<T>>` from all endpoints
- Use `@Valid` on `@RequestBody` parameters
- Path variables for identifiers: `@PathVariable UUID id`
- Query parameters for filtering: `@RequestParam(defaultValue = "") String search`
- Document with Springdoc OpenAPI: `@Operation`, `@ApiResponse` annotations

### Services
- Constructor injection with `@RequiredArgsConstructor` (Lombok)
- Interface + implementation pattern for testability
- `@Transactional` at service method level, `readOnly = true` for queries
- Business validation in service layer, not controller
- Throw domain exceptions: `ResourceNotFoundException`, `BusinessRuleException`

### JPA / Hibernate
- Entity classes with `@Entity`, `@Table(name = "resources")`
- Use `@MappedSuperclass` for base entity with `id`, `createdAt`, `updatedAt`
- `FetchType.LAZY` for all associations; explicit `JOIN FETCH` in queries
- Use `@EntityGraph` for optimized loading without N+1
- Specifications for dynamic queries: `Specification<T>` composable filters
- Flyway for database migrations: `V1__description.sql` naming

### Security
- Spring Security 6.x with `SecurityFilterChain` bean configuration
- JWT filter in security chain for stateless authentication
- Method-level security: `@PreAuthorize("hasRole('ADMIN')")` where needed
- CORS configured in `SecurityFilterChain`, not controller-level
- Password encoding: `BCryptPasswordEncoder` with strength 12

### Testing
- `@SpringBootTest` for integration, `@WebMvcTest` for controller, `@DataJpaTest` for repository
- `@Testcontainers` with PostgreSQL for realistic integration tests
- Use `TestRestTemplate` or `MockMvc` for API testing
- Builder pattern for test data with Instancio or custom builders

### Configuration
- `application.yml` with profile-specific overrides: `application-dev.yml`, `application-prod.yml`
- Externalize secrets via environment variables: `${DB_PASSWORD}`
- Use `@ConfigurationProperties` for type-safe config binding
- Actuator endpoints enabled for health, metrics, info

Free to copy and use. Compatible with GitHub Copilot, GPT-5.

Usage Instructions

Tags

Compatible AI Models

Version History

Related Prompts