[초안] 커머스 Spring 서비스에 Clean/Hexagonal Architecture를 실용적으로 적용하기

Controller → Service → Repository(JPA) → Entity(@Entity)

[adapter-in]  HTTP Controller, Kafka Listener
       │
       ▼
[application] UseCase 인터페이스 ← 구현 ApplicationService
       │  ↓ 사용         ↑ 호출
       ▼
[domain]      Order, OrderLine, OrderPolicy (POJO)
       ▲
       │ 구현
[adapter-out] OrderJpaRepository, KafkaPublisher, TossPaymentClient
       │ implements
[application] OrderRepository(port), PaymentPort

com.example.order
├── domain                  // POJO, 프레임워크 의존 0
│   ├── Order.java
│   ├── OrderLine.java
│   ├── OrderStatus.java
│   └── OrderPricingPolicy.java
├── application
│   ├── port.in
│   │   └── PlaceOrderUseCase.java
│   ├── port.out
│   │   ├── OrderRepository.java
│   │   ├── PaymentPort.java
│   │   └── StoreInventoryPort.java
│   └── service
│       └── PlaceOrderService.java   // @Service, @Transactional
└── adapter
    ├── in.web
    │   └── OrderController.java
    └── out
        ├── persistence
        │   ├── OrderJpaEntity.java
        │   ├── OrderJpaRepository.java
        │   └── OrderPersistenceAdapter.java   // implements OrderRepository
        ├── payment
        │   └── TossPaymentAdapter.java        // implements PaymentPort
        └── inventory
            └── StoreInventoryHttpAdapter.java

@Test
void domainShouldNotDependOnSpringOrJpa() {
    noClasses().that().resideInAPackage("..order.domain..")
        .should().dependOnClassesThat()
        .resideInAnyPackage("org.springframework..", "jakarta.persistence..", "..adapter..")
        .check(importedClasses);
}

@Service
@RequiredArgsConstructor
public class OrderService {
 
    private final OrderJpaRepository orderRepo;
    private final MenuJpaRepository menuRepo;
    private final RestTemplate paymentClient;
    private final KafkaTemplate<String, String> kafka;
 
    @Transactional
    public Long placeOrder(PlaceOrderRequest req) {
        var menus = menuRepo.findAllById(req.menuIds());
        long total = 0;
        for (var m : menus) {
            if (m.getStoreId() != req.storeId()) {
                throw new IllegalArgumentException("매장 불일치");
            }
            if (req.couponCode() != null && m.isCouponApplicable()) {
                total += m.getPrice() * 9 / 10;
            } else {
                total += m.getPrice();
            }
        }
 
        var pgRes = paymentClient.postForObject(
            "https://pg.example.com/pay",
            Map.of("amount", total, "card", req.cardToken()),
            Map.class);
 
        if (!"OK".equals(pgRes.get("result"))) {
            throw new IllegalStateException("결제 실패");
        }
 
        var entity = new OrderJpaEntity(req.storeId(), total, "PAID", LocalDateTime.now());
        orderRepo.save(entity);
 
        kafka.send("order.created", String.valueOf(entity.getId()));
        return entity.getId();
    }
}

// domain/Order.java
public class Order {
    private final Long id;
    private final Long storeId;
    private final List<OrderLine> lines;
    private OrderStatus status;
    private Money totalAmount;
 
    public static Order place(Long storeId, List<OrderLine> lines, CouponPolicy coupon) {
        if (lines.isEmpty()) throw new DomainException("빈 주문");
        Money total = lines.stream()
            .map(line -> coupon.applyTo(line))
            .reduce(Money.ZERO, Money::plus);
        return new Order(null, storeId, lines, OrderStatus.PENDING, total);
    }
 
    public void markPaid() {
        if (status != OrderStatus.PENDING) throw new DomainException("이미 처리됨");
        this.status = OrderStatus.PAID;
    }
}

// application/service/PlaceOrderService.java
@Service
@RequiredArgsConstructor
public class PlaceOrderService implements PlaceOrderUseCase {
 
    private final OrderRepository orderRepository;     // port.out
    private final PaymentPort paymentPort;             // port.out
    private final StoreInventoryPort inventoryPort;    // port.out
    private final OrderEventPublisher eventPublisher;  // port.out
    private final CouponPolicyFactory couponFactory;
 
    @Override
    @Transactional
    public OrderId place(PlaceOrderCommand cmd) {
        inventoryPort.reserve(cmd.storeId(), cmd.lineItems());
 
        var coupon = couponFactory.of(cmd.couponCode());
        var order  = Order.place(cmd.storeId(), cmd.toLines(), coupon);
        var saved  = orderRepository.save(order);
 
        var paid = paymentPort.pay(saved.id(), saved.totalAmount(), cmd.cardToken());
        if (!paid.isSuccess()) {
            throw new PaymentFailedException(paid.reason());
        }
        saved.markPaid();
        orderRepository.save(saved);
 
        eventPublisher.publishCreated(saved);
        return saved.id();
    }
}

// adapter.out.payment/TossPaymentAdapter.java
@Component
@RequiredArgsConstructor
class TossPaymentAdapter implements PaymentPort {
    private final TossClient tossClient;
 
    @Override
    public PaymentResult pay(OrderId orderId, Money amount, String cardToken) {
        var res = tossClient.charge(orderId.value(), amount.toLong(), cardToken);
        return res.isApproved()
            ? PaymentResult.success(res.transactionId())
            : PaymentResult.fail(res.reasonCode());
    }
}

class FakeOrderRepository implements OrderRepository {
    private final Map<Long, Order> store = new HashMap<>();
    private final AtomicLong seq = new AtomicLong();
    public Order save(Order order) { /* id 발급 후 저장 */ }
    public Optional<Order> findById(OrderId id) { /* */ }
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
    runtimeOnly("com.mysql:mysql-connector-j")
 
    testImplementation("org.springframework.boot:spring-boot-starter-test")
    testImplementation("com.tngtech.archunit:archunit-junit5:1.3.0")
    testImplementation("org.testcontainers:mysql:1.20.1")
    testImplementation("org.wiremock:wiremock-standalone:3.5.4")
}