Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

spring-conventions

/spring-conventions

Ustala konwencje Spring Boot dla kontrolerów REST, warstwy serwisów, wstrzykiwania zależności i walidacji danych.

Repozytorium
claude-sdlc ↗
Licencja
MIT
Ostatnia zmiana repozytorium
26.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 26.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Ustala konwencje Spring Boot dla kontrolerów REST, warstwy serwisów, wstrzykiwania zależności i walidacji danych.

Oryginalny opis (EN)

Spring Boot coding conventions: REST controller design, service layer, dependency injection, configuration, DTO patterns, exception handling, and Bean Validation. Apply on any Spring Boot project. Works alongside spring-boot-plugin:spring-data-jpa for persistence and java-foundation:java-conventions for domain objects. Use this skill to: - Structure REST endpoints with @RestController, proper HTTP semantics, and DTO mapping. - Enforce constructor injection and @ConfigurationProperties over @Value on fields. - Write @Service classes with transactional boundaries at the right layer. - Handle err

Jak działa

  1. REST Controller design
  2. DTO patterns
  3. Service layer
  4. Constructor injection
  5. Configuration with @ConfigurationProperties
  6. Bean Validation on DTOs
  7. Error handling with @RestControllerAdvice
  8. Domain exceptions
Sekcje z nagłówków SKILL.md, w oryginale · 222 linii, 756 słów
Podgląd SKILL.md
---
name: spring-conventions
description: |
  Spring Boot coding conventions: REST controller design, service layer, dependency injection, configuration, DTO patterns, exception handling, and Bean Validation. Apply on any Spring Boot project. Works alongside spring-boot-plugin:spring-data-jpa for persistence and java-foundation:java-conventions for domain objects.

  Use this skill to:
  - Structure REST endpoints with @RestController, proper HTTP semantics, and DTO mapping.
  - Enforce constructor injection and @ConfigurationProperties over @Value on fields.
  - Write @Service classes with transactional boundaries at the right layer.
  - Handle errors consistently with @RestControllerAdvice and ProblemDetail (RFC 9457).

  Do NOT use this skill for:
  - JPA entity and repository patterns — see spring-boot-plugin:spring-data-jpa.
  - Spring Security configuration — see the security phase injection in stack.md.
  - Build tool configuration — see java-foundation:build-tooling.
user-invocable: false
paths: ["src/main/java/**", "src/main/resources/**"]
---

# Spring Boot Conventions

## REST Controller design

```java
@RestController
@RequestMapping("/api/v1/users")
@RequiredArgsConstructor            // Lombok — generates constructor for final fields
public class UserController {

    private final UserService userService;

    @GetMapping("/{id}")
    public UserResponse getById(@PathVariable Long id) {
        return userService.findById(id)
            .orElseThrow(() -> new EntityNotFoundException("User", id));
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public UserResponse create(@RequestBody @Valid CreateUserRequest request) {
        return userService.create(request);
    }

    @PutMapping("/{id}")
    public UserResponse update(@PathVariable Long id,
                               @RequestBody @Valid UpdateUserRequest request) {
        return userService.update(id, request);
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void delete(@PathVariable Long id) {
        userService.delete(id);
    }
}
```

**Return DTO directly** (not `ResponseEntity<T>`) unless you need explicit control over headers or status codes beyond `@ResponseStatus`. `ResponseEntity` is valid for partial-update responses (202 Accepted + Location header) or conditional-GET (`ETag` / `If-None-Match`).

**HTTP semantics:**
- `GET` — idempotent, no body.
- `POST` — create, return `201 Created` + new resource.
- `PUT` — replace entire resource, return `200 OK` with updated resource.
- `PATCH` — partial update.
- `DELETE` — return `204 No Content`.

## DTO patterns

```java
// Request DTO — mutable, with Bean Validation
public record CreateUserRequest(
    @NotBlank @Email String email,
    @NotBlank @Size(min = 8) String password,
    @NotNull Role role
) {}

// Response DTO — immutable record, projection of domain data
public record UserResponse(
    Long id,
    String email,
    Role role,
    Instant createdAt
) {
    public static UserResponse from(User user) {
        return new UserResponse(user.id(), user.getEmail(), user.getRole(), user.getCreatedAt());
    }
}
```

**Separate request and response types.** Never expose the JPA entity directly from the controller — it leaks schema details and creates bidirectional serialization issues.

Use **static factory methods** (`from(Entity)`) on response records for clean mapping without a mapper library when the mapping is trivial. For complex mappings with many fields, introduce a `UserMapper` interface and implement with MapStruct or plain Java.

## Service layer

```java
@Service
@Transactional(readOnly = true)     // Default to read-only; override on write methods
@RequiredArgsConstructor
public class UserService {

    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;

    public Optional<UserResponse> findById(Long id) {
        return userRepository.findById(id).map(UserResponse::from);
    }

    @Transactional
    public UserResponse create(CreateUserRequest request) {
        if (userRepository.existsByEmail(request.email())) {
            throw new DuplicateEmailException(request.email());
        }
        var user = new User(request.email(), passwordEncoder.encode(request.password()), request.role());
        return UserResponse.from(userRepository.save(user));
    }

    @Transactional
    public void delete(Long id) {
        var user = userRepository.findById(id)
            .orElseThrow(() -> new EntityNotFoundException("User", id));
        userRepository.delete(user);
    }
}
```

`@Transactional(readOnly = true)` on the class sets a safe default; `@Transactional` on write methods overrides it. Avoid `@Transactional` on controllers — it spans too wide a scope and complicates error handling.

## Constructor injection

```java
// Prefer (with Lombok @RequiredArgsConstructor or explicit constructor)
@Service
public class OrderService {

    private final OrderRepository orderRepository;
    private final InvoiceService invoiceService;

    public OrderService(OrderRepository orderRepository, InvoiceService invoiceService) {
        this.orderRepository = orderRepository;
        this.invoiceService = invoiceService;
    }
}

// Avoid — field injection hides dependencies and makes testing harder
@Service
public class OrderService {
    @Autowired private OrderRepository orderRepository;  // DON'T
}
```

## Configuration with @ConfigurationProperties

```java
// application.yml
// app:
//   mail:
//     host: smtp.example.com
//     port: 587
//     from: noreply@example.com

@ConfigurationProperties(prefix = "app.mail")
public record MailProperties(String host, int port, String from) {}

// Register it
@SpringBootApplication
@EnableConfigurationProperties(MailProperties.class)
public class Application { ... }

// Inject like any bean
@Service
@RequiredArgsConstructor
public class MailService {
    private final MailProperties mailProperties;
}
```

Use `@ConfigurationProperties` records for any group of related configuration values. Avoid `@Value` on fields for groups — it scatters configuration and makes testing harder.

## Bean Validation on DTOs

```java
public record CreateProductRequest(
    @NotBlank(message = "name is required") String name,
    @NotNull @Positive BigDecimal price,
    @NotNull @Min(0) Integer stock,
    @NotBlank @Pattern(regexp = "[A-Z]{3}") String currencyCode
) {}
```

Activate in controllers with `@Valid` on `@RequestBody` / `@PathVariable` / `@ModelAttribute`. Spring Boot auto-configures `MethodArgumentNotValidException` handling — provide a `@RestControllerAdvice` to shape the error response.

## Error handling with @RestControllerAdvice

```java
@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(EntityNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ProblemDetail handleNotFound(EntityNotFoundException ex) {
        var problem = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
        problem.setTitle("Resource Not Found");
        return problem;
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.UNPROCESSABLE_ENTITY)
    public ProblemDetail handleValidation(MethodArgumentNotValidException ex) {
        var errors = ex.getBindingResult().getFieldErrors().stream()
            .map(e -> e.getField() + ": " + e.getDefaultMessage())
            .toList();
        var problem = ProblemDetail.forStatusAndDetail(
            HttpStatus.UNPROCESSABLE_ENTITY, "Validation failed");
        problem.setProperty("errors", errors);
        return problem;
    }
}
```

Use `ProblemDetail` (Spring Boot 3.x, RFC 9457) for structured error responses. For Spring Boot 2.x, return a custom `ErrorResponse` record.

## Domain exceptions

```java
public class EntityNotFoundException extends RuntimeException {
    public EntityNotFoundException(String entityName, Object id) {
        super(entityName + " not found: " + id);
    }
}

public class DuplicateEmailException extends RuntimeException {
    public DuplicateEmailException(String email) {
        super("Email already registered: " + email);
    }
}
```

Keep domain exceptions in a dedicated package (`exception` or `error`). Do not catch and re-throw `RuntimeException` unless translating (e.g., wrapping a JPA exception into a domain exception).

Wersje

W bazie nie ma innych skilli o nazwie spring-conventions.

Migawka bazy z 13.11.2026 · wersja paczki 163f80f65bc0 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100spring-boot-conventions
    Ujednolica kod Spring Boot w Javie, czyli kontrolery, serwisy, DTO, stronicowanie i format odpowiedzi błędów.
  • 100spring-boot-conventions
    Ustala zasady dla serwisów Spring Boot 4 na Javie 21+: układ pakietów, wstrzykiwanie przez konstruktor, błędy RFC 9457 i migracje Flyway.
  • 100spring-boot
    Wspiera tworzenie w Spring Boot 4 REST API, warstwy JPA, bezpieczeństwa, testów i usług chmurowych.
  • 100303-frameworks-spring-boot-validation
    Projektuje i sprawdza walidację w Spring Boot: Bean Validation na DTO, grupy ograniczeń, własne ograniczenia i spójne błędy.
  • 100spring-boot-patterns
    Podpowiada wzorce Spring Boot dla kontrolerów, serwisów i repozytoriów, w tym warstwy, konfigurację i wyjątki.
  • 100spring-boot-crud-patterns
    Generuje przepływy CRUD dla usług Spring Boot 3: agregaty Spring Data JPA, repozytoria, DTO, kontrolery i REST API, z walidacją niezmienników i granic transakcji.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.