Skip to content
javahacks.dev
Architecture

Layered vs Hexagonal vs Vertical Slice Architecture

Compare layered, hexagonal and vertical slice architecture for Spring Boot services: package layout, testing, coupling and which one suits which team.

5 min read
Summarize in AI
Flat illustration of two options weighed side by side, with the Spring Boot, OpenJDK, Apache Maven and Gradle logos.

All three structures organise a Spring Boot service. They differ in which direction code is allowed to depend and in what a package holds.

Layered

Text
com.example.shop
  web/OrderController
  service/OrderService
  repository/OrderRepository
  model/Order

Each layer talks to the one below. It is easy to learn and Spring Boot's tutorials use it. The cost is that the persistence model tends to climb into the web layer, a service becomes a procedural script over entities, and a change to one feature touches four packages. See the real costs of layered architecture.

Hexagonal

Text
com.example.shop.order
  domain/Order
  application/PlaceOrder      (use case)
  port/out/OrderStore         (interface)
  adapter/in/web/OrderController
  adapter/out/jpa/JpaOrderStore

The domain and use cases depend only on interfaces they define. Adapters implement them. The domain can be exercised in plain unit tests, no Spring context needed, and the database can be swapped. The cost is mapping between domain objects and JPA entities and more files for simple cases. A worked example is in hexagonal architecture with Spring Boot.

Vertical slice

Text
com.example.shop
  placeorder/PlaceOrderController
  placeorder/PlaceOrderHandler
  placeorder/PlaceOrderRequest
  cancelorder/...

A slice holds everything for one use case, and slices avoid sharing abstractions. Each slice may query the database in the way that suits it. Adding a feature means adding a package, and deleting one means deleting a package. The risk is duplicated logic when two slices should share a rule, so shared domain rules still need a home. This is close to package by feature.

Compared

LayeredHexagonalVertical slice
Package byRoleRole inside a moduleFeature
Domain isolationWeakStrongPer slice
BoilerplateLowHighLow to medium
Unit test without SpringHardEasyMixed
Best forCRUD servicesRich domainsFeature teams

Choosing

Pick by what hurts. A CRUD service with little logic gains nothing from ports. A pricing engine with rules that change often gains a lot from isolating them. A team that ships features in parallel benefits from slices because pull requests rarely collide.

They combine. A service can package by feature at the top level and use ports and adapters only inside the modules that have a real domain. Boundaries can be checked with ArchUnit.

What it feels like after a year

The diagrams make the three look equally neat, and the difference appears when you change things. In a layered application a new field on an order touches the controller, the service, the repository and the entity, so each change fans out across four packages, but any developer can predict where the files are. In a hexagonal application the same change touches the domain model and an adapter, and the part you most want to protect, the business rule, can be tested with no framework running. In a vertical slice application you open one folder and edit the handler and its query, and the cost is that two slices may implement the same rule twice until someone extracts it.

Each pays for a different kind of discipline. Layers need you to stop skipping layers, hexagonal needs you to keep the domain free of framework imports, and slices need you to extract shared logic on purpose. In every case, the architecture lasts as long as something checks it, which is why a boundary test belongs in the build, see enforcing module boundaries.

A concrete example of where each wins

Take a pricing rule: a discount applies to returning customers on orders above a threshold. In a layered service the rule ends up in OrderService, mixed with transaction handling and repository calls, and testing it needs a Spring context or a pile of mocks. In a hexagonal service it is a plain class DiscountPolicy in the domain, tested with new DiscountPolicy() and two assertions, and the database is an adapter behind an interface that the domain does not know exists. In a slice, the rule lives in the placeOrder slice next to the query that loads the customer, and the test exercises the whole slice against a real database in a container, which is slower and more realistic.

None of those is wrong. The question is where your complexity lives. If it is in the rules, protect them with a hexagonal core. If it is in many small, unrelated use cases, slices keep each one easy to change. If it is mostly data in and data out, layers are enough and cost the least.

You can mix them

The three are not exclusive. A common and sensible shape is vertical slices at the top level, one package per feature, with a hexagonal core inside the one or two features that have real domain logic, and plain layers inside the CRUD ones. Nobody needs the same ceremony for the settings page and the pricing engine. Decide per feature, write the choice in a short architecture note, and revisit it when a feature changes character.

Signs you picked wrong

Three symptoms say the structure is fighting you. A feature takes a day to add because of plumbing, not logic: you have too many layers for your problem. A bug fix touches six packages: the code that changes together is not together. A unit test needs a database or a web server to check an arithmetic rule: the domain is tangled with infrastructure. Each points to a different fix, and none requires a rewrite, only moving code toward the shape that fits.

A note on team size

A team of three can hold the whole application in their heads, and any of the three structures will work; pick the cheapest one, which is layers. The structure starts to matter when the team passes about eight, and different people own different parts. Vertical slices then let two people work in different folders without collisions, and a hexagonal core lets the person who understands the pricing rules protect them from everyone else. If you expect to grow into that, choose a structure early enough that moving the first features costs a day and not a quarter.

When none of this applies

A small service of a handful of endpoints needs a folder structure, not an architecture. Premature structure is its own debt. Alistair Cockburn's original hexagonal article and Jimmy Bogard's vertical slice writing are the primary sources.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.