java-spring-service

What this skill does

# Spring Boot Service Generator

## Table of Contents

- [Purpose](#purpose)
- [When to Use](#when-to-use)
- [Quick Start](#quick-start)
- [Instructions](#instructions)
- [Examples](#examples)
- [Requirements](#requirements)
- [Best Practices Checklist](#best-practices-checklist)
- [Output Format](#output-format)
- [Error Handling](#error-handling)

## Purpose

Generates complete, production-ready Spring Boot services following industry best practices: proper layered architecture (Controller/Service/Repository), dependency injection, exception handling with @ControllerAdvice, OpenAPI/Swagger documentation, configuration management, and comprehensive logging.

## When to Use

Use this skill when you need to:
- Create new Spring Boot REST APIs
- Generate CRUD services with JPA repositories
- Set up layered architecture (Controller/Service/Repository)
- Implement RESTful endpoints with proper HTTP methods
- Add OpenAPI/Swagger documentation
- Configure Spring Data JPA entities and repositories
- Create DTOs and mappers for API contracts
- Implement global exception handling with @ControllerAdvice
- Set up dependency injection with constructor injection
- Generate complete Spring Boot microservices
- Add pagination and sorting to endpoints
- Configure database migrations with Flyway
- Bootstrap new Spring Boot projects with best practices

## Quick Start
Describe the service you need and get a complete implementation:

```bash
# Create a complete CRUD service
Create a Spring Boot service for User management with CRUD operations

# Create a specific endpoint
Create a Spring Boot REST endpoint for processing orders
```

## Instructions

### Step 1: Understand Service Requirements
Identify what needs to be created:
- Entity/domain model (JPA entity)
- Repository layer (Spring Data)
- Service layer (business logic)
- Controller layer (REST API)
- DTOs (request/response objects)
- Exception handling
- Configuration
- API documentation

### Step 2: Generate Domain Model (Entity)
Create JPA entity with proper annotations:

```java
@Entity
@Table(name = "users")
@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 100)
    private String name;

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

    @Column(name = "phone_number", length = 20)
    private String phoneNumber;

    @Enumerated(EnumType.STRING)
    @Column(nullable = false)
    private UserStatus status;

    @CreatedDate
    @Column(nullable = false, updatable = false)
    private LocalDateTime createdAt;

    @LastModifiedDate
    @Column(nullable = false)
    private LocalDateTime updatedAt;

    @Version
    private Long version;
}
```

**Key Annotations:**
- @Entity, @Table - JPA entity mapping
- @Id, @GeneratedValue - Primary key generation
- @Column - Column constraints and naming
- @Enumerated - Enum mapping
- @CreatedDate, @LastModifiedDate - Audit fields
- @Version - Optimistic locking
- @Data (Lombok) - Getters, setters, toString, equals, hashCode
- @Builder (Lombok) - Builder pattern

### Step 3: Create DTOs (Data Transfer Objects)
Separate internal models from API contracts:

```java
// Request DTO
@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class CreateUserRequest {
    @NotBlank(message = "Name is required")
    @Size(min = 2, max = 100, message = "Name must be between 2 and 100 characters")
    private String name;

    @NotBlank(message = "Email is required")
    @Email(message = "Email must be valid")
    private String email;

    @Pattern(regexp = "^\\+?[1-9]\\d{1,14}$",
        message = "Phone number must be in E.164 format")
    private String phoneNumber;
}

// Response DTO
@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class UserResponse {
    private Long id;
    private String name;
    private String email;
    private String phoneNumber;
    private UserStatus status;
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}

// Mapper
@Component
public class UserMapper {
    public User toEntity(CreateUserRequest request) {
        return User.builder()
            .name(request.getName())
            .email(request.getEmail())
            .phoneNumber(request.getPhoneNumber())
            .status(UserStatus.ACTIVE)
            .build();
    }

    public UserResponse toResponse(User user) {
        return UserResponse.builder()
            .id(user.getId())
            .name(user.getName())
            .email(user.getEmail())
            .phoneNumber(user.getPhoneNumber())
            .status(user.getStatus())
            .createdAt(user.getCreatedAt())
            .updatedAt(user.getUpdatedAt())
            .build();
    }
}
```

### Step 4: Create Repository Layer
Use Spring Data JPA for data access:

```java
@Repository
public interface UserRepository extends JpaRepository<User, Long> {

    Optional<User> findByEmail(String email);

    List<User> findByStatus(UserStatus status);

    @Query("SELECT u FROM User u WHERE u.name LIKE %:searchTerm% OR u.email LIKE %:searchTerm%")
    Page<User> searchUsers(@Param("searchTerm") String searchTerm, Pageable pageable);

    boolean existsByEmail(String email);

    @Modifying
    @Query("UPDATE User u SET u.status = :status WHERE u.id = :id")
    int updateUserStatus(@Param("id") Long id, @Param("status") UserStatus status);
}
```

**Key Features:**
- Extends JpaRepository for CRUD operations
- Custom query methods (findByEmail, findByStatus)
- @Query for complex queries
- Pagination support with Pageable
- @Modifying for update/delete queries

### Step 5: Create Service Layer
Implement business logic with transactions:

```java
@Service
@RequiredArgsConstructor
@Slf4j
public class UserService {
    private final UserRepository userRepository;
    private final UserMapper userMapper;
    private final ApplicationEventPublisher eventPublisher;

    @Transactional(readOnly = true)
    public UserResponse getUserById(Long id) {
        log.debug("Fetching user with id: {}", id);
        User user = userRepository.findById(id)
            .orElseThrow(() -> new UserNotFoundException(id));
        return userMapper.toResponse(user);
    }

    @Transactional(readOnly = true)
    public Page<UserResponse> getAllUsers(Pageable pageable) {
        log.debug("Fetching all users: page={}, size={}",
            pageable.getPageNumber(), pageable.getPageSize());
        return userRepository.findAll(pageable)
            .map(userMapper::toResponse);
    }

    @Transactional
    public UserResponse createUser(CreateUserRequest request) {
        log.info("Creating user: email={}", request.getEmail());

        if (userRepository.existsByEmail(request.getEmail())) {
            throw new DuplicateEmailException(request.getEmail());
        }

        User user = userMapper.toEntity(request);
        User savedUser = userRepository.save(user);

        eventPublisher.publishEvent(new UserCreatedEvent(savedUser));

        log.info("User created successfully: id={}", savedUser.getId());
        return userMapper.toResponse(savedUser);
    }

    @Transactional
    public UserResponse updateUser(Long id, UpdateUserRequest request) {
        log.info("Updating user: id={}", id);

        User user = userRepository.findById(id)
            .orElseThrow(() -> new UserNotFoundException(id));

        updateUserFields(user, request);
        User updatedUser = userRepository.save(user);

        log.info("User updated successfully: id={}", id);
        return userMapper.toResponse(updatedUser);
    }

    @Transactional
    public void deleteUser(Long id) {
        log.info("Deleting user: id={}", id);

        if (!userRepository.existsById(id)) {
            throw new UserNotFoundException(id);
        }

        userRepository.deleteById(id);
        log.info("User deleted successfully: id={}", id);
    }

    p