معماری Hexagonal، Clean و لایه‌ایHexagonal, Clean & Layered Architecture

Most software-architecture talk arrives buried under hexagons, nested rings, and impressive-sounding names. Here's the good news: underneath all of it there is only one idea. Get that one idea deep in your bones and you can re-derive everything else yourself. Let's build it slowly, from scratch.

Part 0 — words you must know

Before anything else, let's unpack a few terms from the ground up so none of them ever gets dropped on you cold.

• Dependency: when class A imports or uses class B, we say A depends on B. If B changes, A may break. The direction of that arrow — who depends on whom — is the heart of this entire chapter.
• Domain: the heart of your business — the actual rules of your work. Things like "an order must have at least one line" or "only a NEW order can be paid." These have nothing to do with databases or HTTP; they'd still be true if your company ran on pen and paper.
• Infrastructure: all the replaceable technical stuff — database, web framework, message queue, payment service. These are tools, not the business.
• Port: a Java interface that the app itself owns. Think of a wall socket: the app decides its shape, and anything wanting to connect must match that shape.
• Adapter: code that wires a port to the real world — either implementing it or calling it. Like the plug that goes into the socket.
• Coupling: how tangled two pieces of code are. High coupling means you can't change one without touching the other.

Mental model: it's all one rule

Strip away the diagrams and the marketing, and Layered, Hexagonal (Ports & Adapters), and Onion/Clean are three answers to a single question: which direction do source-code dependencies point?

The winning answer, shared by Hexagonal and Clean, is the Dependency Rule:

Source dependencies point inward, toward the domain, and the domain depends on nothing external.

That means your business logic must not import Spring, JPA, Jackson, Kafka, or java.sql. Everything else — ports, adapters, use cases, mappers — is just machinery that enforces this one rule. If you understand why the domain must not know about the database, you can derive the rest yourself.

Why is this worth it? The payoff is concrete:

• You can unit-test business logic with no Spring context and no database — tests that run in milliseconds.
• You can swap Postgres for MongoDB, or REST for gRPC, without touching a single business rule.
• Code that changes for business reasons is physically separated from code that changes for technical reasons.

The cost? Indirection and ceremony — more classes and layers standing in the middle of the path. Senior judgment is knowing exactly when that trade is worth paying.

The three styles compared

Classic Layered / n-tier

The default most teams reach for:

┌─────────────────────────┐
│   Controller / Web      │  presentation
├─────────────────────────┤
│   Service               │  business logic
├─────────────────────────┤
│   Repository / DAO      │  persistence
├─────────────────────────┤
│   Database              │
└─────────────────────────┘
   dependencies point DOWN

Each layer depends on the one below. The fatal flaw is right here: the business layer depends on the persistence layer. Your Service imports Repository, and that Repository is bound to JPA and the DB schema. So your domain now transitively (that is, through one middleman) knows about the database. The chain is: Service → Repository → JPA → schema.

In practice it gets worse: JPA @Entity classes leak upward and become your "domain model." Then your business rules get shaped by Hibernate's needs — public no-arg constructor, mutable setters, lazy-loading proxies, @ManyToOne graphs — rather than by the business itself.

Hexagonal (Ports & Adapters), Alistair Cockburn, 2005

Cockburn's key insight: there is no top or bottom, only inside — the application — and outside — everything else: UI, DB, message brokers, other services. The application talks to the outside world exclusively through ports (interfaces it owns), and the outside world connects via adapters that implement or invoke those ports.

        DRIVING side (primary)              DRIVEN side (secondary)
      actors that USE the app             things the app USES

   REST ─┐                                        ┌─ JPA / Postgres
   CLI  ─┤→ [driving port] → APPLICATION → [driven port] ├─ Kafka
   gRPC ─┘        (inbound)     (domain +    (outbound)  └─ Payment API
                                use cases)

Let me carefully separate the two kinds of ports, because this is exactly where people stumble in interviews:

• Driving / primary / inbound ports: interfaces the application exposes so the outside can "drive" it — e.g. PlaceOrderUseCase. An adapter here (say a REST controller) calls the port. The outside commands the inside.
• Driven / secondary / outbound ports: interfaces the application requires so it can reach the outside itself — e.g. OrderRepository, PaymentGateway. An adapter here (say a JPA repository) implements the port. The inside uses the outside.

Now the critical inversion: the outbound port is defined by the domain but implemented in infrastructure. This is the Dependency Inversion Principle made physical — the arrow between domain and database is flipped so that now the database depends on the domain, not the other way round.

Onion / Clean (Jeffrey Palermo 2008 / Robert Martin 2012)

The same rule, this time drawn as concentric rings:

┌───────────────────────────────────────┐
│  Frameworks & Drivers (web, DB, UI)    │  ← adapters
│  ┌─────────────────────────────────┐   │
│  │  Interface Adapters (controllers,│   │
│  │  presenters, gateways)          │   │
│  │  ┌───────────────────────────┐   │  │
│  │  │  Use Cases (application)   │   │  │
│  │  │  ┌─────────────────────┐   │   │  │
│  │  │  │  Entities (domain)   │   │   │  │
│  │  │  └─────────────────────┘   │   │  │
│  │  └───────────────────────────┘   │  │
│  └─────────────────────────────────┘   │
└───────────────────────────────────────┘
        dependencies point INWARD only

The layers, precisely — a reference table

Keep this table in front of you like a map. For each layer, three things matter: what it contains, what it's allowed to depend on, and what it must not know about at all.

Two new words from the table:

• Value object: an object whose identity is purely its value, not an id. E.g. OrderId — two OrderIds with the same UUID are "the same." Like banknotes: two 1000-unit notes are interchangeable to you.
• Invariant: a rule that must always stay true, like "an order always has at least one line." The domain's job is to make sure it's never violated.

A concrete Spring Boot package layout

There are two common conventions. Package-by-feature with hexagonal sub-packages scales best — instead of every controller in one place and every repository in another, each feature (here orders) gets its own package and is layered inside it:

com.acme.orders
├── domain                        # ZERO framework imports
│   ├── model
│   │   ├── Order.java            # rich aggregate, enforces invariants
│   │   ├── OrderId.java          # value object
│   │   ├── OrderLine.java
│   │   └── OrderStatus.java
│   ├── event
│   │   └── OrderPlaced.java
│   └── port
│       └── out
│           ├── OrderRepository.java   # outbound port (interface)
│           └── PaymentGateway.java    # outbound port (interface)
│
├── application
│   ├── port
│   │   └── in
│   │       └── PlaceOrderUseCase.java # inbound port (interface)
│   └── service
│       └── PlaceOrderService.java     # implements the use case
│
└── adapter
    ├── in
    │   └── web
    │       ├── OrderController.java
    │       ├── PlaceOrderRequest.java # DTO
    │       └── OrderWebMapper.java
    └── out
        └── persistence
            ├── OrderJpaEntity.java
            ├── OrderJpaRepository.java   # Spring Data interface
            ├── OrderPersistenceAdapter.java  # implements OrderRepository
            └── OrderPersistenceMapper.java

One new word: an aggregate is a cluster of domain objects that behaves as one unit and has a "root" (here Order) that is the only door into changing that cluster. To touch the OrderLines you must go through Order.

Port and adapter example, end to end

Now we go from theory to real code. Watch which direction the import arrow points in each file.

Domain: a rich entity and its outbound ports

First, Order itself. Notice it has no annotations — no @Entity, no @Component. The rules live in the constructor and the methods:

package com.acme.orders.domain.model;

import java.util.List;
import java.util.Objects;

// Pure domain. No annotations. Invariants live in the constructor and methods.
public final class Order {
    private final OrderId id;
    private final String customerId;
    private final List<OrderLine> lines;
    private OrderStatus status;

    public Order(OrderId id, String customerId, List<OrderLine> lines) {
        if (lines == null || lines.isEmpty())
            throw new IllegalArgumentException("order must have at least one line");
        this.id = Objects.requireNonNull(id);
        this.customerId = Objects.requireNonNull(customerId);
        this.lines = List.copyOf(lines);   // defensive copy -> immutable
        this.status = OrderStatus.NEW;
    }

    public long totalCents() {
        return lines.stream().mapToLong(OrderLine::subtotalCents).sum();
    }

    // A real business rule, unit-testable with zero infrastructure.
    public void markPaid() {
        if (status != OrderStatus.NEW)
            throw new IllegalStateException("only NEW orders can be paid, was " + status);
        this.status = OrderStatus.PAID;
    }

    public OrderId id()          { return id; }
    public String customerId()   { return customerId; }
    public List<OrderLine> lines(){ return lines; }
    public OrderStatus status()  { return status; }
}

See three things together: the constructor won't let a line-less order be built (an invariant); List.copyOf makes a defensive copy so no one outside can mutate the list (immutable); and markPaid checks the condition before changing state. That's what makes an entity "rich" — it has behavior, not just data.

Now the outbound ports. These are only interfaces, and they're defined in the domain itself:

package com.acme.orders.domain.port.out;

import com.acme.orders.domain.model.Order;
import com.acme.orders.domain.model.OrderId;
import java.util.Optional;

// Outbound port: DEFINED by the domain, IMPLEMENTED by infrastructure.
public interface OrderRepository {
    Order save(Order order);
    Optional<Order> findById(OrderId id);
}

package com.acme.orders.domain.port.out;

import com.acme.orders.domain.model.OrderId;

public interface PaymentGateway {
    // Returns a provider reference; throws PaymentDeclinedException on failure.
    String charge(OrderId orderId, long amountCents);
}

Notice: OrderRepository says "I want to save an Order" — in the domain's language. It doesn't say how, with what SQL, in which table. Those details are the adapter's job.

Application: inbound port + use-case service

The inbound port is the only door through which the outside is allowed to place an order:

package com.acme.orders.application.port.in;

import com.acme.orders.domain.model.OrderId;
import java.util.List;

// Inbound port: the ONLY way the outside is allowed to place an order.
public interface PlaceOrderUseCase {
    OrderId placeOrder(Command command);

    // A dedicated command object -> the web DTO never reaches the domain.
    record Command(String customerId, List<Item> items) {
        public record Item(String sku, int qty, long unitPriceCents) {}
    }
}

That Command is a dedicated input object. Why not just the web DTO? Because if the web DTO came this far, the web framework would have wormed into the core of the app. Command is a boundary between web and business.

And now the service itself, where the orchestration happens:

package com.acme.orders.application.service;

import com.acme.orders.application.port.in.PlaceOrderUseCase;
import com.acme.orders.domain.model.*;
import com.acme.orders.domain.port.out.OrderRepository;
import com.acme.orders.domain.port.out.PaymentGateway;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.util.UUID;

@Service   // The one place Spring is allowed to touch application code.
public class PlaceOrderService implements PlaceOrderUseCase {

    private final OrderRepository orders;      // depends on the PORT, not JPA
    private final PaymentGateway payments;

    public PlaceOrderService(OrderRepository orders, PaymentGateway payments) {
        this.orders = orders;
        this.payments = payments;
    }

    @Override
    @Transactional   // transaction boundary belongs to the use case, not the domain
    public OrderId placeOrder(Command cmd) {
        var lines = cmd.items().stream()
                .map(i -> new OrderLine(i.sku(), i.qty(), i.unitPriceCents()))
                .toList();
        var order = new Order(new OrderId(UUID.randomUUID()), cmd.customerId(), lines);

        payments.charge(order.id(), order.totalCents());  // driven port
        order.markPaid();                                 // domain rule
        return orders.save(order).id();                   // driven port
    }
}

Notice what PlaceOrderService does not import: no @Entity, no JpaRepository, no RestTemplate, no HttpServletRequest. It just orchestrates domain objects through interfaces. That is the whole point. The only trace of Spring here is two annotations: @Service (so Spring builds and injects this class) and @Transactional (the transaction boundary).

Outbound adapter: JPA implements the port

Here's where you see the inversion arrow with your own eyes — this class writes implements OrderRepository, meaning it depends on the domain:

package com.acme.orders.adapter.out.persistence;

import com.acme.orders.domain.model.Order;
import com.acme.orders.domain.model.OrderId;
import com.acme.orders.domain.port.out.OrderRepository;
import org.springframework.stereotype.Component;
import java.util.Optional;

@Component
public class OrderPersistenceAdapter implements OrderRepository {

    private final OrderJpaRepository jpa;
    private final OrderPersistenceMapper mapper;

    public OrderPersistenceAdapter(OrderJpaRepository jpa, OrderPersistenceMapper mapper) {
        this.jpa = jpa;
        this.mapper = mapper;
    }

    @Override
    public Order save(Order order) {
        OrderJpaEntity saved = jpa.save(mapper.toJpa(order)); // domain -> entity
        return mapper.toDomain(saved);                        // entity -> domain
    }

    @Override
    public Optional<Order> findById(OrderId id) {
        return jpa.findById(id.value()).map(mapper::toDomain);
    }
}

And the JPA entity, where all of Hibernate's concerns are imprisoned:

package com.acme.orders.adapter.out.persistence;

import jakarta.persistence.*;
import java.util.UUID;

@Entity                       // Hibernate concerns live ONLY here
@Table(name = "orders")
public class OrderJpaEntity {
    @Id private UUID id;
    private String customerId;
    private String status;
    // ... columns, no-arg ctor, getters/setters that Hibernate demands
    protected OrderJpaEntity() {}
    // ...
}

The OrderJpaRepository itself is a normal interface OrderJpaRepository extends JpaRepository<OrderJpaEntity, UUID>. All of Spring Data lives inside the adapter; the application never sees it. The mapper just translates between the domain shape and the entity shape.

Inbound adapter: REST calls the port

And on the opposite side, the controller, which calls the inbound port:

package com.acme.orders.adapter.in.web;

import com.acme.orders.application.port.in.PlaceOrderUseCase;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.net.URI;

@RestController
@RequestMapping("/orders")
public class OrderController {

    private final PlaceOrderUseCase placeOrder;   // depends on inbound PORT

    public OrderController(PlaceOrderUseCase placeOrder) {
        this.placeOrder = placeOrder;
    }

    @PostMapping
    public ResponseEntity<Void> place(@RequestBody PlaceOrderRequest req) {
        var cmd = OrderWebMapper.toCommand(req);   // DTO -> command
        var id = placeOrder.placeOrder(cmd);
        return ResponseEntity.created(URI.create("/orders/" + id.value())).build();
    }
}

Now see the whole flow at a glance:

HTTP → controller → inbound port → use-case service → domain + outbound ports → adapters → DB/payment.

Dependencies at every seam point inward. Every import arrow points toward the core. That's it.

Testability: the concrete payoff

// Pure unit test — no Spring, no DB, milliseconds to run.
class PlaceOrderServiceTest {
    @Test
    void chargesThenSaves() {
        var repo = mock(OrderRepository.class);
        var pay  = mock(PaymentGateway.class);
        when(repo.save(any())).thenAnswer(inv -> inv.getArgument(0));

        var service = new PlaceOrderService(repo, pay);
        var cmd = new PlaceOrderUseCase.Command("cust-1",
                List.of(new PlaceOrderUseCase.Command.Item("SKU", 2, 500)));

        service.placeOrder(cmd);

        verify(pay).charge(any(), eq(1000L));  // 2 * 500
        verify(repo).save(argThat(o -> o.status() == OrderStatus.PAID));
    }
}

No @SpringBootTest, no Testcontainers, no HTTP. One word: a mock is a fake stand-in for an interface whose behavior you dictate and which you can later ask "was this method called?". Because the service depends only on interfaces you own, you substitute fakes trivially.

Adapters get their own narrow tests: @DataJpaTest (with Testcontainers — a real database in a container) for the persistence adapter, and @WebMvcTest for the controller. Domain entities get plain JUnit. Each test targets exactly one concern and runs fast — a direct consequence of the architecture, not an add-on.

Enforcing the rule with ArchUnit

ArchUnit is a library that lets you write tests about the structure of your code — for example, "no class in the domain package may depend on Spring." These tests run in the same CI, and if someone breaks the rule, the build goes red:

@AnalyzeClasses(packages = "com.acme.orders")
class ArchitectureTest {

    @ArchTest
    static final ArchRule domain_depends_on_nothing_external =
        classes().that().resideInAPackage("..domain..")
            .should().onlyDependOnClassesThat()
            .resideInAnyPackage("..domain..", "java..", "javax.validation..");

    @ArchTest
    static final ArchRule no_framework_in_domain =
        noClasses().that().resideInAPackage("..domain..")
            .should().dependOnClassesThat()
            .resideInAnyPackage("org.springframework..", "jakarta.persistence..");
}

This turns the architecture from a wiki page (that nobody reads) into a build gate. Without it, the first tired engineer under deadline pressure will @Autowired a repository into the domain and nobody will notice for six months — until writing one simple test suddenly requires spinning up all of Spring.

Common pitfalls & gotchas

When it's over-engineering

Be honest about this — it's precisely the thing that separates a senior engineer from everyone else. Full hexagonal is not free: more classes, more mappers, more indirection, slower onboarding for a new team member.

It pays off when: the domain is genuinely complex (rich invariants, many rules); the app is long-lived; you have multiple driving/driven adapters (REST + Kafka + batch, or Postgres today + something else later); or testability of business rules is a hard requirement.

It's over-engineering when: the service is essentially CRUD or a thin data pipe; the team is small and the app short-lived; there is no real domain logic (validation + persistence is not a domain). For those, a disciplined layered app — even sharing entities — ships faster and is perfectly maintainable.

Interview Questions

var order = new Order(new OrderId(UUID.randomUUID()), "c1",
        List.of(new OrderLine("SKU", 1, 100)));
order.markPaid();
order.markPaid();