Przejdź do treści
Biblioteka skilli
Programowanie · Pisanie

spring-boot-conventions

/spring-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.

Repozytorium
devkit-skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
03.11.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
7
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 03.11.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 zasady dla serwisów Spring Boot 4 na Javie 21+: układ pakietów, wstrzykiwanie przez konstruktor, błędy RFC 9457 i migracje Flyway.

Oryginalny opis (EN)

Team conventions for Spring Boot 4.x on Java 21+ services: package-by-feature layout, constructor injection, records as DTOs, REST controllers with RFC 9457 Problem Details, Spring Data JPA and transaction boundaries, typed @ConfigurationProperties, Flyway migrations, JSpecify null-safety, virtual threads, Micrometer observability. Use when creating or modifying a Spring Boot application, controller, service, entity, repository or configuration, or when asked how to structure Java backend code. Not for test code (see spring-boot-testing) or API contract design (see api-contract).

Jak działa

  1. Use when / do not use
  2. Workflow
  3. Rules
  4. References
Sekcje z nagłówków SKILL.md, w oryginale · 79 linii, 789 słów
Podgląd SKILL.md
---
name: spring-boot-conventions
description: "Team conventions for Spring Boot 4.x on Java 21+ services: package-by-feature layout, constructor injection, records as DTOs, REST controllers with RFC 9457 Problem Details, Spring Data JPA and transaction boundaries, typed @ConfigurationProperties, Flyway migrations, JSpecify null-safety, virtual threads, Micrometer observability. Use when creating or modifying a Spring Boot application, controller, service, entity, repository or configuration, or when asked how to structure Java backend code. Not for test code (see spring-boot-testing) or API contract design (see api-contract)."
license: MIT
metadata:
  author: baibesh/devkit-skills
---

# Spring Boot Conventions

Targets: Spring Boot 4.x (4.0/4.1), Spring Framework 7, Java 21 or 25. First detect the project's real versions from pom.xml / build.gradle(.kts) and adapt; never downgrade a project.

## Use when / do not use

- Use when adding or changing controllers, services, entities, repositories, configuration, migrations or wiring in a Spring Boot service.
- Use when asked how to lay out a new Java backend or where a class belongs.
- Do not use for tests: see `spring-boot-testing`. Do not use for designing the HTTP contract itself (resource names, status codes, OpenAPI): see `api-contract`.
- If the `spring-boot-community` plugin (sivalabs) is installed, its `spring-boot` skill has deeper references; these conventions take precedence where they differ.

## Workflow

1. Read the build file: Boot version, Java toolchain, starters present (Boot 4 uses modular starters such as `spring-boot-starter-webmvc`, `spring-boot-starter-flyway`). Match what exists.
2. Locate the feature package (`com.acme.<feature>`); create `api`, `domain`, `infra` subpackages only as needed. Never add a top-level `controller/` or `service/` package.
3. Model the change inward-out: Flyway migration, then entity and repository, then service with the transaction boundary, then controller and DTO records.
4. Put new settings in a `@ConfigurationProperties` record with `@Validated`; never sprinkle `@Value`.
5. Map failures to Problem Details through the shared `@RestControllerAdvice`; throw domain exceptions, never build error bodies in controllers.
6. Add `package-info.java` with `@NullMarked` to every new package; mark nullable spots with `@Nullable`.
7. Make the change observable: meaningful log lines (structured), metrics or `@Observed` on key operations, health indicators for new external dependencies.
8. Build and run the tests (`./mvnw verify` or `./gradlew check`); hand test authoring to `spring-boot-testing`.

## Rules

- Do organize by feature: `com.acme.orders.{api,domain,infra}`; features talk through public services or events, not each other's repositories.
- Do use constructor injection with `final` fields (or records for simple beans); never `@Autowired` on fields or setters.
- Do use Java records for request/response DTOs, commands, events and projections.
- Don't return or accept JPA entities in controllers; map explicitly (a static `from(entity)` factory on the response record is enough).
- Do put `@Transactional` on service methods only (`readOnly = true` for queries); never on controllers or repositories you write.
- Don't use `Optional` for fields, parameters or collections; return `Optional` only from lookups.
- Do validate input with Jakarta Bean Validation (`@Valid @RequestBody`, constraints on record components).
- Do return RFC 9457 Problem Details for every error via one `@RestControllerAdvice` extending `ResponseEntityExceptionHandler`.
- Do bind config to `@ConfigurationProperties` records annotated `@Validated`, registered via `@ConfigurationPropertiesScan`.
- Do keep secrets out of `application.yml`; read them from env vars or a secret store.
- Do write schema changes as Flyway scripts in `src/main/resources/db/migration` (`V<n>__<desc>.sql`); never edit an applied migration.
- Do set `spring.jpa.hibernate.ddl-auto=validate` and `spring.jpa.open-in-view=false`.
- Do mark `@ManyToOne`/`@OneToOne` `fetch = LAZY` and fetch what a use case needs with `@EntityGraph` or a projection.
- Do enable `spring.threads.virtual.enabled=true` on Java 21+; size DB pools for the database, not the request rate.
- Do annotate each package with JSpecify `@NullMarked` in `package-info.java`.
- Do use `spring-boot-docker-compose` (dev-only) with a `compose.yaml` for local Postgres and friends.
- Do expose only `health`, `info`, `prometheus` (plus what ops asks for) over HTTP; keep `env`, `heapdump`, `loggers` off public ports.
- Do log through SLF4J with structured output: `logging.structured.format.console=ecs` (or `logstash`) outside local dev.
- Don't log secrets, tokens or full request bodies; use parameterized messages, not string concatenation.
- Do use `RestClient` (or HTTP interface clients) for outbound HTTP; never `RestTemplate` in new code.
- Do keep `@SpringBootApplication` in the root package and free of bean definitions.
- Don't catch and swallow exceptions; translate them into domain exceptions or let them reach the advice.
- Do use `Instant`/`OffsetDateTime` in UTC for timestamps and `BigDecimal` for money.
- Do note that Boot 4 ships Jackson 3 (`tools.jackson.*`); annotations stay in `com.fasterxml.jackson.annotation`.

```java
// Shape of a typical feature slice
@RestController
@RequestMapping("/api/orders")
class OrderController {
    private final OrderService orders;
    OrderController(OrderService orders) { this.orders = orders; }

    @PostMapping
    ResponseEntity<OrderResponse> create(@Valid @RequestBody CreateOrderRequest req, UriComponentsBuilder uri) {
        OrderResponse created = orders.create(req);
        return ResponseEntity.created(uri.path("/api/orders/{id}").build(created.id())).body(created);
    }
}

public record CreateOrderRequest(@NotBlank String customerId, @NotEmpty List<@Valid LineItem> items) {}
```

## References

| File | Read when ... |
|---|---|
| [references/project-structure.md](references/project-structure.md) | creating a service or feature, deciding where a class goes, enforcing module boundaries, considering Spring Modulith |
| [references/rest-controllers.md](references/rest-controllers.md) | writing controllers: validation, pagination, versioning, Problem Details shape and the exception advice |
| [references/persistence-jpa.md](references/persistence-jpa.md) | designing entities and repositories, fixing N+1, projections, auditing, transactions, Flyway |
| [references/configuration.md](references/configuration.md) | adding properties, profiles, secrets, Docker Compose dev setup, virtual threads |
| [references/security-basics.md](references/security-basics.md) | protecting endpoints with JWT resource server, method security, CORS |
| [references/observability.md](references/observability.md) | Actuator exposure, Micrometer metrics, tracing, health checks, structured logging |
Pliki w paczce (7)
  • SKILL.md 7 KB
  • references/configuration.md 5 KB
  • references/observability.md 5 KB
  • references/persistence-jpa.md 7 KB
  • references/project-structure.md 5 KB
  • references/rest-controllers.md 7 KB
  • references/security-basics.md 5 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · baibesh/devkit-skills100MIT
jameskomo/config-drift-checker100Apache-2.0

Migawka bazy z 13.11.2026 · wersja paczki a77a0b2f0fbf (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-idioms
    Podpowiada wzorce Spring Boot 3.x, czyli wstrzykiwanie przez konstruktor, błędy RFC 7807 i testy warstw.
  • 100spring-boot
    Pomaga tworzyć usługi Spring Boot 4.x: kontrolery REST, encje JPA z Flyway, zabezpieczenia OAuth2 i testy Testcontainers.
  • 91stack-spring-boot
    Opisuje konwencje Spring Boot: pakiety wg funkcji, wstrzykiwanie przez konstruktor, błędy ProblemDetail, testy MockMvc i Testcontainers oraz Flyway.
  • 100spring-conventions
    Ustala konwencje Spring Boot dla kontrolerów REST, warstwy serwisów, wstrzykiwania zależności i walidacji danych.
  • 100spring-boot-production-architecture
    Wspiera architekturę produkcyjną Spring Boot 3.3+ z Javą 21, wątkami wirtualnymi, warstwami, Spring Data JPA, HikariCP, wyjątkami RFC 7807 i Micrometer.
  • 100spring-boot
    Wspiera tworzenie w Spring Boot 4 REST API, warstwy JPA, bezpieczeństwa, testów i usług chmurowych.

Uwagi i zgłoszenia

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