DDD + Hexagonal Architecture 모범사례

Infrastructure (밖) → Application (중간) → Domain (안)

src/main/java/kr/co/example/
├── payment/          ← BC: 결제
├── refund/           ← BC: 취소/환불
├── inquiry/          ← BC: 조회
└── shared/           ← Shared Kernel (BC 간 공유)

{bc-name}/
├── domain/
│   ├── model/           ← Entity, Value Object
│   ├── event/           ← Domain Event
│   └── port/
│       ├── in/          ← Inbound Port (Use Case 인터페이스)
│       └── out/         ← Outbound Port (외부 의존 인터페이스)
├── application/
│   ├── service/         ← Use Case 구현체
│   └── command/         ← 입력 구조체 (Command / Query)
└── infrastructure/
    └── adapter/
        ├── in/          ← Inbound Adapter (이벤트 리스너, 스케줄러)
        └── out/
            ├── persistence/      ← DB Adapter (QueryDSL, JPA)
            └── external/
                └── {partner}/
                    ├── {Partner}Adapter.java    ← Port 구현
                    └── dto/
                        ├── {Partner}Request.java
                        └── {Partner}Response.java

// domain/port/in/ProcessRefundUseCase.java
public interface ProcessRefundUseCase {
    RefundResult processRefund(ProcessRefundCommand command);
}

// domain/port/out/CancelApiPort.java
public interface CancelApiPort {
    CancelResult cancel(CancelCommand command);
}
 
// domain/port/out/RefundQueryPort.java
public interface RefundQueryPort {
    Optional<OriginalPayment> findOriginalPayment(String transactionNo);
}

// application/service/RefundApplicationService.java
@Service
@RequiredArgsConstructor
@Transactional
public class RefundApplicationService implements ProcessRefundUseCase {
 
    private final RefundQueryPort refundQueryPort;   // ← Port로만 주입
    private final CancelApiPort cancelApiPort;       // ← Port로만 주입
 
    @Override
    public RefundResult processRefund(ProcessRefundCommand command) {
        // 1. 원거래 조회
        OriginalPayment original = refundQueryPort
            .findOriginalPayment(command.transactionNo())
            .orElseThrow(() -> new OriginalPaymentNotFoundException(command.transactionNo()));
 
        // 2. 도메인 로직: cancelType 결정
        CancelType cancelType = original.determineCancelType(LocalDate.now());
 
        // 3. 외부 취소 API 호출 (Port 위임)
        CancelResult result = cancelApiPort.cancel(
            CancelCommand.of(command, original, cancelType)
        );
 
        return RefundResult.from(result);
    }
}

// infrastructure/adapter/out/external/app/MoretaPayCancelAdapter.java
@Component
@RequiredArgsConstructor
public class MoretaPayCancelAdapter implements CancelApiPort {
 
    private final MoretaPayRefundClient client;
 
    @Override
    public CancelResult cancel(CancelCommand command) {
        MoretaPayCancelRequest request = toRequest(command);  // 도메인 → 인프라 변환
        MoretaPayCancelResponse response = client.cancel(request);
        return toResult(response);                            // 인프라 → 도메인 변환
    }
 
    private MoretaPayCancelRequest toRequest(CancelCommand command) { /* ... */ }
    private CancelResult toResult(MoretaPayCancelResponse response) { /* ... */ }
}

// infrastructure/adapter/out/persistence/RefundQueryAdapter.java
@Component
@RequiredArgsConstructor
public class RefundQueryAdapter implements RefundQueryPort {
 
    private final PaymentResultRepository repository;
    private final IntegratedTransactionQueryDsl queryDsl;
 
    @Override
    public Optional<OriginalPayment> findOriginalPayment(String transactionNo) {
        return queryDsl.findByTransactionNo(transactionNo)
            .map(OriginalPayment::from);   // Entity → Domain 변환
    }
}

shared/
├── config/         ← Spring 설정 (@Configuration)
├── exception/      ← 공통 예외
└── util/           ← 유틸리티

// Port를 Mock으로 대체 → 외부 의존 없이 비즈니스 로직만 테스트
@Test
void processRefund_당일이면_CANCEL() {
    given(refundQueryPort.findOriginalPayment("TXN001"))
        .willReturn(Optional.of(originalPaymentOf("2026-06-15")));
 
    RefundResult result = service.processRefund(command("TXN001"));
 
    assertThat(result.cancelType()).isEqualTo(CancelType.CANCEL);
    verify(cancelApiPort).cancel(argThat(c -> c.cancelType() == CancelType.CANCEL));
}

// 간단한 조회 기능에도:
domain/port/out/UserQueryPort.java
application/service/UserApplicationService.java
application/command/FindUserQuery.java
infrastructure/adapter/out/persistence/UserQueryAdapter.java

// 레거시 서비스를 Port Adapter로 감싸기
@Component
public class LegacyRefundAdapter implements CancelApiPort {
    private final LegacyRefundService legacy;  // 기존 서비스

    @Override
    public CancelResult cancel(CancelCommand command) {
        return legacy.processRefund(command.transactionNo(), ...);
    }
}

gateway/
├── refund/                          ← 취소/환불 BC
│   ├── domain/port/out/
│   │   ├── CancelApiPort.java       ← MoretaPay 취소 API 추상화
│   │   └── RefundQueryPort.java     ← 원거래 조회 추상화
│   ├── application/service/
│   │   └── RefundApplicationService.java
│   └── infrastructure/adapter/out/
│       ├── persistence/
│       │   └── RefundQueryAdapter.java
│       └── external/app/
│           ├── MoretaPayCancelAdapter.java
│           └── dto/
│               ├── MoretaPayCancelRequest.java
│               └── MoretaPayCancelResponse.java
└── shared/
    └── config/