Hexagonal / Clean Architecture를 Spring 백엔드에 적용하기

@RestController
@RequiredArgsConstructor
public class OrderController {
    private final OrderService orderService;
 
    @PostMapping("/orders")
    @Transactional
    public OrderResponse create(@RequestBody OrderCreateRequest req) {
        return orderService.create(req);
    }
}
 
@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderRepository orderRepository; // JpaRepository<OrderEntity, Long>
    private final CouponRepository couponRepository;
    private final PaymentClient paymentClient;     // FeignClient
    private final KafkaTemplate<String, String> kafka;
 
    public OrderResponse create(OrderCreateRequest req) {
        OrderEntity order = new OrderEntity();
        order.setUserId(req.getUserId());
        order.setItems(req.getItems().stream().map(i -> {
            OrderItemEntity e = new OrderItemEntity();
            e.setSku(i.getSku());
            e.setQty(i.getQty());
            e.setPrice(i.getPrice());
            return e;
        }).collect(Collectors.toList()));
 
        if (req.getCouponCode() != null) {
            CouponEntity coupon = couponRepository.findByCode(req.getCouponCode())
                .orElseThrow(() -> new RuntimeException("쿠폰 없음"));
            if (coupon.isUsed()) throw new RuntimeException("이미 사용됨");
            int discount = coupon.getAmount();
            int total = order.getItems().stream().mapToInt(i -> i.getPrice() * i.getQty()).sum() - discount;
            if (total < 0) total = 0;
            order.setTotal(total);
            coupon.setUsed(true);
        } else {
            order.setTotal(order.getItems().stream().mapToInt(i -> i.getPrice() * i.getQty()).sum());
        }
 
        orderRepository.save(order);
        paymentClient.charge(order.getId(), order.getTotal());      // 외부 호출
        kafka.send("order-created", String.valueOf(order.getId())); // 외부 호출
 
        OrderResponse res = new OrderResponse();
        res.setOrderId(order.getId());
        res.setTotal(order.getTotal());
        return res;
    }
}

// domain/order/Order.java  — Spring/JPA 의존 없음
public class Order {
    private final OrderId id;
    private final UserId userId;
    private final List<OrderLine> lines;
    private Money total;
    private OrderStatus status;
 
    public static Order create(UserId userId, List<OrderLine> lines, Optional<Coupon> coupon) {
        Money subtotal = lines.stream().map(OrderLine::amount).reduce(Money.ZERO, Money::add);
        Money discounted = coupon.map(c -> c.applyTo(subtotal)).orElse(subtotal);
        if (discounted.isNegative()) discounted = Money.ZERO;
        return new Order(OrderId.next(), userId, lines, discounted, OrderStatus.PLACED);
    }
 
    public Money total() { return total; }
    public OrderId id()  { return id; }
    // ... 상태 전이 메서드
}
 
public class Coupon {
    private final CouponCode code;
    private final Money amount;
    private boolean used;
 
    public Money applyTo(Money subtotal) {
        if (used) throw new CouponAlreadyUsedException(code);
        return subtotal.minus(amount);
    }
    public void markUsed() { this.used = true; }
}

// application/port/in/PlaceOrderUseCase.java
public interface PlaceOrderUseCase {
    OrderPlacedResult place(PlaceOrderCommand command);
}
 
public record PlaceOrderCommand(String userId, List<Line> lines, String couponCode) {
    public record Line(String sku, int qty, long unitPrice) {}
}

// application/port/out/OrderRepositoryPort.java
public interface OrderRepositoryPort {
    void save(Order order);
    Optional<Order> findById(OrderId id);
}
 
// application/port/out/CouponRepositoryPort.java
public interface CouponRepositoryPort {
    Optional<Coupon> findByCode(CouponCode code);
    void save(Coupon coupon);
}
 
// application/port/out/PaymentPort.java
public interface PaymentPort {
    void charge(OrderId id, Money amount);
}
 
// application/port/out/OrderEventPublisher.java
public interface OrderEventPublisher {
    void publishPlaced(OrderId id);
}

@Service
@RequiredArgsConstructor
public class PlaceOrderService implements PlaceOrderUseCase {
    private final OrderRepositoryPort orderRepo;
    private final CouponRepositoryPort couponRepo;
    private final PaymentPort payment;
    private final OrderEventPublisher events;
 
    @Transactional
    @Override
    public OrderPlacedResult place(PlaceOrderCommand cmd) {
        Optional<Coupon> coupon = Optional.ofNullable(cmd.couponCode())
            .map(CouponCode::of).flatMap(couponRepo::findByCode);
 
        Order order = Order.create(UserId.of(cmd.userId()), toLines(cmd.lines()), coupon);
        coupon.ifPresent(c -> { c.markUsed(); couponRepo.save(c); });
        orderRepo.save(order);
 
        // 결제와 이벤트 발행은 도메인 트랜잭션 밖에서 일어나도록 후처리에 위임
        payment.charge(order.id(), order.total());
        events.publishPlaced(order.id());
 
        return new OrderPlacedResult(order.id().value(), order.total().value());
    }
}

@Repository
@RequiredArgsConstructor
class OrderRepositoryAdapter implements OrderRepositoryPort {
    private final OrderJpaRepository jpa;
    private final OrderJpaMapper mapper;
 
    @Override public void save(Order order) { jpa.save(mapper.toJpa(order)); }
    @Override public Optional<Order> findById(OrderId id) {
        return jpa.findById(id.value()).map(mapper::toDomain);
    }
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web:3.3.0'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa:3.3.0'
    runtimeOnly    'com.mysql:mysql-connector-j:8.4.0'
    compileOnly    'org.projectlombok:lombok:1.18.32'
    annotationProcessor 'org.projectlombok:lombok:1.18.32'
    testImplementation 'org.springframework.boot:spring-boot-starter-test:3.3.0'
    testImplementation 'org.testcontainers:junit-jupiter:1.19.8'
    testImplementation 'org.testcontainers:mysql:1.19.8'
}

com.example.hex
├── adapter
│   ├── in.web        (Controller, Web DTO)
│   └── out
│       ├── persistence (JpaEntity, JpaRepository, RepositoryAdapter)
│       └── payment    (FeignClient, PaymentAdapter)
├── application
│   ├── port.in       (UseCase 인터페이스, Command/Result)
│   ├── port.out      (Repository/Payment/Event 포트)
│   └── service       (UseCase 구현)
└── domain
    └── order         (Order, OrderLine, Money, Coupon ...)

@Test
void domain_must_not_depend_on_spring_or_jpa() {
    JavaClasses classes = new ClassFileImporter().importPackages("com.example.hex");
    noClasses().that().resideInAPackage("..domain..")
        .should().dependOnClassesThat().resideInAnyPackage(
            "org.springframework..", "jakarta.persistence..", "org.hibernate.."
        ).check(classes);
}

class OrderTest {
    @Test
    void 쿠폰_적용_후_음수면_0으로_보정된다() {
        var lines = List.of(new OrderLine(Sku.of("A"), 1, Money.of(1000)));
        var coupon = new Coupon(CouponCode.of("C1"), Money.of(5000));
 
        Order order = Order.create(UserId.of("u1"), lines, Optional.of(coupon));
 
        assertThat(order.total()).isEqualTo(Money.ZERO);
    }
 
    @Test
    void 이미_사용된_쿠폰은_적용시_예외() {
        var coupon = new Coupon(CouponCode.of("C1"), Money.of(500));
        coupon.markUsed();
        assertThatThrownBy(() ->
            Order.create(UserId.of("u1"),
                List.of(new OrderLine(Sku.of("A"), 1, Money.of(1000))),
                Optional.of(coupon)))
            .isInstanceOf(CouponAlreadyUsedException.class);
    }
}

class PlaceOrderServiceTest {
    @Test
    void 주문_저장과_쿠폰_사용처리가_함께_일어난다() {
        var orderRepo  = new InMemoryOrderRepo();
        var couponRepo = new InMemoryCouponRepo();
        couponRepo.save(new Coupon(CouponCode.of("C1"), Money.of(2000)));
        var payment = mock(PaymentPort.class);
        var events  = mock(OrderEventPublisher.class);
 
        var sut = new PlaceOrderService(orderRepo, couponRepo, payment, events);
        var result = sut.place(new PlaceOrderCommand("u1",
            List.of(new PlaceOrderCommand.Line("A", 1, 5000)), "C1"));
 
        assertThat(result.total()).isEqualTo(3000L);
        assertThat(couponRepo.findByCode(CouponCode.of("C1")).orElseThrow().isUsed()).isTrue();
        verify(payment).charge(any(), eq(Money.of(3000)));
    }
}