spring-boot-best-practices

kousen's avatarfrom kousen

Generate Spring Boot components following modern Java best practices and team conventions

⭐28stars🔀30forks📁View on GitHub🕐Updated Nov 20, 2025⬇️2downloads

When & Why to Use This Skill

This Claude skill streamlines Spring Boot development by generating production-ready Java components that strictly adhere to modern best practices. It automates the creation of REST controllers, service layers, JPA entities, and comprehensive unit tests, ensuring architectural consistency, maintainability, and high-quality code standards across your project.

Use Cases

  • 1. Rapid API Scaffolding: Quickly generate standardized RESTful endpoints with proper HTTP methods, versioning, and ResponseEntity handling.
  • 2. Architectural Standardization: Enforce team-wide conventions such as constructor-based dependency injection and clean package layering.
  • 3. Automated Test Suite Generation: Produce boilerplate-free MockMvc and Mockito tests to ensure high code coverage for controllers and business logic.
  • 4. Data Layer Implementation: Create JPA entities and repositories with optimized mapping, Lombok annotations, and transaction management.
  • 5. Code Refactoring and Review: Analyze existing Spring Boot code to identify and fix anti-patterns like field injection or improper error handling.
nameSpring Boot Best Practices
descriptionGenerate Spring Boot components following modern Java best practices and team conventions

Spring Boot Code Generation Guidelines

When generating or reviewing Spring Boot code, follow these best practices:

Dependency Injection

  • Use constructor injection, never field injection with @Autowired
  • Mark injected fields as private final
  • Let Lombok's @RequiredArgsConstructor generate constructors when appropriate
// Good
@Service
@RequiredArgsConstructor
public class UserService {
    private final UserRepository userRepository;
    private final EmailService emailService;
}

// Avoid
@Service
public class UserService {
    @Autowired
    private UserRepository userRepository; // Field injection - avoid
}

Package Structure

Follow standard Spring Boot layering:

com.example.project/
├── controller/       # REST endpoints, @RestController
├── service/          # Business logic, @Service
├── repository/       # Data access, extends JpaRepository
├── model/            # JPA entities, @Entity
├── dto/              # Data transfer objects
├── config/           # Configuration classes, @Configuration
└── exception/        # Custom exceptions and @ControllerAdvice

REST Controllers

  • Use proper HTTP methods (GET, POST, PUT, DELETE, PATCH)
  • Return ResponseEntity<T> for explicit status codes
  • Use @Valid for request body validation
  • Include API versioning in paths (e.g., /api/v1/users)
@RestController
@RequestMapping("/api/v1/users")
@RequiredArgsConstructor
public class UserController {
    private final UserService userService;

    @GetMapping("/{id}")
    public ResponseEntity<UserDto> getUser(@PathVariable Long id) {
        return userService.findById(id)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
    }

    @PostMapping
    public ResponseEntity<UserDto> createUser(@Valid @RequestBody CreateUserRequest request) {
        UserDto created = userService.create(request);
        return ResponseEntity.status(HttpStatus.CREATED).body(created);
    }
}

Service Layer

  • Keep services focused on business logic
  • Use Optional<T> for potentially absent results
  • Throw custom exceptions for business rule violations
  • Add @Transactional where needed
@Service
@RequiredArgsConstructor
public class UserService {
    private final UserRepository userRepository;

    public Optional<User> findById(Long id) {
        return userRepository.findById(id);
    }

    @Transactional
    public User create(CreateUserRequest request) {
        if (userRepository.existsByEmail(request.getEmail())) {
            throw new UserAlreadyExistsException(request.getEmail());
        }
        User user = new User(request.getName(), request.getEmail());
        return userRepository.save(user);
    }
}

JPA Entities

  • Use @Entity and @Table annotations
  • Include @Id with generation strategy
  • Use Lombok annotations: @Data, @NoArgsConstructor, @AllArgsConstructor
  • Include proper relationships with @OneToMany, @ManyToOne, etc.
@Entity
@Table(name = "users")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String name;

    @Column(nullable = false, unique = true)
    private String email;

    @OneToMany(mappedBy = "user", cascade = CascadeType.ALL)
    private List<Order> orders = new ArrayList<>();
}

Testing Requirements

For every component generated:

  1. Controller Tests - Use @WebMvcTest and MockMvc
  2. Service Tests - Use @ExtendWith(MockitoExtension.class) with mocks
  3. Repository Tests - Use @DataJpaTest with test database
  4. Integration Tests - Use @SpringBootTest for end-to-end scenarios
@WebMvcTest(UserController.class)
class UserControllerTest {
    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private UserService userService;

    @Test
    void getUser_WhenExists_ReturnsUser() throws Exception {
        // Arrange
        UserDto user = new UserDto(1L, "John Doe", "john@example.com");
        when(userService.findById(1L)).thenReturn(Optional.of(user));

        // Act & Assert
        mockMvc.perform(get("/api/v1/users/1"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.name").value("John Doe"));
    }
}

Documentation

  • Add comprehensive JavaDoc for public methods
  • Include @param, @return, and @throws tags
  • Document business rules and assumptions
  • Use OpenAPI/Swagger annotations for REST endpoints
/**
 * Creates a new user in the system.
 *
 * @param request the user creation request containing name and email
 * @return the created user with generated ID
 * @throws UserAlreadyExistsException if a user with the email already exists
 */
@Transactional
public User create(CreateUserRequest request) {
    // implementation
}

Error Handling

  • Create custom exceptions extending RuntimeException
  • Use @ControllerAdvice for global exception handling
  • Return proper HTTP status codes with error details
@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleUserNotFound(UserNotFoundException ex) {
        ErrorResponse error = new ErrorResponse(
            HttpStatus.NOT_FOUND.value(),
            ex.getMessage()
        );
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }
}

Configuration

  • Use application.yml over application.properties
  • Externalize configuration values
  • Use Spring profiles for environment-specific config
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false

When This Skill Activates

This skill automatically activates when:

  • Generating Spring Boot controllers, services, or repositories
  • Creating JPA entities or DTOs
  • Writing Spring Boot tests
  • Reviewing existing Spring Boot code
  • Questions about Spring Boot best practices