DDD Architecture — Hexagonal (Ports & Adapters)

"Allow an application to be equally driven by users, programs, automated tests, or batch scripts, and to be developed and tested in isolation from its final runtime devices and database." — Alistair Cockburn

Workflow

Step 1: Primary Adapter protocol conversion — The REST Controller/CLI receives the request, performs parameter validation, and converts the protocol

Step 2: Inbound port invocation — The Adapter invokes the UseCase interface, triggering use-case orchestration in the application layer

Step 3: Application service orchestration — The Application Service orchestrates the use case and invokes the domain model to execute business logic

Step 4: Domain model execution — The aggregate root/entity executes business logic and outputs a result or domain events

Step 5: Outbound port persistence — The Application Service persists domain state through the Repository interface

Step 6: Secondary Adapter technical implementation — The Adapter provides the technical implementation for DB/MQ/external API integrations

Boundary validation method: All domain-layer unit tests can pass without a database or HTTP → the boundaries are correct.

Rules

1. Dependency rule: The dependency direction must be from outside to inside—Adapter → Application → Domain. The Domain layer must have zero external dependencies.
2. Port granularity rule: Each port must have a single responsibility. Any port containing 10+ methods must be split immediately.
3. Exception translation rule: Technical exceptions (SQLException, TimeoutException) must be caught inside the Adapter and translated into domain exceptions; they must not leak upward.

When to Use

✅ Suitable Scenarios

1. Multi-entry-point systems (REST + CLI + MQ + gRPC): multiple external systems drive the same business logic simultaneously
2. Frequently changing infrastructure (switching DB/MQ/cache): only the Adapter implementation changes, with no modifications to the Domain
3. Maximum testability: Mock the ports to test all domain logic without depending on a database
4. Standardizing microservice architecture: teams > 5 people need consistent architectural conventions across services
5. The team is familiar with abstract design: it can reasonably define port granularity and avoid over-abstraction

Boundary

⚠️ Conditions Required

1. The team understands abstract design: defining port granularity requires domain knowledge and abstraction skills; otherwise, the ports may be defined incorrectly
2. The project is of moderate size: Layered Architecture is simpler for small projects, while Hexagonal Architecture adds the cost of indirection layers
3. A DDD domain model is required: defining Port interfaces presupposes knowledge of domain modeling
4. Good DI container support: frameworks such as Spring and Guice can simplify adapter wiring

❌ Not Applicable (with Alternatives)

1. Single REST API + simple CRUD → use

   ddd-architecture-layered

2. Enterprise MyBatis ecosystem in China → use

   ddd-architecture-cola

3. Strict UseCase + Entity separation is required → use

   ddd-architecture-clean

4. Rapid prototyping / MVP stage → use a traditional three-tier architecture directly, without the overhead of Hexagonal Architecture

Core Principles

Three Abstractions

Driving Side (REST/CLI/gRPC/Test) → Domain Core ← Driven Side (PostgreSQL/RabbitMQ/Redis/Stripe)

interface OrderRepository

Strong Port vs Weak Port

// ❌ Weak — 泄漏 SQL 概念
interface OrderRepository { List<Order> findByQuery(String sql, Map<String, Object> params); }

// ✅ Strong — 纯领域概念
interface OrderRepository {
    Optional<Order> findById(OrderId id);
    List<Order> findByCustomerId(CustomerId customerId);
    void save(Order order);
}

Directory Structure

{project}/
├── {project}-domain/              # 领域核心 + 端口定义（零框架依赖）
│   └── port/{inbound, outbound}/  # ★ 端口接口
├── {project}-application/         # 应用层（UseCase 实现）
├── {project}-adapter/             # 适配器层
│   ├── inbound/                   # ★ 主适配器（REST/CLI/gRPC/MQ）
│   └── outbound/                  # ★ 次适配器（Persistence/Messaging/External）
└── {project}-configuration/       # 配置层（DI 装配）

Development Standards

Layer Responsibilities

Code Standards

// 入站端口（Domain）
public interface CreateOrderUseCase { OrderCreatedResult execute(CreateOrderCommand command); }
// 出站端口（Domain）
public interface OrderRepository { void save(Order order); Optional<Order> findById(OrderId id); }
// 应用服务（实现入站端口，注入出站端口）
@ApplicationService
public class CreateOrderService implements CreateOrderUseCase {
    private final OrderRepository orderRepository;
    @Override @Transactional
    public OrderCreatedResult execute(CreateOrderCommand command) {
        Order order = Order.create(command.getCustomerId());
        orderRepository.save(order);
        return OrderCreatedResult.from(order);
    }
}
// 主适配器（仅协议转换）
@RestController
public class OrderController {
    @PostMapping("/orders")
    public ResponseEntity<CreateOrderResponse> create(@RequestBody @Valid CreateOrderRequest req) {
        var result = createOrderUseCase.execute(req.toCommand());
        return ResponseEntity.status(201).body(CreateOrderResponse.from(result));
    }
}
// 次适配器（技术实现）
@Repository
public class PostgresOrderRepository implements OrderRepository {
    @Override public void save(Order order) { jpaRepo.save(mapper.toPO(order)); }
}

Implementation Steps

Phase 1: 定义端口（1-2 天）→ 入站端口(UseCase) → 出站端口(Repository/Gateway)
Phase 2: 领域模型（2-3 天）→ 聚合根/实体/值对象 → 领域服务 → 领域事件
Phase 3: 应用服务（1-2 天）→ UseCase 实现（注入端口，编排调用）
Phase 4: 适配器（2-4 天） → 主适配器(REST/gRPC/CLI) → 次适配器(DB/MQ/External)
Phase 5: DI 装配 + 测试（1-2 天）→ DI 配置 → 端口 Mock 测试 → 适配器集成测试

Security & Stability

• This skill is a documentation-only architecture guide and does not collect, process, or upload user data.
• All code templates are provided for educational reference. Replace external service URLs, secrets, and credentials with environment-variable-based configuration.
• Port/Adapter isolation ensures that domain logic does not directly depend on HTTP/DB/MQ libraries—the Adapter layer handles all I/O.
• When implementing a Secondary Adapter, always configure connection/read timeouts and implement the circuit breaker pattern for critical paths.

Gotchas (8 Common Pitfalls)

1. Port definition is too broad: Each port should do only one thing. A port containing 10+ methods is considered a “god port” and must be split immediately.
2. The Primary Adapter contains business logic: A Controller may only convert parameters and invoke the UseCase; it must not contain if/else business decisions.
3. The Secondary Adapter forgets exception translation: Technical exceptions (SQLException, TimeoutException) must be translated into domain exceptions inside the Adapter.
4. The Domain layer has framework dependencies: The Domain module must not import Spring/JPA/MyBatis annotations.
5. Inconsistent port naming: Name inbound ports using actions (

   CreateOrderUseCase

   ) and outbound ports using resources (

   OrderRepository

   ).
6. Transactions are placed in the Adapter layer: Transactions are controlled by the application layer; Adapters must not manage them.
7. Over-abstraction: Do not create ports in advance for something that “might be replaced in the future.” Extract a port only when replacement is actually needed.
8. State assumptions first when user requirements are unclear: If the user has not specified the technology stack, entry-point type, or team size, provide an assumed version first and then ask follow-up questions.

FAQ (8 Common Questions)

save

findById

OrderRepository

QueryOrderUseCase

References

Primary Sources

• Hexagonal Architecture — Alistair Cockburn (2005)
• Hexagonal Architecture Explained — Cockburn & Garrido de Paz (2024)
• Domain-Driven Design: The Blue Book — Eric Evans (2003)
• AWS: Hexagonal Architecture Pattern

Navigation

• → Next: Hand off to the

  ddd-domain-designer

  skill — design domain models for Hexagonal Architecture. Install:

  npx skills add full-stack-skills/ddd-skills --skill ddd-domain-designer

  .
• 🔗 Related:

  ddd-testing-strategist

  — Port Mock testing (Install:

  npx skills add full-stack-skills/ddd-skills --skill ddd-testing-strategist

  ) |

  ddd-api-designer

  — Hexagonal API design (Install:

  npx skills add full-stack-skills/ddd-skills --skill ddd-api-designer

  ).

💡 Hexagonal Architecture = Ports + Adapters. Validation method: Run business logic through CLI/unit tests without starting a database or HTTP server → the boundaries are correct.