Package by feature vs by layer

Written Explanation

Package by layer

A layer is a technical role. Package by layer creates one package per role:

shop/
  controller/  OrderController  UserController
  service/     OrderService     UserService
  repository/  OrderRepository  UserRepository

This feels tidy: all repositories sit together. Many tutorials start this way. But look at what one change needs. Adding a discount rule to orders touches OrderController, OrderService and OrderRepository: three files in three packages. And the package names (controller, service, repository) say nothing about what the application is for.

Package by feature

A feature is something the business cares about: orders, users, accounts. Package by feature creates one package per feature and puts everything for it inside:

shop/
  order/  OrderController  OrderService  OrderRepository
  user/   UserController   UserService   UserRepository

Open the folder order/ and you see all that orders need. Deleting a feature means deleting a folder. A new teammate can find the order code by name. Package names now describe the business, which is why this is also called "screaming architecture" by some authors: the structure shouts what the app does. (We cite no source for that nickname; treat it as a side remark.)

The key difference: package-private

Package-private only helps when the classes that should share a secret are in the same package. Compare the same two classes in both layouts.

In a layered layout, OrderService (package shop.service) uses OrderRepository (package shop.repository). They are in different packages, so OrderRepository must be public. The compiler leaves no choice:

error: OrderRepository is not public in shop.repository; cannot be accessed from outside package

Once it is public, anyone can use it, including a controller that skips the service and its business rules. In our test, a Main in a third package called new OrderRepository().find(7) directly and it worked.

In a feature layout, OrderService and OrderRepository are both in shop.order. The repository can be package-private. Code outside the package can use OrderService, the public front desk, and nothing else:

error: OrderRepository is not public in shop.order; cannot be accessed from outside package

The rule of thumb for this course: layer packages force many classes to be public so the layers can reach each other, while feature packages keep a feature's helpers private to it.

What crosses a boundary

Features are not islands. An account needs to know its customer, and sends notifications. The imports show these links:

package bank.account;

import bank.customer.Customer;
import bank.notification.Notifier;

Each import of another feature's class is a dependency, and each depends on a public class. Design the packages so that:

• the public surface of every feature is small (a service class and a few types others must see, such as Customer);
• dependencies point one way where possible: account uses customer and notification, but customer does not use account. Circular dependencies between packages make them hard to separate later.

If you need a class in two features, ask whether it belongs to one of them (the more fundamental one), or whether a third small package should hold it.

Is layering wrong?

No. Layers are still a real idea: controllers should not contain business rules, and services should not write SQL. The question is only how you group files into packages. You can keep layering inside a feature: order may hold a controller, a service and a repository, each doing its own layer's job. Both styles are used in industry. For small and medium applications, feature packages are a strong default. Very large systems often combine them: top-level packages by feature, sub-packages by layer.

The Spring Modulith documentation (a framework you may meet later) describes a similar idea: it treats each direct sub-package of an application's main package as a module, and says that in a simple module, package-private types are hidden from other modules, while public types form its API. The same reasoning drives this lesson.

Honest trade-offs

Feature packages are not free:

• Deciding where a class belongs takes thought, whereas "it is a service" is automatic.
• Features may need each other, so you must watch dependencies.
• Generic code used everywhere (utilities, shared types) needs its own home. Do not let a package called common or util become a dumping ground.

Justifying the choice

When the lab asks for two sentences, say what it gives you and why it matters. For example: "Feature packages keep everything for one business capability together, so a change or a removal touches one folder. They also let helpers be package-private, which keeps the public surface of each feature small."