Spring Boot

Pathrule2 Rules • 3 Memories • 1 Skill

Spring Boot applications stay maintainable when package boundaries, configuration binding, validation, transactions, exception handling, and tests follow the framework's runtime model. This bundle defines thin web adapters, service-owned transactions, validated ConfigurationProperties, dependency direction, and focused test slices. Unlike Django, it captures current Spring Boot and Java conventions rather than Python and Django architecture.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

review-spring-boot-service

src/

main/

java/

Keep web adapters thin and validate at the boundary

Put transaction boundaries on application services

Package boundaries follow use cases and dependency direction

resources/

Configuration is a validated typed contract

test/

java/

Choose the smallest Spring test that proves the behavior

Rules

Keep web adapters thin and validate at the boundary/src/main/javahighstrictControllers translate HTTP, validate request contracts, call one application service, and map the result without owning business flow.

1	Controllers translate HTTP, validate request contracts, call one application service, and map the result without owning business flow. Business rules in controllers are duplicated across jobs, messaging, tests, and later transports, while persistence entities exposed directly leak lazy state and internal fields. Enforce this boundary in /src/main/java so invalid work stops before it reaches another subsystem or creates an externally visible side effect.
2
3	- Use request and response DTOs with Jakarta validation constraints and map them explicitly to application commands and results.
4	- Keep authentication-derived identity, tenant, and authorization context server-owned instead of accepting them from request fields.
5	- Centralize expected exception-to-response mapping with stable public error codes and no stack or internal class leakage.
6	- Return persistence entities only through deliberate read models that control fields, serialization, and fetch behavior.
7
8	Verification: Test invalid input, unauthorized tenant fields, domain conflicts, missing resources, and unexpected failures through the web slice; confirm no business write begins before validation.

Put transaction boundaries on application services/src/main/javahighstrictA service method owns one business transaction and separates database commit from asynchronous or remote effects.

1	A service method owns one business transaction and separates database commit from asynchronous or remote effects. Transactions spread across controllers, private helper assumptions, remote calls, and async work create long locks, partial effects, and rollback expectations the runtime cannot honor. Enforce this boundary in /src/main/java so invalid work stops before it reaches another subsystem or creates an externally visible side effect.
2
3	- Start the transaction at a public application-service operation that expresses one business command.
4	- Keep network calls and slow external work outside open database transactions; use an outbox or durable job when an effect must follow commit.
5	- Define read-only and isolation needs deliberately for queries whose correctness depends on concurrent changes.
6	- Make idempotency and retry behavior explicit for commands that can be invoked again after timeouts.
7
8	Verification: Inject failure before commit, after commit, during outbox publication, and on duplicate command delivery; verify database and external effects converge exactly once.

Memories

Configuration is a validated typed contract/src/main/resourcesScattered string-based property reads hide required values, accepted ranges, grouping, and override behavior until a deep code path runs.

1	Scattered string-based property reads hide required values, accepted ranges, grouping, and override behavior until a deep code path runs. Bind each configuration namespace to a typed ConfigurationProperties object and validate required values and constraints during startup.
2
3	Keep safe defaults close to the type and secrets in external providers or environment inputs rather than committed resources. Document override sources and avoid relying on incidental property precedence for security-sensitive behavior. Test representative production configuration and fail startup with an actionable field-level message when the contract is invalid. Keep the decision explicit at /src/main/resources; moving it into an incidental caller makes behavior depend on which route happened to execute first.
4
5	See /src/test/java for configuration fixtures and the secrets pattern for credential handling. That related boundary consumes this decision and carries the evidence that proves it still holds.

Package boundaries follow use cases and dependency direction/src/main/javaA single controllers, services, and repositories layout becomes a shared bucket where every feature can reach every implementation detail.

1	A single controllers, services, and repositories layout becomes a shared bucket where every feature can reach every implementation detail. Group cohesive domain or feature code and keep web, persistence, messaging, and provider adapters pointing toward application and domain contracts.
2
3	Expose intentional interfaces between features instead of importing another feature's repository or entity. Keep framework annotations at adapter and wiring boundaries where practical so domain decisions can be tested without a container. Place the application entry point above the packages it should scan and make additional scanning explicit. Keep the decision explicit at /src/main/java; moving it into an incidental caller makes behavior depend on which route happened to execute first.
4
5	See /src/test/java for boundary tests and /src/main/resources for module configuration. That related boundary consumes this decision and carries the evidence that proves it still holds.

Choose the smallest Spring test that proves the behavior/src/test/javaA full application context is valuable for wiring and end-to-end behavior, but it is slow and can hide that a unit or focused slice lacks an explicit dependency.

1	A full application context is valuable for wiring and end-to-end behavior, but it is slow and can hide that a unit or focused slice lacks an explicit dependency. Use plain unit tests for domain logic, focused web or data slices for adapter contracts, and SpringBootTest only when Boot wiring, externalized configuration, or the real application context is the subject.
2
3	Keep slice-specific configuration local and avoid importing the entire application through a convenient test helper. Remember that a transactional test using a real server port does not share the server thread's transaction and rollback behavior. Use production-like database and dependency integrations for behavior an embedded substitute cannot represent. Keep the decision explicit at /src/test/java; moving it into an incidental caller makes behavior depend on which route happened to execute first.
4
5	See /src/main/java for the transaction boundary and the Spring Boot review skill for test selection. That related boundary consumes this decision and carries the evidence that proves it still holds.

Skills

review-spring-boot-service/rootReview a Spring Boot service for web contracts, validation, transactions, configuration, dependency direction, and test scope.

1	---
2	name: review-spring-boot-service
3	description: Review a Spring Boot service for web contracts, validation, transactions, configuration, dependency direction, and test scope.
4	---
5
6	# Review Spring Boot Service
7
8	Run this procedure whenever the governed surface changes or its operational evidence becomes stale.
9
10	1. Trace representative requests from DTO validation and authorization through application service, transaction, persistence, external effects, exception mapping, and response models.
11	2. Inspect ConfigurationProperties binding, startup validation, override sources, secret handling, profile behavior, and production configuration fixtures.
12	3. Review package dependencies for feature leakage, direct repository access across boundaries, framework types in domain decisions, and implicit component scanning.
13	4. Map domain, web, data, configuration, wiring, and integration risks to the smallest useful tests, then run duplicate, rollback, concurrency, and real-server cases where behavior differs.
14
15	Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory.

Why this pattern

Agents put business logic and transactions in controllers, scatter Value injection, expose persistence entities directly, or use full-context tests for every behavior.

Built for Java and Kotlin teams building HTTP services and data applications with Spring Boot.

Keeps your assistant from:

Controllers owning business transactions and persistence logic
Invalid configuration discovered only after traffic reaches a feature
Full application contexts hiding missing focused tests and slow feedback

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25