ddd-hexagonal-architecture

このスキルを使う場面

ユーザーが次のことを希望する場合は、いつでもこのスキルを使います。

• ヘキサゴナル（ポートとアダプター）アーキテクチャを使ってアプリケーションを設計する
• ドメイン層を外部システム（データベース、API、メッセージング）から分離する
• ドメインがインターフェースを定義し、アダプターがそれを実装する依存関係逆転を実装する
• ヘキサゴナルアーキテクチャの図やレイヤリングを作成、または実装する
• インメモリーまたはモックのアダプターを使って、ドメインを分離してテストする

このスキルの使い方

ワークフロー

1. エンティティ、値オブジェクト、ドメインサービスを使ってドメインモデルを定義します
2. すべての外部とのやり取りについて、ドメイン層でポート（インターフェース）を定義します
3. ポートの契約を満たすアダプターを実装します（インバウンド：HTTP、メッセージング、アウトバウンド：DB、API）
4. すべての矢印がドメインに向かうように依存関係を接続します

1. ポートの定義（ドメイン層）

// Domain port — no framework dependencies
public interface UserRepository {
    Optional<User> findById(UserId id);
    void save(User user);
}

public interface EventPublisher {
    void publish(DomainEvent event);
}

2. インバウンドアダプター（HTTP コントローラー）

@RestController
@RequestMapping("/api/users")
public class UserController {
    private final CreateUserUseCase createUserUseCase;

    public UserController(CreateUserUseCase createUserUseCase) {
        this.createUserUseCase = createUserUseCase;
    }

    @PostMapping
    public ResponseEntity<UserDto> create(@RequestBody CreateUserRequest request) {
        User user = createUserUseCase.execute(request.toCommand());
        return ResponseEntity.ok(UserDto.from(user));
    }
}

3. アウトバウンドアダプター（データベース）

@Repository
public class JpaUserRepository implements UserRepository {
    private final SpringDataUserRepository springRepo;

    @Override
    public Optional<User> findById(UserId id) {
        return springRepo.findById(id.value()).map(UserEntity::toDomain);
    }

    @Override
    public void save(User user) {
        springRepo.save(UserEntity.fromDomain(user));
    }
}

4. パッケージ構成

com.example.app/
├── domain/
│   ├── model/         # Entities, Value Objects
│   ├── port/          # Repository and service interfaces
│   └── service/       # Domain services
├── application/
│   └── usecase/       # Use cases orchestrating domain logic
├── adapter/
│   ├── inbound/       # HTTP controllers, message consumers
│   └── outbound/      # Database, HTTP clients, message publishers
└── config/            # Dependency injection wiring

ベストプラクティス

• ドメイン層にはフレームワークへの依存を一切持たせず、インメモリーまたはモックのアダプターを使ってテストできるようにします
• 1つのポートに複数のアダプターを用意できます（例：異なるストレージバックエンド、異なるトランスポート）
• COLA または Clean Architecture と組み合わせます。ヘキサゴンは本質的に「1つのドメイン層 + 複数のアダプター」です
• DTO はアダプターとの境界に配置します。ドメインから永続化モデルやトランスポートモデルを公開することはありません

リソース

• Alistair Cockburn による原著： https://alistair.cockburn.us/hexagonal-architecture/
• DDD とヘキサゴナルアーキテクチャ： https://herbertograca.com/2017/11/16/explicit-architecture-01-ddd-hexagonal-onion-clean-cqrs-how-i-put-it-all-together/

キーワード

ヘキサゴナルアーキテクチャ、ポートとアダプター、ドメインの分離、依存関係逆転、インバウンドアダプター、アウトバウンドアダプター、クリーンな境界、DDD