Package by Layer for Spring Projects Is Obsolete

I believe Spring applications shouldn’t be structured in a package by layer approach. In my opinion, package by feature makes much more sense.

First of all, let me describe each approach briefly.

“Package by Layer” (“Folder by Type” in the Non-Java World)

This project structure groups source code files into packages/directories based on the architecture layer they belong to:

.
└── net
    └── lkrnac
        └── blog
            ├── Application.java
            ├── persistence
            │   ├── ProjectRepository.java
            │   └── UserRepository.java
            ├── dto
            │   ├── ProjectDto.java
            │   └── UserDto.java
            ├── model
            │   ├── Project.java
            │   └── User.java
            ├── service
            │   ├── ProjectService.java
            │   └── UserService.java
            └── web
                ├── ProjectController.java
                └── UserController.java

“Package by Feature” (“Folder by Feature” in Non-Java World)

This approach, on the other hand, groups together files belonging to a certain feature within the system:

.
└── net
    └── lkrnac
        └── blog
            ├── Application.java
            ├── project
            │   ├── ProjectController.java
            │   ├── ProjectDto.java
            │   ├── Project.java
            │   ├── ProjectRepository.java
            │   └── ProjectService.java
            └── user
                ├── UserController.java
                ├── UserDto.java
                ├── User.java
                ├── UserRepository.java
                └── UserService.java

Trends

This subject interested me for a long time. When I Google “package by layer” vs. “package by feature” or “folder by type” vs. “folder by feature”, there seems to be a growing camp of proponents of the “by feature” structure. I am in this camp, too.

Angular (one of the most prominent Single Page Application frameworks) is promoting such folder structure in their style guide.

Spring Project Structure

As there is plenty of reading about pros and cons of each approach out there, I will focus on the implications for Spring projects.

The traditional structure of laying down Spring CRUD applications (if your back-end application is not using Spring Data REST) is divided into three layers: web/service/persistence. The vast majority of Java/Spring projects I was working on followed this structure.

Coupling

Package by layer most probably originates in the previous century, where layered architectures were used as a decoupling mechanism. In fact, “decoupling” was often the answer when I was challenging package by layer structures. I disagree. To me, package by layer is one of the major reasons behind tight coupling.

When you are writing a signature for classes in a package by layer structured project, what keyword is first? I bet it is public. Does the public access modifier help decoupling? I guess nobody would answer yes to this question.

Then why are developers using public access modifier all over the place? It is exactly because the project is structured in a by-layer fashion. The repository class needs to be public because it needs to be accessed from the service package, and the service needs to be public because it needs to be accessed from the web package. When everything is public, it is very hard to maintain discipline to avoid a big ball of mud.

When using package by feature, package private UserRepository (meaning no access modifier is specified) can’t be used by services other than UserService, because they are in the same package. And if we decide that only UserController should use UserService, we just make it package private, because they share same package. In such a project structure, most of the classes would be package private. Therefore developer should have a very good reason to make the class public.

Scaling

What happens if a project starts to have 10+ classes in the web/service/persistence layer? Developers tend to group classes into sub-packages. But how do they categorize them? From my experience, it is mostly based on features. So we can often find such structure in bigger projects:

.
└── net
    └── lkrnac
        └── blog
            ├── Application.java
            ├── dao
            │   ├── ...other repositories...
            │   ├── ProjectRepository.java
            │   └── user
            │       ├── UserRepository.java
            │       └── UserRoleRepository.java
            ├── dto
            │   ├── ...other DTOs...
            │   ├── ProjectDto.java
            │   └── user
            │       ├── UserDto.java
            │       └── UserRoleDto.java
            ├── model
            │   ├── ...other models...
            │   ├── Project.java
            │   └── user
            │       ├── User.java
            │       └── UserRole.java
            ├── service
            │   ├── ...other services...
            │   ├── ProjectService.java
            │   └── user
            │       ├── UserRoleService.java
            │       └── UserService.java
            └── web
                ├── ...other controllers...
                ├── ProjectController.java
                └── user
                    ├── UserController.java
                    └── UserRoleController.java

Isn’t this obvious madness?

Future Proof-ness

As a bunch of smart people suggest, it might not be a good idea to start greenfield project with a microservices architecture. I agree. So it might be a good idea to prepare your monolith for eventual separation into smaller projects if your application hits major growth.

Imagine extracting microservices from your monolith project. Or splitting the whole project into microservices. I hope everybody understands that no sane microservices architecture is separated by architectural layers. Separation based on features is used. So which project structure will be easier to separate into microservices? The one where any public class can use any other public class from any package (package by layer)? Or one separated into package private buckets (package by feature)? I believe the answer is obvious.

Conclusion

Package by feature is a simple but very powerful mechanism for decoupling. So next time some layer-obsessed developer defends the package by layer project structure as a decoupling mechanism, please correct her/his misunderstanding. I believe dinosaur-ness is the only reason why package by layer still exists nowadays.