---
name: springboot-best-practices
description: Write or review Java and Spring code using records, var, streams, functional interfaces, sealed types, exhaustive switches, domain validators, modern APIs, collection ownership, concurrency, transactions, persistence, tests, and existing architecture. Apply concrete rules with version bounds and justified exceptions.
---

# Java and Spring rules for generation and review

Read [project context](../java-spring-updates/references/project-context.md), then select the rules whose trigger appears in the task or diff. Load recent API changes through `java-spring-updates` when dependencies, imports, or configuration differ from familiar examples.

| Trigger | Rule | Priority |
| --- | --- | --- |
| DTOs, value objects, or non-entity domain data | [Use records by default](rules/java-record-data-models.md) | High |
| Local declarations, generics, or numeric inference | [Prefer clear local type inference](rules/java-local-var.md) | Medium |
| Filtering, mapping, aggregation, or strategy lambdas | [Use declarative transformations](rules/java-declarative-transformations.md) | Medium |
| Closed domain alternatives or instanceof chains | [Seal variants and exhaust switches](rules/java-sealed-exhaustive-switch.md) | High |
| Entity creation, state changes, cross-field rules, or request validation | [Keep domain validation unavoidable](rules/domain-validation-boundaries.md) | High |
| Collection-returning APIs, record components, or toList conversions | [Preserve collection ownership](rules/java-collection-contracts.md) | High |
| Handwritten string/file/batching utilities or newer syntax | [Select stable modern APIs](rules/java-modern-api-selection.md), then the [Java 11–25 feature index](references/java-11-25.md) | Medium |
| Virtual threads or increased concurrent external requests | [Bound constrained resources](rules/concurrency-resource-limits.md) | High |
| Catching InterruptedException or retrying after cancellation | [Preserve interruption](rules/java-preserve-interruption.md) | High |
| New interfaces, factories, or generic base classes | [Require a purpose for abstractions](rules/design-purposeful-abstraction.md) | Medium |
| Self-invocation or a new transaction/propagation boundary | [Make interception real](rules/tx-proxy-boundary.md) | High |
| N+1 query evidence, a fetch join, or pagination changes | [Measure the fetch plan](rules/persistence-fetch-plan.md) | High |
| New or modified regression tests | [Assert observable behavior](rules/tests-observable-behavior.md) | Medium |
| Moving classes, adding dependencies, or creating a component | [Follow existing boundaries](rules/architecture-existing-boundaries.md) | High |

For each applicable rule:

1. Check its version/runtime conditions and exceptions against the repository. Prefer records for value-like data, clear `var` locals, declarative transformations, and exhaustive closed-domain modeling in new or changed code. State a concrete exception when retaining another form; avoid unrelated whole-repository rewrites.
2. During generation, choose a correction that fits the intended behavior and existing boundaries. During review, identify the affected code and a concrete consequence before raising a finding.
3. Run the rule's verification and the repository's required checks through `spring-verify`.

Report findings with the rule ID, file/line, consequence, and evidence. Treat advisory design judgments as review guidance; only repository-adopted executable policy can turn them into mandatory build failures. A pattern match alone is insufficient evidence of a defect.