spring-boot-4-conventions

Spring Framework 7 / Spring Boot 4 conventions

Java 25 + Spring Framework 7 + Spring Boot 4. Prefer the most modern idiom unless an ADR explains otherwise.

Defaults to apply

Package layout — by feature, not by layer

Top-level packages are bounded contexts / features, not technical layers. Inside a feature, split by visibility (api published, private impl hidden). For the private impl sub-packages, apply the following rule:

• One class of a given type (single entity, single service, etc.) — keep it directly in the feature package (no sub-package).
• Multiple classes of the same type — use a typed sub-package within the feature:
  • model/ — JPA entities
  • repository/ — Spring Data repositories
  • service/ — service classes / implementations
  • service/ — service implementations
• Inside api/ — keep the controller (or service interface) at the api/ level; put all request/response DTO records in an api/dto/ sub-package.

All classes in the feature's private sub-packages (model, repository, service, internal) must be public (cross-package visibility is required when code spans multiple sub-packages). Cross-feature access is still forbidden and enforced by ArchUnit — public here means "visible within this feature", not "part of the published API".

The api/ sub-package is the only published surface. Other features depend only on <feature>.api.

com.example.checkout
├── giftcard/                    # feature/domain — one package per bounded context
│   ├── api/                     # published surface: controller, service interfaces, events
│   │   ├── GiftCardController.java
│   │   ├── GiftCardRedemptionService.java
│   │   ├── GiftCardRedeemed.java
│   │   ├── dto/                 # request/response DTOs always in api/dto/
│   │   │   ├── RedeemCommand.java
│   │   │   └── GiftCardRedemptionResponse.java
│   │   └── exception/           # domain exceptions thrown by this feature's services
│   │       └── InsufficientBalanceException.java
│   ├── model/                   # entities (multiple → typed sub-package)
│   │   ├── GiftCardEntity.java
│   │   └── GiftCardTransactionEntity.java
│   ├── repository/              # repositories (multiple → typed sub-package)
│   │   ├── GiftCardRepository.java
│   │   └── GiftCardTransactionRepository.java
│   └── service/                 # service implementations (multiple → typed sub-package)
│       └── GiftCardRedemptionServiceImpl.java
├── order/                       # another feature
│   ├── api/
│   │   └── dto/                 # DTOs always in api/dto/
│   │       └── OrderSummaryResponse.java
│   └── service/                 # single service impl — sub-package still used for consistency
│       └── OrderService.java
└── shared/                      # cross-cutting: error envelope, security config, time
    └── exception/               # GlobalExceptionHandler (@RestControllerAdvice)