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

java-spring-patterns

/java-spring-patterns

Pomaga projektować i przeglądać usługi Java 17+ i Spring Boot 3 oraz 4, z transakcjami, idiomami i testami.

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

Brak sygnałów. Repozytorium zmienione 04.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

Pomaga projektować i przeglądać usługi Java 17+ i Spring Boot 3 oraz 4, z transakcjami, idiomami i testami.

Oryginalny opis (EN)

Java 17+ and Spring Boot 3/4 architecture, idioms, transactions and testing. Use when building or reviewing Java or Spring Boot services.

Jak działa

  1. 1. Find out what the project is
  2. 2. Match what is already there
  3. 3. Apply the topic file for the task
  4. 4. Review against what actually breaks
  5. Sources
Sekcje z nagłówków SKILL.md, w oryginale · 165 linii, 1 257 słów
Podgląd SKILL.md
---
name: java-spring-patterns
description: "Java 17+ and Spring Boot 3/4 architecture, idioms, transactions and testing. Use when building or reviewing Java or Spring Boot services."
allowed-tools: Read Write Edit Glob Grep
---

# Working on a Java / Spring Boot codebase

This file is a working method and an index. The detail lives in topic files next to it; read
only the ones the task needs, because each one is long enough to crowd out the code you are
looking at.

The method has four moves, in this order: **find out what the project is**, **match what is
already there**, **apply the topic file for the task**, and **review the result against the
failure modes that actually hurt Spring services**. Skipping the first move is the most common
way to give advice that does not compile or does not fit.

Not Java? Stop here. Node.js work belongs to `cardume-backend:nodejs-best-practices`, and
API contract questions that are language-neutral belong to `cardume-backend:api-patterns`.

## 1. Find out what the project is

Read the build file before suggesting any code. Advice for Java 21 is wrong on Java 17, and a
Boot 4 starter name is wrong on Boot 3.

- **JDK release:** `maven.compiler.release` / `<java.version>` in `pom.xml`, or the toolchain
  `languageVersion` in `build.gradle(.kts)`. Then check what that release allows in
  [capability-baseline.md](capability-baseline.md). Preview features need `--enable-preview`
  and are not a default.
- **Spring Boot generation:** the parent POM or the `org.springframework.boot` plugin version.
  3.x and 4.x share the conventions here but differ in starters, test annotations and some
  property names; [capability-baseline.md](capability-baseline.md#framework-baseline) has the
  table.
- **Persistence and messaging:** Spring Data JPA, JDBC, R2DBC; Kafka, Rabbit, none. The answer
  changes how transactions, locking and events are written.
- **Existing shape:** look at the top-level packages under the `@SpringBootApplication` class.
  Feature packages with `web`/`service`/`persistence` inside are layered; `port`/`adapter`
  packages are hexagonal; a `package-info.java` with `@ApplicationModule` or a
  `spring-modulith` dependency means a modular monolith.
- **Existing tests:** Testcontainers, ArchUnit or `ApplicationModules.verify()` tests are rules
  the team already decided to enforce. Keep them green.

When the prompt gives a code snippet with no build file (a review question, say), take the
versions it states and say which assumptions you made.

## 2. Match what is already there

Consistency is worth more than local perfection. A hexagonal use case dropped into a layered
codebase is harder to maintain than one more well-written `@Service`.

- Follow the existing package style, naming, mapping approach and error format.
- When the existing style itself causes the bug (field injection, logic in controllers,
  `double` balances), fix it in the code you touch and say why. Do not rewrite unrelated
  modules in the same change.
- Changing the architecture style is a decision, not a refactor. Use
  [architecture-selection.md](architecture-selection.md) to argue it, and record it with
  `cardume-core:adr` if the team agrees.

## 3. Apply the topic file for the task

Pick by what the task touches. Several can apply; read them one at a time as the work reaches
them.

**Language and platform**
- Is this idiom available here? → [capability-baseline.md](capability-baseline.md)
- Records, sealed types, pattern matching, text blocks, virtual threads, plain-JDK idioms →
  [java-language.md](java-language.md)

**Framework**
- Dependency injection, `@Transactional` boundaries, locking, money types, request/response
  records, Bean Validation, ProblemDetail errors, configuration, HTTP clients →
  [spring-conventions.md](spring-conventions.md)

**Architecture** — start with [architecture-selection.md](architecture-selection.md) when the
style is not yet decided, then go to the style itself:
- Feature-first web/service/persistence layers → [mvc-layered.md](mvc-layered.md)
- Ports and adapters, framework-free core → [hexagonal.md](hexagonal.md)
- Bounded contexts, aggregates, value objects → [ddd.md](ddd.md)
- One deployable with verified module boundaries → [modular-monolith.md](modular-monolith.md)
- Separate read models, event-sourced aggregates, Axon →
  [cqrs-event-sourcing.md](cqrs-event-sourcing.md)
- Spring application events, transactional listeners, outbox, Kafka →
  [eda.md](eda.md)

**Proof and operations**
- Test slices, Testcontainers, ArchUnit, Modulith tests, Boot 3 → 4 test migration →
  [testing.md](testing.md)
- Micrometer observations, metrics cardinality, tracing, logs →
  [observability.md](observability.md)

Related skills, when the question leaves Java:
`cardume-backend:api-patterns` (resource design, status codes, versioning),
`cardume-core:database-design` (schema, indexes, migrations),
`cardume-core:clean-code` (naming and function shape in any language),
`cardume-qa:testing-patterns` (test strategy across the stack).

## 4. Review against what actually breaks

Most production incidents in Spring services come from a short list of causes, and almost all
of them are visible in one controller-plus-service pair. Walk the request from the edge to the
database and back, and answer each question below. When the answer is "no", the finding goes
in the review with the fix and the reason.

**At the edge.** Does a state-changing endpoint take a request body as a `record` with Bean
Validation (`@Valid @RequestBody`), rather than loose query parameters? Is the controller thin:
map the request to a command, call one service method, map the result to a response record
with the right status? See [spring-conventions.md](spring-conventions.md#web-layer-input-output-and-errors).

**Wiring.** Are collaborators injected through the constructor into `final` fields? Field
injection hides dependencies and forces a Spring context into every unit test, which is why
"hard to test" usually points here.

**The unit of work.** Is there exactly one `@Transactional` boundary per use case, on a
service method, wrapping *every* write of that use case? Two `save` calls in a controller run
as separate transactions, so an exception between them leaves the first write committed. That
is the classic "debited but not credited" bug. Watch for self-invocation, which bypasses the
proxy, and for checked exceptions, which do not roll back by default.

**Order of operations.** Are all checks (existence, limits, permissions, invariants) done
before the first mutation? Rolling back is the safety net, not the plan; a rejected request
should never touch state.

**Concurrency.** Is any read-modify-write on a shared row (balances, stock, counters)
protected? Use optimistic locking with `@Version` and return `409` or retry, or take
pessimistic locks in a stable order (for example ascending id) so opposite operations cannot
deadlock, or use one conditional `UPDATE`. Without one of these, two concurrent requests lose
an update even inside a transaction.

**Numbers.** Is money a `BigDecimal` with explicit scale and rounding, or a `long` of minor
units, wrapped in a value object and stored as `NUMERIC`? `double` cannot represent most
decimal amounts, and the error compounds.

**Absence and failure.** Is `Optional.get()` replaced by `orElseThrow` with a domain
exception (`AccountNotFound`)? Are domain exceptions translated to RFC 9457 `ProblemDetail`
responses in one `@RestControllerAdvice` (404 for unknown resources, 422 for rule violations,
409 for conflicts), with no stack traces or SQL leaking out? `RuntimeException("limit")`
becomes a 500 with no useful body.

**Side effects.** Are HTTP calls and broker sends kept out of the transaction and triggered
after commit (`@TransactionalEventListener`, Modulith event publication registry, outbox)?
See [eda.md](eda.md).

**Proof.** Is there a test that would have caught the bug? For transactional and locking
bugs that means a `@SpringBootTest` with Testcontainers on the real database engine: force a
failure mid-use-case and assert nothing was written; run two transfers concurrently and assert
the totals. H2 hides locking and dialect behaviour. See [testing.md](testing.md).

**Idioms.** Does the code use what the baseline allows and avoid what it does not (no pattern
`switch` on 17, no `synchronized` around blocking I/O on 21–23 virtual threads)? See
[java-language.md](java-language.md).

### Writing the review

Lead with the defect that loses data or money, then the ones that make the service wrong
under load, then structure and style. For each finding give the line, what goes wrong in
production, and the fix. Close with a corrected version of the code when it fits in the
reply: a request record, a controller that delegates, a transactional service that validates
first and locks consistently, the exception advice, and the test that proves the rollback.

## Sources

Topic files cite their own primary sources. The ones this guide leans on directly:
[Spring Framework: declarative transactions](https://docs.spring.io/spring-framework/reference/data-access/transaction/declarative.html),
[Spring Framework: dependency injection](https://docs.spring.io/spring-framework/reference/core/beans/dependencies/factory-collaborators.html),
[Spring Data JPA: locking](https://docs.spring.io/spring-data/jpa/reference/jpa/locking.html),
[Spring Framework: error responses](https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html),
[RFC 9457](https://www.rfc-editor.org/rfc/rfc9457),
[Spring Boot: Testcontainers](https://docs.spring.io/spring-boot/reference/testing/testcontainers.html),
[Spring Boot system requirements](https://docs.spring.io/spring-boot/system-requirements.html).
Pliki w paczce (13)
  • SKILL.md 10 KB
  • architecture-selection.md 11 KB
  • capability-baseline.md 5 KB
  • cqrs-event-sourcing.md 4 KB
  • ddd.md 4 KB
  • eda.md 4 KB
  • hexagonal.md 5 KB
  • java-language.md 7 KB
  • modular-monolith.md 7 KB
  • mvc-layered.md 3 KB
  • observability.md 4 KB
  • spring-conventions.md 8 KB
  • testing.md 7 KB

Wersje

W bazie nie ma innych skilli o nazwie java-spring-patterns.

Migawka bazy z 13.11.2026 · wersja paczki e49e0eb2cce7 (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

  • 90spring-boot
    Pomaga zmieniać aplikacje Java oparte na Spring Boot: MVC, Spring Security, Spring Data i konfigurację zarządzaną przez Spring.
  • 90java-spring-boot-expert
    Pomaga budować aplikacje Spring Boot 3.x, mikroserwisy i reaktywne aplikacje Java, z Spring Data JPA i Spring Security 6.
  • 100spring-boot-java
    Pilnuje zasad i dobrych praktyk w projektach Spring Boot w Javie, od JPA po WebFlux i bezpieczeństwo.
  • 100spring-boot
    Wspiera tworzenie w Spring Boot 4 REST API, warstwy JPA, bezpieczeństwa, testów i usług chmurowych.
  • 100spring-boot-idioms
    Podpowiada wzorce Spring Boot 3.x, czyli wstrzykiwanie przez konstruktor, błędy RFC 7807 i testy warstw.
  • 90java-spring
    Buduje i aktualizuje usługi Java i Spring z jawnymi kontraktami transakcji, współbieżności i wdrożenia.

Uwagi i zgłoszenia

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