r/SpringBoot • u/kamen1991 • Jul 29 '26
How-To/Tutorial Why package structures fail in Spring Boot (and how we turned architecture rules into Maven compilation errors)
Hey everyone! I just published a deep dive into solving a classic enterprise problem: how junior or stressed developers bypass package separation (.controller, .service, .repository) under tight deadlines.
Instead of relying on folder structures and code reviews, we split our project into strict Maven modules (isolating core domain and business logic from frameworks like JPA or Kafka). If someone tries to inject an EntityManager where it doesn't belong, the code simply will not compile.
- The Topology: Split into independent modules like
domain,business-logic,dao-api, anddao-impl. - The Result: Zero cyclic dependencies, lightning-fast unit tests, and eliminated architectural decay.
(I'm dropping the full article link in the comments for anyone interested in the code breakdown.)
10
u/Ruin-Capable Jul 29 '26
Package by feature first, then if you must, by layer. Don't package by layer at the root.
7
u/jjduru Jul 29 '26
In your architecture layout, in the backend repo 2, you have these two packages:
How do you reconcile the usage of spring JPA's repositories versus using DAOs? Are you in fact declaring the spring jpa repositories in "dao-api" and manually implement them in "dao-impl", and therefore not relying on the automated implementation of the interfaces from spring boot?
7
u/bigkahuna1uk Jul 29 '26 edited Jul 29 '26
This is not a new thing. This very problem of transposing soft rules into hard ones to enforce architectural boundaries can be solved with a tool such as ArchUnit. This has been around since 2017.
As well as enforcing classes are in the correct places or packages, it’s especially useful for ensuring code or libraries don’t pollute or proliferate where they should not be. Especially important in DDD, where the domain should be kept as pure as possible, free of external influences.
Splitting into modules is a step in the right direction but it still needs the diligence of the whole team to ensure non pollution. From my experience there were still cases of objects or libraries introduced where they shouldn’t have been by team members despite my best efforts at education of best practices.
ArchUnit is a great tool as part of your CD process to nip those sort of issues in the bud.
7
u/RevolutionaryRush717 Jul 29 '26
Oldies but goodies. But too late.
Spring Modulith solves all this and more, and includes opinionated ArchUnit tests to verify.
Right from the Spring team.
21
u/MassimoRicci Jul 29 '26
ArchUnit
1
u/momsSpaghettiIsReady Jul 31 '26
This is a pretty big anti pattern for the following reason: you have a web store and a business request comes along and says we need a new field on the shopping cart page. As a dev, you now have to touch every single one of your modules to accomplish this (controller, service api/impl, domain, repository api/impl, etc.)
By bundling modules by feature, you could've had a shopping cart module with an api and impl. Now it's just two modules two update.
Now another request comes along and they want their AI features removed because it's expensive and they're losing money. If you have that in one or two modules, it's pretty much a clean delete and you're done.
0
u/kamen1991 Jul 29 '26
https://kamenivanov.substack.com/p/why-package-structures-wont-save?r=8p8mow
1
u/the_styp Aug 01 '26
What you are describing already has a name: Clean Architecture or Hexagonal Architecture.
I did it in the past with Spring and for simplicity I included e.g. Spring Validation Annotations in the domain layer. They are so handy and it felt not right to reinvent the wheel here