Spring Boot Project Rules

springjavabackend

Enforces Spring Boot conventions including layered architecture, dependency injection, JPA entity design, security configuration, and testing patterns for Java enterprise applications.

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

## Spring Boot Project Rules ### Layered Architecture - Follow strict layer separation: Controller → Service → Repository - Controllers handle HTTP mapping and request/response DTOs only - Services contain all business logic and orchestrate repository calls - Repositories interact with the database exclusively - Do not inject repositories directly into controllers - `@Component`, `@Service`, `@Repository`, `@Controller` are semantic — use the correct annotation ### Dependency Injection - Prefer constructor injection over field injection (`@Autowired` on field is an anti-pattern) - Use `final` fields with constructor injection for immutability - Use `@RequiredArgsConstructor` (Lombok) to generate constructor injection boilerplate - Avoid `ApplicationContext.getBean()` — let Spring manage dependency resolution - Use `@Primary` or `@Qualifier` to resolve ambiguous bean injection, never leave it implicit ### Controllers - Annotate all REST controllers with `@RestController` and `@RequestMapping("/api/v1/[resource]")` - Use method-level annotations: `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping` - Validate request bodies with `@Valid` and Bean Validation annotations on DTOs - Return `ResponseEntity<T>` for explicit HTTP status control - Use `@ControllerAdvice` with `@ExceptionHandler` for centralized error handling - DTOs must be records or final classes — never expose JPA entities from controllers ### JPA & Entities - Use `@Entity` with `@Table(name = "...")` for explicit table naming - Primary keys: use `@GeneratedValue(strategy = GenerationType.IDENTITY)` or UUID - Always define `equals()` and `hashCode()` based on a business key, not the generated ID - Use `@Version` for optimistic locking on entities that may be concurrently updated - Fetch type: use `FetchType.LAZY` by default; use `EAGER` only when always needed - Avoid bidirectional relationships unless querying from both sides; if used, manage both sides - Use `@EntityGraph` or JPQL `JOIN FETCH` to avoid N+1 queries ### Spring Data Repositories - Extend `JpaRepository<Entity, ID>` for standard CRUD - Use query method naming for simple queries: `findByEmailAndActive(String email, boolean active)` - Use `@Query` with JPQL for complex queries; use `nativeQuery = true` sparingly - Use `@Modifying` with `@Transactional` for update/delete queries - Use `Pageable` and `Page<T>` for paginated results ### Transactions - Annotate service methods with `@Transactional` where multiple DB operations must be atomic - Use `@Transactional(readOnly = true)` for read-only service methods (performance optimization) - Transactions only work on Spring-managed proxies — never call `@Transactional` methods internally - Set rollback rules explicitly: `@Transactional(rollbackFor = SpecificException.class)` ### Configuration - Use `application.yml` over `application.properties` for readability - Bind config to `@ConfigurationProperties` classes with validation annotations - Use Spring profiles (`@Profile("dev")`, `@Profile("prod")`) for environment-specific beans - Never hardcode secrets — use environment variables or Spring Vault integration ### Security - Configure `SecurityFilterChain` as a bean — do not extend `WebSecurityConfigurerAdapter` (deprecated) - Enable CSRF for browser-facing apps; disable only for stateless REST APIs with token auth - Use `BCryptPasswordEncoder` for password hashing - Apply `@PreAuthorize("hasRole('ADMIN')")` on service methods for method-level security ### Testing - Use `@SpringBootTest` for integration tests; `@WebMvcTest` for controller slice tests - Use `@DataJpaTest` for repository layer tests with an in-memory database - Mock service dependencies in controller tests with `@MockBean` - Use `@Sql` annotation to set up test data for integration tests - Test names must describe behavior: `should_return_404_when_user_not_found()` ### Anti-patterns - Do not use `@Autowired` on fields in production code — use constructor injection - Do not share `EntityManager` across threads — it is not thread-safe - Do not put `@Transactional` on controller methods — transactions belong in the service layer - Do not catch and swallow exceptions — log them and rethrow or translate to domain exceptions

CLI

npx mindaxis apply spring-boot-rules --target cursor --scope project

Используется в паках

Не используется ни в одном паке

← Правила