10주간의 항해가 끝이 났다. 그 결과, 나는... 블랙 배지를 받았다.

인증된 무언가는 없지만, 스스로 정말 몰입했다고 자부할 수 있는 결과라서 의미 있고 즐거운 마무리였다.

📅 일주일 시간표는 이렇게 흘러간다

항해플러스는 단순히 과제만 주는 프로그램이 아니다.

문제를 이해하고, 팀과 소통하며, 구조적으로 해결해나가는 주간 사이클이 있다.

내가 경험한 주간 루틴은 아래와 같았다.

• 토요일: 발제 + 팀모임 + Q&A

  → 한 주의 주제와 과제를 처음 마주하는 시간. 발제를 기반으로 토론하고 방향을 잡는다.

• 일요일: 쉼

  → 머리를 식히는 리셋의 시간.

• 월요일: 공개 Q&A

  → 발제를 맡은 코치님과의 실시간 질의응답. 놓쳤던 개념을 다시 짚고 정리할 수 있는 기회.

• 화요일: 팀 멘토링

  → 개인적으로 가장 값졌던 시간. 질문을 우선순위대로 정리해서 가져가면, 전반적인 설계부터 디테일까지 피드백을 받을 수 있다.

  같은 코치님께 꾸준히 받는 게 훨씬 효율적이었다. 맥락 공유가 되니까 피드백의 깊이가 달라진다.

• 수~목: 집중 코딩

  → 이제 본격적인 과제 수행. 기획부터 테스트까지 몰입하는 시간이다.

• 금: 오전 10시 까지 과제 제출

밤샘, 그리고 ‘버티는 힘’

솔직히 말하면, 거의 매주 목요일은 밤을 샜다. 과제 양 때문만은 아니다. 눈에 거슬리는 걸 그냥 두지 못하는 성격 때문이었다. 리팩토링, 테스트 코드, 설계의 구조적 정당성까지 내가 납득이 안 되면 끝낼 수가 없었다. 그래서 항상 계획보다 시간이 더 걸렸고, 결과적으로 더 몰입하게 됐다. 그러다 보면 종종 “이거 왜 이렇게까지 해야 해?”라는 회의감도 왔지만, 결국 이 과정을 거쳤기에 그 주차의 개념이 정말 내 것이 되었다고 느낀다.

항해에서 얻은 것

처음 항해를 선택한 이유는 단순했다.

혼자 공부하는 것보다, 목표와 경쟁이 있는 환경에서 더 성장할 수 있다고 믿었기 때문이다.

그리고 실제로 그랬다.

항해는 ‘어떻게 구현할 것인가’가 아니라 ‘왜 그렇게 설계해야 하는가’를 고민하게 만든다.

• Redis 락을 왜 썼는가?
• Kafka DLQ를 어떻게 설계했는가?
• 이 구조가 운영 환경에서도 안정적으로 돌아갈 수 있는가?

이런 질문에 “그게 맞는 이유”를 설명할 수 있을 정도로 깊이 고민하는 훈련을 시켰다.

내가 생각하는 진짜 개발자란, 결국 ‘말할 수 있는 사람’이라고 믿는데,

항해는 그 기반을 만들어준 과정이었다.

WIL 쓰는 습관 – 성장을 기록하는 법

항해에서는 매주 WIL(What I Learned)을 쓰도록 권장했다.

처음엔 그냥 해야 하니까 썼는데, 점점 이게 나만의 성장 기록이 되어갔다.

• 어떤 개념이 헷갈렸는지
• 이번 주 설계에서 왜 그렇게 했는지
• 지금 다시 하면 어떻게 바꿀 수 있을지

단순한 기술 요약이 아니라, 스스로에게 질문을 던지는 시간이었고,

그게 항해를 10주 동안 의미 있게 이어갈 수 있었던 큰 동기가 됐다.

막막하거나 자신이 없을 때, 지난주 WIL을 다시 읽어보면

“그래도 여기까지 왔구나” 하는 힘이 생겼고,

돌아보니 이 습관이 개발자로서 사고력을 키워준 밑바탕이 된 것 같다.

• 회고상을 받았다 !!!!

함께 항해한 사람들 덕분에

혼자였다면 절대 못 했을 고민과 시도들을,

팀원들과 함께였기에 끝까지 밀고 나갈 수 있었다.

특히 우리 팀은 기술뿐만 아니라 태도 면에서도 서로에게 긍정적인 자극이 되었다.

그리고 코치님들의 멘토링은 정말 큰 힘이 됐다.

단순한 기능 구현을 넘어,

실제 서비스에서 어떤 기준으로 판단하고, 어떻게 구조를 설계해야 하는지

날카롭고 현실적인 조언을 아낌없이 해주셨다.

항해를 시작할 때는 “커뮤니티? 네트워킹?” 별 생각 없었는데,

지금은 이 연결이야말로 가장 큰 자산이라고 느낀다.

✨ 마무리하며

누군가가 “항해플러스 어땠어?”라고 묻는다면

나는 이렇게 답할 것 같다.

“성장하고 싶어요? 그냥 하세요”

항해플러스과정에 대해 문의사항이나 과정 진행 중에 도움이 필요하다면 언제든 연락주셔도 좋습니다. 추가로 K71MWE 코드를 입력하면 20만원 할인이 가능하다

이번 주의 핵심 목표는 도메인 이벤트를 기점으로 Outbox + Kafka 기반의 비동기 전파 아키텍처를 직접 설계하고,

그 흐름을 통해 도메인 간의 협업을 결합도 낮은 구조로 구현해보는 것이었다.

이를 통해 다음과 같은 설계를 실험하고 검증했다:

• 쿠폰 발급, 주문 확정, 외부 전송 등의 도메인 흐름을 상태 기반 이벤트로 분리
• 도메인에서 이벤트 등록 → ApplicationEventPublisher 를 통한 발행
• @TransactionalEventListener(BEFORE_COMMIT or AFTER_COMMIT) 기반 이벤트 감지
• Outbox DB 저장 → Kafka로 전송하는 이벤트 릴레이 구조 구현
• Kafka Consumer → 후속 도메인 처리까지 연결
• Awaitility 기반 통합 테스트로 전체 흐름 검증

문제 정의

1. 동기 트랜잭션 내에서 모든 처리를 해결하려다 보니 책임이 모호해짐

예를 들어, 쿠폰 발급 과정에서 수량 확인 → 발급 처리 → 메시지 전송까지 한 메서드에 몰려있었고,

메시지 발행 실패 시 전체 트랜잭션이 롤백되는 구조는 장애 복원력 측면에서도 한계가 있었다.

2. 이벤트는 도메인에서 발생하지만, 전송/처리는 애플리케이션 레이어의 역할

초기에는 컨트롤러나 서비스 단에서 Kafka 메시지를 직접 발행하려 했으나,

"도메인의 책임은 상태 전이",

• *"메시지 전파는 후속 처리"**라는 역할 분리가 필요하다는 결론에 도달했다.

해결 전략 및 설계 방식

도메인 → ApplicationEvent → Outbox → Kafka 구조

도메인 객체는 상태 변화 시 registerEvent()를 통해 도메인 이벤트를 등록하고,

Application Layer에서 publishEvent()로 발행한다.

coupon.validateUsable(clock, userId); // → 내부적으로 도메인 이벤트 등록
coupon.getDomainEvents().forEach(eventPublisher::publishEvent);
coupon.clearEvents();

전체 흐름 예시

쿠폰 발급 요청 흐름

[Coupon 도메인]
 - validateUsable() 내부에서 CouponIssueRequestedEvent 등록

[Application Layer]
 - @TransactionalEventListener(BEFORE_COMMIT)
   → OutboxService.saveEvent() 호출 → OutboxMessage 저장

[Infrastructure Layer]
 - ScheduledOutboxRelayRunner (1초마다 실행)
   → 저장된 메시지를 Kafka 로 전송 → 성공 시 lastProcessedId 갱신

[Kafka Consumer]
 - coupon.issue.requested 수신 → 발급 처리 실행

결제 성공 → 주문 상태 변경 → 외부 전송 흐름

[Payment 도메인]
 - createSuccess() 시 OrderConfirmedEvent 등록

[OrderConfirmedEventHandler]
 - AFTER_COMMIT + @Async로 수신 → 주문 상태 CONFIRMED 전이

[OrderAggregate]
 - markConfirmed() → ProductSalesRankRecordedEvent, OrderExportRequestedEvent 등록

[OrderExportEventHandler]
 - AFTER_COMMIT + @Async → Kafka 전송

[Kafka Consumer]
 - order-export 수신 → 외부 연동 처리

테스트 전략

통합 테스트 검증 포인트

Awaitility를 활용하여 비동기 리스너가 동작 완료될 때까지 기다리며, 로그 기반으로 실제 흐름 검증 완료.

인사이트

도메인 이벤트는 도메인 상태 전이의 일부로만 발생해야 한다

• 단순 메시지 전송을 위한 이벤트는 Application 레벨에서만 처리하고,
• 도메인 이벤트는 도메인의 상태 변화가 명확히 발생한 경우에만 사용해야 구조가 명확해졌다.

Kafka 도입의 기준점은 ‘타 도메인으로의 이벤트 전파 필요성’

• 쿠폰 발급 같은 단일 도메인 처리라면 Redis/Stream 으로도 충분하지만,

• 주문 → 랭킹 → 외부 전송처럼 도메인이 여러 개로 분리되고,

  처리를 병렬화하거나 장애 복원성을 확보하고자 할 때 Kafka의 도입 가치가 명확해졌다.

Outbox 패턴은 메시지 신뢰성과 장애 대응의 기초

• 메시지 저장 → 별도 릴레이 스케줄러 → Kafka 전송 구조를 구현하면서,

  트랜잭션 일관성과 메시지 재처리 구조를 어느 정도 확보했다.

• 다만 실패 메시지 저장, Retry 큐, DLT(DLQ)까지는 아직 보완이 필요하다.

요약 정리

회고

성과

• Outbox 기반의 Kafka 연동 구조를 도메인 이벤트로 연결
• 도메인 책임(상태 전이) ↔ 후속 전파(메시징) 역할 분리
• Kafka, ApplicationEvent, Scheduler, Consumer의 흐름을 하나의 시나리오로 통합

아쉬움

• 단일 애플리케이션 구조에서 Kafka를 붙이다 보니 약간의 과도함

이번 주의 핵심 목표는 핵심 도메인의 상태 전이를 기준으로 트랜잭션 경계를 재설계하고, 이벤트 기반으로 도메인 간 협업을 비동기화하여 실시간성과 복원력을 동시에 확보하는 구조를 구현 및 검증하는 것이었다.

이를 위해 다음과 같은 도메인 이벤트 체계와 상태 기반 설계를 적용하고, 이벤트 실패 보상 흐름까지 포함한 구조적 실험을 진행했다:

• 결제 성공 → 주문 CONFIRMED → 상품 랭킹 등록 → 외부 전송 까지 이벤트 체이닝 구현
• 잔액 충전 → 잔액 이력 저장 로직을 도메인 이벤트로 분리
• 주문 확정 실패 시 OrderConfirmationFailedEvent 로 보상 트리거 설계
• @TransactionalEventListener(AFTER_COMMIT) + @Async 기반 비동기 리스닝 구조 적용
• Awaitility 기반의 E2E 통합 테스트로 전체 이벤트 체이닝 검증

문제 정의

1. 결제/주문 트랜잭션이 하나의 흐름에 결합되어 실패 전파가 광범위함

• 결제 성공 후 주문 상태 변경, 상품 랭킹 기록, 외부 전송까지 모두 한 흐름에 존재
• 중간 하나라도 실패하면 전체 트랜잭션이 롤백되어 UX와 데이터 무결성 모두에 악영향

2. 부가 로직이 핵심 로직 내부에서 처리되어 트랜잭션이 길어짐

• 판매량 기록이나 외부 연동 요청 같은 부가 로직이 핵심 결제/주문 트랜잭션에 포함됨
• I/O 작업 포함 시 타임아웃, 장애 전파, 트랜잭션 병목 리스크 증가

해결 전략 및 설계 방식

🧾 STEP15 – 도메인 이벤트 기반 관심사 분리

설계 목표

• 결제, 주문, 잔액, 통계, 외부 전송 등 도메인을 상태 전이 기반으로 명확히 분리
• 후속 처리는 모두 이벤트 리스너에서 처리하여 핵심 트랜잭션은 작게, 처리는 분산되도록 설계

이벤트 체이닝 구조

1. 결제 성공 시 → OrderConfirmedEvent 발행
2. 주문 CONFIRMED → ProductSalesRankRecordedEvent, OrderExportRequestedEvent 발행
3. 각 이벤트는 AFTER_COMMIT + Async 리스너에서 소비
4. 실패 시 OrderConfirmationFailedEvent 로 보상 이벤트 분리

테스트 전략

통합 테스트 구조

• Awaitility를 활용한 비동기 리스너 대기
• 실제 이벤트 흐름이 순차적으로 실행되는지, 비동기 리스너가 정상 동작하는지 확인

📌 통합 테스트 실행 로그에서 도메인 이벤트 등록, 리스너 실행 로그까지 추적

인사이트

• 핵심 도메인은 상태 전이만 책임지고, 후속 로직은 이벤트로 연결할 때 구조가 명확해진다.
• @TransactionalEventListener(AFTER_COMMIT) + @Async 구조는 핵심 트랜잭션과 후속 I/O 작업을 분리하면서도 흐름을 연결시켜준다.
• 이벤트가 늘어나면 복잡도도 함께 증가한다. 따라서 어떤 이벤트는 발행하지 말고 도메인 내부로 처리해야 할지 선별 기준이 필요하다.
• 실패 상황에 대비해 XXXFailedEvent를 별도 정의하고 로깅하는 방식은 Kafka가 없는 상황에서도 복원력을 확보하는 현실적인 대안이 될 수 있다.
• 이벤트 기반 구조는 단순히 메시지를 넘기는 수준이 아니라, 도메인의 책임을 상태 전이 단위로 구조화할 수 있는 수단이기도 하다.

요약 정리

지난 목표 회고

지난 주 목표는 도메인 이벤트 기반 설계 적용 및 트랜잭션 경계 분리였으며, 아래 항목을 통해 실질적으로 달성했다.

• 모든 상태 전이 기반 도메인 이벤트 등록 완료
• 통합 테스트로 트랜잭션 내/외 경계 분리 흐름 검증 완료
• 이벤트 실패 대비 설계 (OrderConfirmationFailedEvent) 도입

다만 Kafka나 Outbox 기반의 실제 MSA 구조에서의 전파 설계는 아직 적용하지 못했다. 실패 이벤트를 DB 테이블에 저장하거나 Retry Queue를 활용한 자동 복구 설계는 향후 과제로 남는다.

이번 주 목표

이번 주의 핵심 목표는 Redis의 자료구조를 활용해 DB 부하를 줄이고, 실시간 처리 및 비동기 처리를 안정적으로 구성할 수 있는 구조를 설계하고 구현하는 것이었다.

이를 위해 다음 두 가지 기능을 중심으로 설계를 진행했다:

• Redis Sorted Set 기반의 실시간 인기 상품 랭킹 시스템
• Redis Stream 기반의 비동기 쿠폰 발급 시스템 (DLQ + 재시도 포함)

문제 정의

1. 실시간 통계를 RDB에 저장하면 발생하는 성능 문제

• 주문 확정 시마다 DB에 인기 상품 통계를 쓰는 구조는 RDB 쓰기 부하 집중 및 락 충돌 발생 우려
• 특히 주문이 폭주하는 피크 타임에는 통계 기록만으로도 DB 병목이 생길 수 있음

2. 선착순 쿠폰 발급에서의 Race Condition

• 동시에 수천 명이 요청을 보내면, count < total 조건을 통과한 요청이 중복 발급되는 현상 발생 가능
• 단순한 동기 락으로는 병렬성 확보가 어렵고, 무조건 실패시키는 방식은 사용자 경험을 해침

해결 전략 및 설계 방식

STEP13 – 실시간 랭킹 시스템 설계 (Redis Sorted Set)

설계 목표

• 실시간 인기 상품 통계 기록을 RDB가 아닌 Redis로 우선 처리
• 기간별(일간/주간/월간) 랭킹 구분과 향후 확장성 고려

구조 구성

ZADD product:ranking:{date} {score} {productId}
EXPIRE product:ranking:{date} 7d

• Sorted Set을 활용하여 주문 수를 점수로 누적
• TTL을 이용해 Redis 용량 관리 + 최신성 유지
• RecordProductSalesEvent를 @TransactionalEventListener로 처리하여 주문과 분리

전략 패턴 적용

• 기간별 랭킹 생성을 위해 RankingStrategy를 도입해 OCP 확장
• 일간/주간/월간 기준에 따라 Redis Key/날짜 생성 방식만 변경되도록 추상화

public interface RankingStrategy {
    String key(ProductRankingCommand command);
    LocalDate date();
}

STEP14 – 비동기 쿠폰 발급 (Redis Stream + DLQ)

설계 목표

• 트래픽이 몰려도 발급 요청을 안전하게 수용하고, 실패 시 복구 가능한 구조로 설계
• DB가 아닌 Redis Stream으로 요청을 버퍼링 → Consumer가 순차 처리

전체 처리 흐름

1. Publisher: Redis Stream 에 발급 요청 저장
2. Consumer: ConsumerGroup 으로 메시지 처리
   → 중복 검사, DB 저장, ACK
   → 실패 시 DLQ로 전송
3. DLQConsumer: 실패 메시지 재시도, 3회 이상 실패 시 폐기

재시도/보상 설계

• DLQ 메시지는 retry:{recordId} Redis 키로 재시도 횟수 관리
• REQUIRES_NEW 트랜잭션을 사용하여 처리 단위를 작게 분리
• 중복 발급 방지는 Redis + DB에서 이중 체크 → 완벽한 멱등성 확보

테스트 전략

• Embedded Redis 기반 통합 테스트에서 Awaitility로 Redis Stream 메시지 처리 대기
• Consumer 수동 호출 → 성공/실패/재시도까지 End-to-End 시나리오 검증
• 발급 실패 시 DLQ → 재처리 후 DB 저장 여부까지 체크

인사이트

• Redis는 단순 캐시뿐 아니라 실시간 처리 버퍼, 순위 정렬, 중복 제어 등 다양한 역할로 활용 가능
• 비동기 설계에서 중요한 건 실패 복구 시나리오를 구조적으로 설계하는 것
• 테스트는 "정상 작동"만이 아니라 실패 → 복구 → 재시도 흐름까지 고려해야 설계의 완성도가 높아짐
• Kafka 없이도 Redis Stream만으로 충분히 트래픽 흡수 + 처리를 분리하는 설계 가능

요약 정리

총평

이번 주는 단순 기능 구현을 넘어서, "운영 가능한 구조란 무엇인가"에 대해 깊이 고민한 시간이었다.

Redis는 캐시 도구가 아니라 하나의 구조적 저장소이며 처리 흐름의 중심이 될 수 있다는 가능성을 실감했다. 특히 Redis Stream은 Kafka가 없더라도 실시간 트래픽 처리, 재시도, 실패 보완까지 충분히 커버 가능하다는 점에서 강력한 무기가 될 수 있음을 확인했다.

비동기 시스템은 단순히 큐에 메시지를 밀어넣는 게 아니라, 실패했을 때의 복구 전략까지 함께 설계되어야 진정한 운영 가능한 구조가 된다는 사실도 체감했다. DLQ, retry count, REQUIRES_NEW 트랜잭션 분리 같은 것들이 그 고민의 결과였다.

또한 랭킹 시스템 구현에서 OCP를 만족하는 전략 패턴을 도입한 경험은 단지 정렬 기준의 유연성 확보가 아니라, 구조적 설계가 시스템의 유지보수성과 직결된다는 것을 보여주는 좋은 사례였다.

이번 주는 Redis라는 외부 인프라를 신뢰할 수 있는 일관성 보장 시스템으로 끌어올리는 실전 연습이었다. 코드뿐 아니라 아키텍처, 장애 상황, 테스트 전략까지 종합적으로 고민하고 구현한 한 주였다.

이번 주의 핵심 목표는 외부 인프라인 Redis를 활용하여, 다중 인스턴스 환경에서 발생할 수 있는 DB 병목 문제를 방지하는 구조를 설계하고 구현하는 것이었다.

이를 위해 적용했던 내용 중 다음 두 가지를 정리해보고자 한다.

• Redisson 기반 분산락을 적용한 주문 생성 등 로직 리팩토링
• @Cacheable(sync = true) 기반의 캐시 적용 + Pre-warming 전략 도입

문제 정의

1. 재고 차감 로직에서의 경쟁 조건

• 기존 구조는 단일 인스턴스, 단일 트랜잭션을 전제로 작성되어 있어 다중 인스턴스 환경에서 Race Condition 발생 가능성이 있었다.
• 예: 두 사용자가 동시에 동일 상품을 주문할 경우 재고 차감이 중복되어 음수 재고 발생

2. 인기 상품 조회에서 발생하는 성능 병목

• /api/v1/products/popular API는 캐시가 없을 경우 매 요청마다 DB 조회가 발생
• 트래픽 증가 시 DB 병목으로 응답 시간 급증 및 처리량 한계 발생

해결 전략 및 설계 방식

STEP11 - Redisson 기반 분산락 + 보상 트랜잭션 설계

기존의 주문 생성 로직은 하나의 메서드에 모든 책임이 집중되어 있었다:

@Transactional
public OrderResult createOrder(CreateOrderCommand command) {
    for (CreateOrderCommand.OrderItemCommand item : command.items()) {
        stockService.decrease(...);
        productService.getProductDetail(...);
        // ...
    }
    ApplyCouponResult result = couponUseCase.applyCoupon(...);
    Order order = orderService.createOrder(...);
    orderEventService.recordPaymentCompletedEvent(order);
    return OrderResult.from(order);
}

이 구조는 다음과 같은 문제를 초래했다:

• 락과 트랜잭션 경계가 겹침 → 락 보유 시간이 길어짐
• 각 서비스가 비즈니스 + 트랜잭션 책임을 모두 가짐 → 테스트 및 유지보수 어려움

리팩토링 후 구조

public OrderResult createOrder(CreateOrderCommand command) {
    Order order = null;
    try {
        List<OrderItem> orderItems = orderItemCreator.createOrderItems(command.items());
        Money discountedTotal = couponUseCase.calculateDiscountedTotal(command, orderItems);
        order = orderService.createOrder(command.userId(), orderItems, discountedTotal);
        orderEventService.recordPaymentCompletedEvent(order);
        return OrderResult.from(order);
    } catch (Exception e) {
        compensationService.compensateStock(command.items());
        if (order != null) {
            compensationService.markOrderAsFailed(order.getId());
        }
        throw e;
    }
}

핵심 리팩토링

• @DistributedLock 어노테이션 기반 분산락 적용
• 락 범위를 stockService.decrease() 수준으로 최소화
• 트랜잭션은 @Transactional로 분리, 보상은 REQUIRES_NEW로 안전하게 분리

@DistributedLock(
    prefix = "stock:decrease:",
    key = "#command.productId + ':' + #command.size",
    waitTime = 5,
    leaseTime = 3
)
public void decrease(DecreaseStockCommand command) {
    ProductStock stock = productStockRepository.findByProductIdAndSize(...);
    if (stock.getStockQuantity() < command.quantity()) throw new ...
    stock.decreaseStock(command.quantity());
    productStockRepository.save(stock);
}

보상 트랜잭션 처리(OrderCompensationService)

@Transactional(propagation = REQUIRES_NEW)
public void compensateStock(...) { ... }

@Transactional(propagation = REQUIRES_NEW)
public void markOrderAsFailed(String orderId) { ... }

이 설계로 다음과 같은 장점을 얻었다:

• 락 보유 시간 최소화 (딱 필요한 재고 차감 로직에만 적용)
• 각 책임이 응용 컴포넌트에 따라 명확히 분리
• 장애 발생 시 재고 보상 및 주문 상태 전이로 정합성 유지

STEP12 - Cache 성능 개선 보고서

문제 인식

• 인기 상품 API는 조건이 거의 동일한 반복 호출이 많지만, 캐시가 없으면 DB Full Scan
• 캐시가 없을 경우 800ms 이상의 평균 응답시간
• 부하 테스트 시 DB 커넥션 10~11개까지 소모 → 병목 집중

캐싱 전략 설계

• @Cacheable(sync = true)로 Cache Stampede 방지
• "popular:{days}:{limit}" 형태로 Key 구성
• Redis 기반 캐시 적용
• @Transactional(readOnly = true)로 트랜잭션 오버헤드 제거

@Cacheable(
    value = "popularProducts",
    key = "'popular:' + #criteria.days() + ':' + #criteria.limit()",
    sync = true
)
public List<PopularProductResult> getPopularProducts(PopularProductCriteria criteria)

Pre-warming 전략

@Scheduled(cron = "0 0 3 * * *")
public void warmUpPopularProducts() {
    List.of(new PopularProductCriteria(3, 5))
        .forEach(productFacade::getPopularProducts);
}

• 새벽 3시에 인기 상품 캐시를 사전 로딩
• 사용자가 접근하는 시점엔 이미 캐시가 채워져 있음
• Cold Start latency 제거 + Stampede 방지 보완

k6 + Prometheus + Grafana 기반 성능 측정

(1) 처리량 비교 - popular vs without-cache

그래프 좌상단

• 파란색: 캐시 적용 (/api/v1/products/popular)
• 빨간색: 캐시 미적용 (/api/v1/products/popular/without-cache)

해석:

• 캐시 미적용 상태는 RPS가 거의 0~20 수준. 요청 처리량이 매우 낮음.
• 캐시 적용 상태는 구간에 따라 최대 4,000 RPS까지 도달.
• 명백하게 캐시 사용 시 처리량이 수십~수백 배 증가. DB 병목 해소됨.
• 시간대별로 부하 주기가 있어서 피크 때 성능 차이가 극명하게 드러남.

즉: 캐시 미적용은 DB 병목으로 RPS 제한 발생, 캐시는 병목 없이 처리량이 상승.

(2) 응답 시간 평균 (Latency 평균)

그래프 우상단

• 빨간색: 캐시 미적용
• 파란색: 캐시 적용

해석:

• 캐시 미적용 요청은 평균 1.6~1.8초(!) → 심각한 지연.
• 캐시 적용 요청은 거의 0초(밀리초 단위) → 응답 시간 극히 짧음.
• 부하가 올라가도 캐시 적용 쪽은 응답 시간 유지, 캐시 미적용은 부하가 커질수록 지연 심화.

즉: 캐시 유무에 따른 latency 차이가 1,000ms 이상. 실사용자 체감으로는 "느림 vs 즉시 응답".

(3) 요청 합계 (Total Requests)

그래프 좌하단

• 파란색: 캐시 적용
• 빨간색: 캐시 미적용

해석:

• 캐시 적용은 최대 260,000건 요청 소화.
• 캐시 미적용은 20,000건 이하 수준으로 정체.
• 캐시 미적용 상태는 부하가 걸릴수록 처리 가능한 요청 수가 급격히 줄어드는 현상 발생.

즉: 캐시 없으면 일정 트래픽 이상부터 아예 요청 처리가 불가능(서비스 한계 도달).

(4) DB 활성 커넥션 수 (Active Connections)

그래프 우하단

• 녹색: 활성 DB 커넥션

해석:

• 캐시 미적용 요청에서만 활성 커넥션이 10~11개로 증가 → DB에 병목이 집중됨.
• 캐시 적용 요청에서는 커넥션 증가 거의 없음 → 캐시만으로 응답 처리.
• DB 풀 한계치 근처까지 활성 커넥션 사용 → 초과 시 커넥션 풀 exhaust 가능.

즉: 캐시가 없으면 커넥션 풀 포화로 요청 대기/실패 가능성이 매우 높아짐.

성능 결론

• 처리량 증가, latency 감소, DB 부하 완화 → 캐시 전략 효과 실증 완료
• sync = true + Pre-warming 조합이 실제 트래픽 환경에서 견고하게 작동함을 검증

요약 정리

인사이트

• 분산 환경에서의 동시성은 단순 트랜잭션만으로 방어 불가 → 분산락 + 구조적 분리 필요
• 락은 보유 범위가 짧을수록 좋고, 트랜잭션과 분리해서 책임을 명확히 해야 유지보수 가능
• 캐시 전략은 단순 @Cacheable 선언이 아니라, TTL 관리, 키 전략, 예외 처리, preload 전략까지 포함한 종합 설계여야 한다
• 성능 개선은 “감”이 아니라 “측정 기반”으로 접근해야 확실한 개선이 가능하다

총평

이번 주는 단순한 과제 수행을 넘어서, 실제 프로덕션 환경에서 어떻게 동시성과 트래픽 이슈를 처리할 수 있을지 깊이 고민해본 시간이었다. 특히 트래픽이 급증할 때 시스템을 어떻게 안정적으로 운영할 수 있을지, 락과 트랜잭션의 경계는 어디까지 설정해야 하는지를 고민하다 보니 자연스럽게 SOLID 원칙, OOP, DDD, Testable Code 같은 개념들이 설계 관점에서 따라왔다.

처음엔 어려워 보였던 개념들이 사실은 "각자의 책임을 명확히 나누는 유연한 구조를 만들기 위한 생각의 확장"이라는 걸 체감할 수 있었다. 도메인이나 컴포넌트뿐 아니라 작은 클래스, 하나의 메서드, 심지어 파일 단위까지도 역할과 책임에 맞게 설계하는 것이 왜 중요한지 몸으로 느꼈다.

또한, 락과 트랜잭션 범위를 최소화하기 위한 고민 속에서 "실패했을 때 어떻게 처리할 것인가?"라는 질문에 자연스럽게 도달했고, 그 해답을 보상 트랜잭션이라는 형태로 도출했다. 외부 인프라에 의존하지 않고, 우선은 애플리케이션 레벨에서 try-catch 구조를 활용해 하나의 작업 단위를 구성하고, 실패 시에는 catch 블록에서 재고 복원, 상태 롤백과 같은 보상 로직을 명시적으로 실행했다.

또한 이벤트 기반 처리를 도입하여 정합성은 중요하나 락의 범위 밖으로 분리해도 되는 작업들(ex. 상태 변경, 기록 저장 등)은 @TransactionalEventListener를 통해 비동기적으로 처리함으로써 전체 트랜잭션의 부담을 줄이고자 했다. 현 시점에서 내가 가진 지식과 경험으로 적용할 수 있는 최선의 구조라고 판단했고, 실제로도 구조적으로 꽤 설득력 있는 결과를 도출해냈다.

무엇보다 인상 깊었던 점은, 단순히 코드가 돌아가게 만드는 것이 아니라 “운영 가능한 구조”로 만드는 것이 진짜 개발이라는 감각을 이번 주에 확실히 체득했다는 점이다.

결과적으로 이번 주는 실습 내용 이상의 인사이트를 얻은 주차였다. 설령 제출한 과제가 Fail을 받더라도 전혀 아쉬움이 없을 만큼 많은 것을 고민했고, 배웠고, 구현했다.

테스트가 테스트답기 위해서는, 운영 환경과 최대한 유사하게 만들어야 한다.

Spring Boot 통합 테스트를 하면서 우리는 종종 @Transactional을 테스트 클래스에 붙이는 실수를 저지른다.

처음에는 빠르고 편리해보이지만, 장기적으로는 심각한 문제를 초래할 수 있다.

이 글에서는

• 왜 그렇게 하면 안 되는지
• 무엇을 대신 사용해야 하는지
• 바꾸는 과정에서 발생한 문제와 해결 방법 까지 실전 사례를 기반으로 자세히 설명한다.

2. 흔히 하는 실수: 테스트에 @Transactional

테스트 클래스에 @Transactional을 걸면 테스트 메서드가 끝날 때 자동으로 롤백되기 때문에 DB를 깔끔하게 유지할 수 있다.

하지만 이 방식은 실제 운영에서 발생하는 트랜잭션 흐름과 완전히 다르다.

3. 왜 문제가 되는가

3.1 서비스 추상화 깨짐

Spring은 서비스 계층을 통해 트랜잭션 경계를 명확히 설정한다.

➡️ @Transactional이 테스트 전체를 감싸면, 서비스 메서드별 트랜잭션 검증이 불가능하다.

3.2 트랜잭션 경계 불일치

운영에서는 트랜잭션 시작 → 작업 → 커밋이 명확하지만, 테스트에서는 통째로 하나의 트랜잭션에 묶인다.

➡️ 커밋 타이밍이 다르면, 실제 장애와 다른 결과가 나온다.

3.3 프록시 초기화 실패 (LazyInitializationException)

JPA 연관관계 매핑 시, 일반적으로 fetch = LAZY를 사용한다.

그런데 세션이 이미 종료된 상태에서 프록시 객체를 접근하면 다음과 같은 에러가 터진다:

failed to lazily initialize a collection of role: kr.hhplus.be.server.domain.order.Order.items: could not initialize proxy - no Session

또는

Could not initialize proxy [Coupon#3] - no session

➡️ 운영 환경에서는 커밋 후 세션이 닫히기 때문에,

제대로 검증 안 된 테스트는 실제 배포 후 터질 수 있다.

➡️ 테스트 통과하더라도, 실제 배포 시 운영에서 Lazy 로딩 에러가 발생할 수 있다.

4. Testcontainers를 도입한 이유

Testcontainers를 통해

• 실제 MySQL 컨테이너를 띄우고
• init.sql로 초기 스키마를 세팅하고
• 테스트마다 깨끗한 환경을 구축했다.

이 방식은

"진짜 운영 환경처럼 DB 상태를 구성하고 테스트한다." 는 것을 가능하게 한다.

결과적으로 신뢰성 있는 테스트를 만들어준다.

5. 테스트를 바꾸는 과정에서 발생한 문제

✅ @Transactional을 제거한 직후,

• 연관관계(Order.items, CouponIssue.coupon)가 LAZY 로딩인데,
• 테스트 검증 시점에는 이미 세션이 닫혀서 LazyInitializationException 발생했다.

✅ 원인

• 기본 JPA 조회 (findById, findByUserIdAndCouponId)가 Fetch Join을 사용하지 않았다.

Order order = orderRepository.findById(order.getId()).orElseThrow();
assertThat(order.getItems()).hasSize(1); // 여기서 no session

CouponIssue issue = couponIssueRepository.findByUserIdAndCouponId(userId, coupon.getId()).orElseThrow();
assertThat(issue.getCoupon().getCode()).isEqualTo("TESTONLY1000"); // 여기서 no session

6. 문제를 해결한 방법

Fetch Join JPQL로 연관된 엔티티까지 한 번에 조회하도록 수정했다.

수정 전

Optional<Order> findById(String orderId);

수정 후

@Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.id = :orderId")
Optional<Order> findByIdWithItems(@Param("orderId") String orderId);

@Query("SELECT ci FROM CouponIssue ci JOIN FETCH ci.coupon WHERE ci.userId = :userId AND ci.coupon.id = :couponId")
Optional<CouponIssue> findByUserIdAndCouponId(@Param("userId") Long userId, @Param("couponId") Long couponId);

➡️ 조회 시점에 연관 객체까지 초기화해서 세션 종료에도 안전하게 테스트 가능하게 만들었다.

이렇게 변경함으로써

• 조회 시점에 LAZY 연관관계도 즉시 초기화
• 세션 종료와 관계없이 테스트 통과
• 운영 환경과 일치하는 트랜잭션 플로우 유지

를 달성할 수 있었다.

7. 그렇다면 언제 @Transactional을 써도 괜찮을까?

모든 테스트에 @Transactional을 금지하는 건 아니다.

특정 목적에 따라 @Transactional을 활용하는 것이 오히려 유리할 때도 있다.

✅ 단위 테스트 (Repository 테스트)

• 간단한 CRUD Repository 검증
• Repository Layer 단독 테스트할 때
• DB 상태를 매번 정리하는 게 귀찮을 때
• 롤백 기반으로 DB 초기화를 간단하게 하고 싶을 때

@DataJpaTest
@Transactional
class UserRepositoryTest {

    @Autowired
    private UserRepository userRepository;

    @Test
    void saveUser() {
        User user = new User("junyoung");
        userRepository.save(user);

        assertThat(userRepository.count()).isEqualTo(1L);
        // 테스트 끝나면 자동 롤백됨
    }
}

➡️ 단순한 CRUD Repository 테스트에서는 @Transactional이 유용하다.

✅ "데이터 정리"가 중요한 경우

• 테스트 데이터가 많고
• AfterEach로 매번 delete 하는 게 복잡하거나 성능에 부담될 때

@Transactional을 걸어서 테스트 끝날 때 깔끔하게 롤백시켜주는 것도 전략이 될 수 있다.

단, 이 경우도 통합 테스트(서비스 흐름 검증) 에는 적용하면 안 된다.

8. 그래서 한 줄 정리

9. 최종 요약

10. 마치며

"테스트는 개발자에게 가장 솔직한 피드백을 준다."

코드를 그냥 맞추는 것이 목표가 아니다.

운영과 동일한 환경에서 테스트를 검증하는 것이 진짜 목표다.

Testcontainers, 트랜잭션 경계 유지, 연관관계 초기화 등은 모두

장애 없는 서비스를 만드는 기본기다.

오늘부터, 테스트를 "운영처럼" 짜보자.

1년 6개월의 현업 경력이 있는 전준영입니다. 풀스택으로 시작했지만, 지금은 백엔드 업무를 맡아서 진행하고 있고 개인적으로 공부하는게 한계가 있다고 생각하여, 항해플러스를 시작하게 됐습니다.

2. 항해를 시작하며 꼭 해내고 싶었던 목표

현업에서 테스트코드를 작성은 해봤지만 이렇게 하는 방식이 맞는지, 또한 경험해보지 못한 대용량트래픽 이라는 키워드가 제가 항해플러스를 선택했던 이유입니다.

그렇기 때문에 항해과정을 통해 실제로 현업에서는 어떤식으로 테스트코드를 적절하게 작성하는지와 대규모트래픽은 어떻게 트러블 슈팅하는지를 코치님들의 멘토링과 과제수행을 통해 확실하게 짚고,

또한 평가시스템을 통해 현재 저의 개발능력이 얼만큼되는지를 정확하게 알아보기 위해 끝까지 ‘몰입’ 해서 All Pass 를 받고 싶습니다.

3. 전반부를 마무리하며 가장 기억에 남는 성취

‘토요지식회 발표’, ‘BP선정’ 이렇게 두 가지가 생각이 납니다.

토요지식회를 준비하면서 제가 기존에 알고있던 개념이 맞는지, 추가적인 공부와 코치님들께도 여쭤보면서 더 확실하게 알게 되고 발표도 무사히 마치게된 기억이 남고, 3주차때, 우연히 BP를 받았을 때를 생각해보면 멘토링과 공개 Q&A를 통해 적극적으로 반영하려고 노력하고 새벽까지 개발을 했던 과정들이 BP로 결과로 이어졌던 기억이 크게 기억이 남습니다.

4. 반드시 이뤘으면 했는데 이루지 못한 것

지난 4주차 과제에서 BP를 받지 못한게 아쉽습니다. 안정적인 운영을 위한 테스트코드 작성, 통합테스트의 범위는 어떻게 설정하고, 테스트를 통해 얻어야 될 것은 무엇인지에 대해서 고민을 많이한 한 주여서, 최대한 반영해서 코드를 작성했지만 BP를 받지 못해 아쉽습니다.

5. 내가 강화해야 할 강점 중 가장 중요하다고 생각하는 한 가지

우선 강점으로 집중력과 적극적인 피드백반영 그리고 꾸준함입니다.

이 강점들 중, 먼저 언급한 두 가지는 일시적이지만 ‘꾸준함’ 이 곁들여진다면, 자연스레 성장이 따라온다고 생각해서 가장 중요하고, 제가 앞으로도 지켜야할 강점이라고 생각합니다.

6. 내가 개선해야 할 개선점 중 가장 중요하다고 생각하는 한 가지

몰입하다보니, 정말 중요한게 무엇인지 방황하는 경우가 있습니다.

예를들어 동시성 처리와 관련된 테스트코드 작성할 때, 테스트성공을 위한 코드를 작성해야 되겠다는 생각으로 개발을 하다보니 논리적으로 이상한 코드를 작성하게 된 경우가 있었습니다. 이 때 느꼈던 점이, ‘중요한 걸 놓치는 경우가 있네..’ 라고 생각이 들었었고, 앞으로 항해를 진행할 때 뿐만 아니라, 다른 것을 할 때에도 지금 하고 있는 작업의 목적은 무엇인지, 다른길로 세진 않았는지에 대한 고민을 동반하면서 개발해야 되겠다고 느꼈습니다.

실패의 원인을 다시 마주하다

지난주까지 작성했던 동시성 테스트들은 대부분 실패하도록 설계된 테스트였다. 쿠폰이 중복 발급되거나, 재고가 음수가 되거나, 하나의 주문에 두 번 결제되는 등 의도적으로 레이스 컨디션을 유도해 문제를 확인하는 테스트였다.

그 테스트들을 이번 주에는 "진짜 통과하게" 만들기 위해 다음과 같은 문제들을 다시 정면으로 마주했다:

• 트랜잭션이 테스트 환경에서는 분리되어 실행되는 문제

  → 애플리케이션에서는 @Transactional로 트랜잭션을 묶어도, 테스트 코드에서는 각각의 스레드가 별도 트랜잭션을 사용하는 바람에 제대로 동작하지 않았다.

• 조회 + 수정이 한 메서드에서 수행될 때, 락이 의도대로 안 걸리는 문제

  → FOR UPDATE가 실제로 적용되지 않거나, 트랜잭션 경계 밖에서 호출되는 문제가 있었다.

• “배포 가능한 수준”의 테스트는 어디까지 해야 하는가에 대한 고민

  → 통합 테스트, 서블릿 필터 테스트, 스케줄러 테스트 등은 일반적인 단위 테스트와는 다른 전략이 필요했다.

이번 주는 기능을 많이 구현했다기보다는, 매 순간 구조를 어떻게 바꿔야 진짜 문제가 해결되는지를 고민했던 밀도 높은 시간이었다.

“테스트 통과”가 아니라 “구조를 바꿔서 통과시키는 것”

처음엔 테스트만 통과시키면 되니까 decrease() 메서드 안에 @Transactional(REQUIRES_NEW)를 박아서 강제로 트랜잭션을 분리했었다.

지금 돌이켜보면 굉장히 부끄러운 코드다.

왜냐하면 책임 분리는 엉망이 되고, 트랜잭션의 흐름은 꼬였고, 테스트가 통과한다고 해서 코드가 제대로 설계된 건 아니었으니까.

테스트에 구조를 맞추는 게 아니라, 구조를 바꿔서 테스트가 자연스럽게 통과하게 해야 한다는 걸 깨달았다.

결국 파사드 레이어에서 트랜잭션 책임을 갖도록 조정하고, decrease()는 순수한 비즈니스 로직을 갖도록 정리했다. 그와 함께 락 시점도 명확하게 트랜잭션 안에서 획득되도록 수정했다. 이 과정을 거치자 비로소 테스트들이 "의도한 대로" 통과하기 시작했다.

동시성 이슈가 실제로 발생할 수 있는 기능들

이번 프로젝트에서 실제로 동시성 문제가 발생할 가능성이 있었던 주요 기능들에 대해 구체적인 문제 상황과 적용한 해결 전략을 정리했다.

1. 잔액 충전 – 중복 요청, 과충전 이슈

• 문제: 동일한 요청이 여러 번 들어올 경우, 동일한 금액이 중복으로 충전되는 현상
• 해결:
  • @Version 필드를 사용한 Optimistic Lock
  • @Retryable로 충돌 시 자동 재시도
  • requestId 기반 멱등성 처리로 이미 처리된 요청은 무시
  • 히스토리 테이블에 기록함으로써 중복 처리 방지를 강화

2. 쿠폰 발급 – 수량 제한 초과 발급

• 문제: 동시에 여러 사용자가 같은 쿠폰을 요청하면 남은 수량보다 많이 발급되는 문제
• 해결:
  • 쿠폰 테이블에 @Lock(PESSIMISTIC_WRITE) 적용
  • 락 획득 → 중복 발급 검사 → 수량 검증 및 차감을 트랜잭션 내에서 순차적으로 처리
  • userId + couponId 조합으로 중복 발급을 차단

3. 재고 차감 – 동시 주문 시 음수 재고 발생

• 문제: 여러 사용자가 동시에 같은 상품을 주문하면 재고보다 많이 팔리는 현상
• 해결:
  • 재고 row에 PESSIMISTIC_WRITE 락 적용
  • findByProductIdAndSizeForUpdate()로 락을 선점한 뒤, 재고 차감과 저장을 같은 트랜잭션 안에서 수행
  • 재고 부족 시 예외 발생으로 즉시 실패 처리

4. 결제 요청 – 복수 결제 발생 가능성

• 문제: 하나의 주문에 대해 결제 API가 여러 번 호출되면 결제가 중복으로 처리될 수 있음
• 해결:
  • 주문 row에 PESSIMISTIC_WRITE 락 선점
  • 결제 진행 전 주문 상태가 REQUESTED인지 선점 확인
  • 잔액 차감 → 결제 기록 저장 → 주문 상태 변경까지 하나의 트랜잭션에서 처리

이 4가지 케이스 모두 실제 테스트로 검증되었고,

단순한 트랜잭션 선언만으로는 해결되지 않는 문제들이었기에 락 전략과 멱등성, 재시도, 트랜잭션 경계까지 모두 고려한 설계가 필요했다.

요약

인사이트

• 단순히 @Transactional만 붙이는 것으로는 경쟁 조건을 방지할 수 없다
• 락의 적용 시점, 트랜잭션 경계, 재시도 전략, 멱등성 처리는 모두 함께 고려되어야 한다
• 테스트에서도 실제 장애를 유도해서 설계를 검증해야 구조적 결함을 잡을 수 있다

알게 된 것들

• FOR UPDATE는 트랜잭션 안에서 실행되어야 의미가 있다.
  • 예: decrease()에서 product를 먼저 조회하고 이어서 stock을 락 걸려고 할 때, 이게 다른 트랜잭션에서 조회됐다면 이미 락이 무의미해진다.
  • → 락은 트랜잭션 시작 이후, 가장 먼저 필요한 데이터에 걸어야 한다.
• 테스트 환경에서 동시성을 검증할 때는 @Transactional(propagation = NOT_SUPPORTED)를 써서 트랜잭션 없이 초기 데이터를 세팅해야 한다.
• 테스트는 단순히 "통과"하는 게 목적이 아니라, 설계가 올바르게 되어 있는지를 검증하는 도구여야 한다.

부가기능: 필터 / 인터셉터 / 스케줄러도 다뤄봤다

• Interceptor: 요청 헤더에 사용자 ID를 주입하는 인증 역할
• Filter: 간단한 로깅 처리
• 스케줄러: 매일 0시에 만료된 쿠폰 비활성화

이 기능들은 서블릿 레벨에서 작동하는 컴포넌트이기 때문에 일반적인 단위 테스트로는 검증하기 어려웠다. 그래서 MockMvc 환경에서의 흐름 테스트, 또는 스케줄러는 직접 호출 테스트처럼 별도의 전략을 고민해봤다.

“이런 건 어떻게 테스트하지?”라는 고민 자체가 성장의 계기가 됐다.

다음 주 목표

차주에는 Redis와 Kafka를 활용한 구조 실험을 진행할 예정이다.

• Redis로 Rate Limiting이나 글로벌 락 처리

• Kafka로 주문/결제/이벤트 기반 메시지 처리 구조 구성

• 지금까지 학습한 트랜잭션 설계, 테스트 전략, 동시성 처리를 기반으로

  “분산 시스템에서도 안정적으로 동작하는 구조”를 직접 실험해볼 계획이다.

이번에는 “이걸 이렇게 하면 되지 않을까?” 하고 머릿속에서만 떠돌던 걸 실제로 구현해볼 수 있을 것 같아 기대된다.

총평

이번 주는 기능 하나하나보다, 그 기능을 감싸는 구조를 진짜 운영 가능한 형태로 바꿔낸 주였다.

동시성 테스트는 결국 실패를 통해 구조를 고치는 과정이라는 걸 온몸으로 체감했고,

그 결과 테스트는 물론, 실제 운영에서도 견고할 수 있는 코드를 만들 수 있었다.

통합 테스트는 두 개 이상의 계층이 실제로 상호작용한다는 점에서 유닛 테스트와는 성격이 달랐다. 그래서 가장 먼저 고민한 건 테스트 커버리지를 어떻게 설정할 것인가였다.

이미 도메인과 서비스 레이어의 유닛 테스트는 충분히 작성되어 있었기 때문에, 중복되지 않도록 범위를 잘 구분해야 했다. 단순히 JPA가 제공해주는 조회 기능 같은 건 제외하고, 인프라스트럭처와 애플리케이션 레이어 간의 상호작용에 집중해서 테스트 케이스를 리스트업했다.

그 과정에서 파사드 계층도 테스트할 필요가 있을까? 싶은 의문이 생겼고, 실제로 몇 개 테스트 코드를 작성해 보니 결국 흐름만 체크하게 되더라. 그래서 파사드 쪽은 흐름만 확인하는 정도로 간소화하고, 핵심은 서비스 ↔ 인프라스트럭처 간 유기적인 결합이 잘 작동하는가에 집중해서 테스트를 구성했다.

테스트 환경도 따로 분리했다. 프로덕션 DB와의 의존성을 줄이기 위해 docker-compose로 MySQL 컨테이너를 구성하고, schema.sql , data.sql 로 초기 스키마 및 데이터를 세팅해 테스트를 수행했다. 이 환경 덕분에 통합 테스트를 CI 환경에서도 안정적으로 돌릴 수 있었다.

🧵 동시성 테스트: 실패로 설계를 검증하다

이번 주에는 쿠폰 발급과 주문 생성에 대해 의도적으로 실패하는 동시성 테스트를 구성했다. 이 테스트들의 목적은 성공 여부가 아니라, 경합 상황에서 데이터 정합성이 깨지는 구조적 결함을 드러내는 것이었다.

예를 들어, 쿠폰 발급 테스트에서는 10명의 사용자가 동시에 같은 쿠폰을 요청하고, 주문 테스트에서는 3명이 동시에 재고 10짜리 상품을 각각 5개씩 주문했다. 이런 상황에서 최대 2명만 성공해야 정상이지만, 테스트 결과에서는 초과 발급이나 재고 마이너스 같은 문제가 발생했다.

특히 동시성 테스트의 신뢰도를 확보하기 위해 @BeforeEach에서 @Transactional(propagation = Propagation.NOT_SUPPORTED)를 명시해 초기 데이터 세팅은 트랜잭션 없이 DB에 즉시 반영되도록 처리했다. 그래야 실제 테스트 스레드들이 트랜잭션 캐시 없이 공통된 실데이터를 읽고 쓰는 상황이 재현되기 때문이다. 이 설정 없이는 테스트 결과가 왜곡될 수 있다.

이번 테스트를 통해 트랜잭션 전파 방식, 데이터 커밋 타이밍, 경합 상황에서의 예외 처리 등을 전반적으로 검증할 수 있었고, 동시에 락이나 동시성 제어가 없는 상태에서는 정합성이 어떻게 무너질 수 있는지를 실증할 수 있었다. 실패는 계획된 것이었고, 그 실패를 통해 많은 걸 검증할 수 있었다.

🚀 인기 상품 조회 성능 병목 분석 및 최적화

이번 주에는 인기 상품 조회 API(/api/v1/products/popular)의 성능 병목을 사전에 분석하고, 실행 계획과 인덱스 전략을 기반으로 성능을 개선하는 작업도 함께 진행했다. 단순 구현이 아니라 데이터가 많아졌을 때 실제로 병목이 발생하는 지점을 사전에 파악하고 최적화 포인트를 확보하는 게 목적이었다.

🔍 문제 쿼리 구조

SELECT *
FROM product_statistics
WHERE stat_date BETWEEN ? AND ?
ORDER BY sales_count DESC
LIMIT 10;

• stat_date: 날짜 범위 필터
• sales_count DESC: 정렬 기준
• LIMIT 10: 상위 N개 추출

이 조합은 대용량 데이터에서 전형적인 성능 저하 구조다.

초기에는 인덱스 없이 실행해서 Full Scan, filesort, post-filter 등 병목이 모두 발생했다.

🛠️ 해결 전략

1. 단순 인덱스 적용
   • stat_date 기준 인덱스를 추가해 Index Range Scan 유도
2. 복합 인덱스 적용
   • CREATE INDEX idx_stat_date_sales ON product_statistics(stat_date, sales_count DESC)
   • 정렬 포함 인덱스로 filesort 제거 가능성 확보
3. Covering Index 확장
   • 필요한 컬럼을 인덱스에 포함시켜 테이블 접근 자체 제거
   • CREATE INDEX idx_stat_date_sales_covering ON product_statistics(stat_date, sales_count DESC, product_id, sales_amount)

📊 성능 개선 결과 요약

✅ 느낀 점

단순히 인덱스를 "건다"는 수준이 아니라, 실제 데이터 분포와 쿼리 조건에 따라 어떤 필드 조합으로 인덱스를 구성해야 하는지를 직접 체감했다.

또한 EXPLAIN ANALYZE를 통해 실제 실행 계획을 보고, Row 수, 정렬 처리 방식, 실행 시간까지 분석하는 연습은 정확한 병목 지점 파악과 설계적 근거 확보에 굉장히 유효했다.

✅ 최종 회고

이번 주차는 구현을 넘어서서 설계된 구조가 실제 운영 환경에서 어떤 문제를 만들 수 있는지, 그 문제를 어떻게 미리 설계적으로 방어할 수 있는지에 대한 경험을 쌓을 수 있었던 시간이었다.

• 테스트는 실패를 유도할 수 있어야 하고,
• 인프라는 독립된 환경에서 검증 가능해야 하며,
• 성능은 기능 구현 이후가 아니라, 설계 단계에서 고려되어야 한다.

다음 주는 트랜잭션 격리 수준과 락 전략을 실제 재고 차감 로직에 적용해보며, 동시성 제어 구조를 개선할 계획이다.

이론적으로만 알고 있던 DDD, 계층 간 분리, DIP 등의 개념을 실제 코드에 녹여내는 과정이었고, 발제와 피드백을 통해 결국 이 구조들이 추구하는 본질은 "도메인을 외부로부터 격리하고, 의존성을 역전시킴으로써 변경에 강한 구조를 만드는 것"이라는 걸 체감할 수 있었다.

초기에는 레이어드 아키텍처처럼 Controller → Service → Repository 구조를 익숙하게 생각했지만, 이번 과제를 통해 Interface → Application (Facade / Service) → Domain ← Infrastructure 형태로 책임을 재정의하면서 구조에 대한 시야가 훨씬 넓어졌다.

헥사고날 아키텍처를 처음엔 어렵게 느꼈지만, '도메인이 중심에 있고 in/out 포트를 통해 어댑터들과 통신한다’는 흐름이 결국은 도메인을 보호하기 위한 장치라는 걸 알게 되었고, 이 흐름은 결국 클린 아키텍처의 계층 분리와도 크게 다르지 않다는 걸 깨달았다.

다만 헥사고날의 경우 in-port(UseCase)와 out-port(Repository 등)를 반드시 인터페이스로 정의해야 한다는 규칙이 있어서 더 엄격하게 느껴지긴 했는데, 결국 중요한 건 "조직에서 어떤 컨벤션으로 이 구조를 유연하게 해석하느냐" 라는 점이었다. 어떤 아키텍처든 본질은 변경에 유연하고, 도메인을 중심에 두는 설계라는 점에서 같다고 생각한다.

1. 도메인과 엔터티 분리에 대한 고민

초기 설계 단계에서는 클린 아키텍처 원칙에 따라 도메인 모델과 JPA 엔터티를 분리하는 방식을 고려했다. JPA 엔터티는 영속성과 밀접하게 연결된 객체이기 때문에, 이를 비즈니스 도메인으로 직접 사용하는 것은 객체지향적인 설계 원칙과는 다소 맞지 않다는 판단이었다.

또한, 순수한 도메인 모델을 별도로 두면 테스트 용이성과 구조적 명확성이 높아진다는 장점도 있다.하지만 실제로 적용해보니, 도메인 ↔ 엔터티 매핑 단계가 추가되며 복잡도가 올라가고, JPA가 제공하는 지연 로딩, 영속성 컨텍스트, 변경 감지 등 핵심 기능들을 활용하기 어려워지는 단점도 있었다.

결국 이번 과제에서는 도메인과 엔터티를 분리하지 않고, 동일한 객체 내에서 비즈니스 로직과 영속성을 함께 다루는 구조로 설계하기로 결정했다.상황에 따라 트레이드오프가 필요한 영역이라는 걸 경험적으로 체감할 수 있었고,이번 과제에서는 복잡도보다 실용성과 학습 목적에 맞는 구조 선택이 더 중요하다고 판단했다.

2. 전략 패턴 적용 고민 - 쿠폰 발급

이번 과제에서는 도메인 복잡도가 높은 쿠폰 발급 기능에 전략 패턴을 도입할 수 있을지 고민했다.

현재 구조에서는 Coupon 엔티티 내부에서 모든 유효성 검증과 상태 변경을 수행하고 있었지만,

쿠폰 타입별 정책이 달라질 수 있는 상황을 고려해 전략 패턴 기반 설계로 분리하면 더 유연할 것 같다는 판단이 들었다.

예를 들어, CouponType 별로 정책을 다형적으로 위임하는 방식은 아래와 같다:

public interface CouponIssuePolicy {
    void validateIssuable(Coupon coupon, Long userId);
}

public class LimitedCouponPolicy implements CouponIssuePolicy {
    public void validateIssuable(Coupon coupon, Long userId) {
        if (coupon.isExpired()) throw new CouponException.ExpiredException();
        if (coupon.isExhausted()) throw new CouponException.AlreadyExhaustedException();
    }
}

또한 발급 로직 자체도 전략으로 위임할 수 있다:

public interface CouponIssueStrategy {
    CouponResult execute(IssueCouponCommand command);
}

@RequiredArgsConstructor
public class LimitedCouponIssueStrategy implements CouponIssueStrategy {
    private final CouponReader couponReader;
    private final CouponIssueWriter couponIssueWriter;

    @Override
    public CouponResult execute(IssueCouponCommand command) {
        Coupon coupon = couponReader.findByCode(command.couponCode());
        coupon.validateUsable();  // 정책 위임 또는 내부 처리

        if (couponIssueWriter.hasIssued(command.userId(), coupon.getId())) {
            throw new CouponException.AlreadyIssuedException(command.userId(), command.couponCode());
        }

        CouponIssue issue = couponIssueWriter.save(command.userId(), coupon);
        return CouponResult.from(issue);
    }
}

쿠폰 발급 시나리오 시퀀스 다이어그램

3. 구현 관점 정리

• 각 도메인은 Facade → Service → Domain 계층으로 책임을 명확히 분리
• 외부 입력은 Request/Command, 출력은 Response/Result로 구분하여 의존 역전 실현
• 복잡한 유즈케이스(ex. 결제 성공 시 주문 확정 + 이벤트 저장)는 Facade 계층에서 orchestration
• 결제 방식(Balance, External 등)은 PaymentProcessor 전략으로 분리하여 확장성 확보
• 도메인 이벤트 기반 아웃박스 구조 설계 (OrderEvent, EventRelayScheduler 등)
• 전 계층 단위 테스트 완비 (Repository 없이 mock 기반 테스트)

이번 주는 정말 구현도 구현이지만, 설계를 어떻게 풀어낼지를 깊이 고민한 한 주였다. 추상적으로만 알고 있던 아키텍처 개념들이 실제 코드에서 왜 필요한지, 어떤 효과를 주는지 몸으로 체감했고, 도메인 중심 설계가 단순한 구조 설계를 넘어서 팀 전체 개발 방향성과 유지보수성에 직결된다는 걸 느낄 수 있었다.

다음 주에는 인프라 계층 구현, 통합 테스트, 이벤트 발행 등까지 진행할 예정인데, 이번에 다져놓은 구조를 기반으로 어떻게 확장해갈 수 있을지 기대된다. 특히 Coupon, WaitingQueue 같은 복잡한 상태 기반 도메인을 어떻게 유연하게 풀어낼지 스스로도 궁금하다.

TDD(Test-Driven Development)는 Kent Beck이 제안한 개발 방법론으로, "테스트 코드를 먼저 작성하고, 테스트를 통과하는 코드를 구현하며, 이를 반복적으로 개선하는 개발 방식"이다.

TDD의 기본 사이클은 다음과 같다:

1. Red: 실패하는 테스트를 먼저 작성한다 (아직 기능이 구현되지 않았기 때문)
2. Green: 테스트를 통과하도록 최소한의 코드를 작성한다
3. Refactor: 중복을 제거하고 구조를 개선한다

이 흐름은 단순히 테스트 중심의 개발이 아니라, 안정성과 리팩토링 가능성을 확보하는 개발 전략이다.

💡 TDD에 대한 오해와 현실

처음엔 TDD가 어렵게 느껴졌다. 테스트 코드를 작성하는 것조차 익숙하지 않았고, “어디까지 테스트를 해야 하지?” “테스트는 언제 해야 해?” 같은 고민이 많았다.

TDD를 처음 시작했을 때는 이런 생각이 들었다.

• 이걸 왜 해야 하지?
• 테스트 코드가 너무 많아지는 건 아닌가?
• 실제 서비스 개발에 과연 실용적인가?

처음엔 테스트 작성이 너무 번거롭고, 시간 낭비처럼 느껴지기도 했다. 하지만 점점 기능 단위로 분리된 테스트를 작성하고, 그 테스트를 통해 빠르게 피드백을 받다 보니 "테스트는 개발의 일부이며, 궁극적으로는 유지보수 비용을 줄이기 위한 투자"라는 걸 체감했다.

그리고 이번 과정을 통해 느낀 건 단순했다.

진짜 중요한 건 '이 코드가 진짜 안전한가?' 를 확인하는 것

🔁 테스트의 본질은 검증이고, 리소스 최소화다

이전에는 기능을 만든 후 curl, postman, 프론트 요청 등으로 일일이 확인했다. 시간도 오래 걸리고, 매번 같은 테스트를 반복하면서 실수도 생겼다.

하지만 지금은 다르다.

• 단위 테스트로 빠르게 확인 가능
• Mock 객체로 외부 의존 없이 핵심만 테스트
• 애플리케이션 내에서 검증 가능 → 리소스 최소화

// 이전: postman → DB 확인 → 로그 확인
// 지금: 테스트 코드 한 줄 → assertThat(result).isEqualTo(...)

그리고 무엇보다 중요한 건 '빠른 검증'이다. 한 기능을 만들고 그것이 잘 작동하는지 검증하기 위해 굳이 전체 애플리케이션을 실행하거나, API 호출 → DB 확인 → 로그 추적 등의 수고를 들이지 않아도 된다. 정말 중요한 기능 단위만 쏙 빼서, 빠르게 테스트할 수 있다.

이걸 가능하게 만들기 위해선 "불필요한 의존성 제거"가 핵심이었다. 테스트하려는 단위 외 모든 것들을 "더미"로 치환하고, 진짜 중요한 그 한 단위만 순수하게 검증하는 구조를 만들기 위해 연습했고, 고민했다.

첨예한 테스트 케이스를 만들기 위해선 어떤 조건에서 실패할 수 있는지를 먼저 고민해야 했다. 실패할 수 있는 조건을 설계하고, 그걸 테스트로 먼저 박아두니 기능 자체도 더 날카로워졌고, 사소한 케이스도 놓치지 않게 됐다.

🧪 테스트 전략에 대해 처음 명확히 구분할 수 있었다

→ 이번엔 주로 단위 테스트에 집중하며, 구조를 테스트하기 좋은 형태로 리팩토링하는 경험을 했다.

🔍 어떤 걸 테스트해야 할까?

"예외를 발생시킬 수 있는 모든 경우를 내가 직접 컨트롤할 수 있어야 한다."

• 정상 흐름만이 아니라, 실패 흐름도 반드시 포함
• 도메인의 핵심 상태 변화를 테스트
• 테스트를 쓰기 힘든 구조 → 리팩토링의 신호

🧠 내가 체감한 TDD의 진짜 장점

• 기능 구현보다 설계 중심의 사고가 먼저 일어남
• 테스트 작성이 설계와 책임 분리를 돕는 도구
• 무언가를 만들었을 때, 믿고 넘어갈 수 있는 안전장치
• 구조를 테스트하기 쉽게 만들다 보니, 자연스럽게 의존성 분리, 계층 분리, 클린 아키텍처 구조로 이어짐
• 테스트 코드를 작성한다는 건, "어떤 구조여야 테스트하기 쉬운가?"를 끊임없이 고민하게 만들었다
• 첨예한 테스트를 작성하기 위해 책임을 명확히 분리하다 보니, 서비스 계층이 응집력 있고, 설계 자체가 클린해졌다

🧭 앞으로 배워나갈 클린 아키텍처와의 연결

TDD를 통해 설계와 책임 분리에 대해 끊임없이 고민하다 보면, 자연스럽게 클린 아키텍처(Clean Architecture)의 흐름으로 이어질 수밖에 없다.

클린 아키텍처는 관심사의 분리, 의존성 역전, 테스트 용이성을 극대화하기 위한 구조다. 이번 과정을 통해 다음과 같은 관점을 가지게 되었다:

• 도메인 로직과 외부 구현의 분리 → 순수한 비즈니스 로직 유지
• Application 계층에서 유즈케이스 책임 명확히 하기
• Interface 계층은 표현의 역할, Infra 계층은 구현의 역할에만 집중

TDD는 단순히 테스트를 위한 기술이 아닌, 이런 구조를 가능하게 만들도록 우리를 좋은 방향으로 유도해주는 길잡이 역할을 한다.

🗯 한 줄 정리

TDD는 결국, '테스트 코드'가 중요한 게 아니라 '검증할 수 있는 구조'를 만들도록 유도해주는 도구였다.

최종적으로 아래와 같은 계층을 갖는 구조로 설계했다.

아키텍처 계층 구조

각 계층은 애플리케이션의 한 부분을 담당하며, 서로 명확한 경계를 갖는다. 역할을 분리함으로써 코드의 응집도(cohesion)는 높이고 결합도(coupling)는 낮추어, 변경에 유연하고 테스트하기 쉬운 구조를 얻는다. 계층별 책임은 다음과 같다:

• Request DTO (요청 DTO): 프레젠테이션 계층의 입력 모델이다. 주로 Controller에서 사용하며, 클라이언트로부터 전달받은 요청 파라미터를 담는 간단한 데이터 객체다. 예를 들어 HTTP 요청 본문(JSON)을 매핑하는 @RequestBody용 클래스인데 외부 세계의 데이터 표현을 내부로 들여오는 역할을 하고, Validation Annotation 등을 활용해 1차적인 유효성 검증을 수행할 수 있다.
• Command 객체: 애플리케이션 계층에서 사용하는 유즈케이스 입력 모델이다. Request DTO를 도메인에 전달하기 적합한 형태로 변환한 객체라고 볼 수 있다. 주로 Service에 전달되며, 유즈케이스 수행에 필요한 데이터를 캡슐화한다. Command 객체에는 비즈니스 로직은 없고 순수하게 데이터와 약간의 유효성 체크 정도만 포함한다.
• Facade (파사드): 선택적인 애플리케이션 계층으로, 복잡한 유즈케이스의 진입점을 단순화하는 역할을 한다. 여러 Service 호출이나 트랜잭션 관리가 필요할 경우 Facade에서 한꺼번에 처리한다.
• Controller와 Service 사이의 완충지대* 역할을 하여, 필요에 따라 여러 서비스를 orchestration(조율)하거나 하나의 상위 유즈케이스로 묶어준다. 단순한 경우에는 생략 가능하며, 이 레이어가 없다면 Controller가 직접 Service를 호출하도록 구현한다.
• Service (서비스): 비즈니스 로직을 담당하는 애플리케이션 계층이다. 하나의 서비스는 하나의 유즈케이스(Use Case)를 구현하며, 주로 도메인 객체를 활용하여 비즈니스 규칙을 처리한다. 트랜잭션 경계를 정하거나, 필요한 경우 도메인 객체를 생성/조회(Repository 활용)하고 도메인 로직을 실행한 뒤 결과를 반환한다. 서비스 레이어에서는 도메인 객체와 외부 세계(예: DB)를 중개하지만, 구체적인 입출력 형식(JSON 등)이나 UI에 대해서는 모른다.
• Domain (도메인): 핵심 비즈니스 규칙과 엔티티를 담은 계층이다. 시스템이 제공해야 하는 개념들과 그 불변 조건, 상태 변경 로직 등이 이곳에 있다. 예를 들어 Coupon 엔티티, Coupon과 관련된 도메인 서비스, 그리고 CouponRepository와 같은 저장소 인터페이스가 도메인에 속한다. 다른 레이어에 전혀 의존하지 않으며, 순수 자바/비즈니스 코드로만 이루어진다. 클린 아키텍처의 핵심인 의존성 규칙(Dependency Rule)에 따라, 외부 계층이 도메인에 의존하고, 도메인은 어떤 것도 의존하지 않도록 구성했다.

유즈케이스 흐름: 컨트롤러부터 도메인까지

이제 선착순 쿠폰 발급 기능을 예시로 각 레이어가 어떻게 협력하는지 단계별로 알아보자. 이 기능은 "특정 쿠폰 이벤트에 대해 선착순으로 제한된 수량의 쿠폰을 사용자에게 발급한다"는 시나리오다.

1. Controller: 요청 수신, Request DTO → Command 변환 및 응답 생성

사용자가 한정 수량 쿠폰 발급 API를 호출하면, Controller가 요청을 수신한다.

이 프로젝트에서는 API 명세(@Operation, @PostMapping)는 CouponAPI라는 인터페이스에 정의되어 있고, 실제 로직은 이를 구현한 CouponController에서 처리한다.

@Tag(name = "Coupon", description = "쿠폰 발급 및 조회 API")
@RequestMapping("/api/v1/coupons")
public interface CouponAPI {

    @Operation(
        summary = "한정 수량 쿠폰 발급",
        description = """
        한정 수량 쿠폰을 사용자가 발급받는 API입니다.

        - 한정 수량 초과 시 `422 UNPROCESSABLE_ENTITY` 반환
        - 이미 발급받은 사용자는 `409 CONFLICT` 반환
        - 쿠폰이 만료되었거나 존재하지 않으면 `404 NOT_FOUND` 반환
        """,
        requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(
            required = true,
            description = "발급받을 쿠폰 정보",
            content = @Content(schema = @Schema(implementation = CouponResponse.class))
        ),
        responses = {
            @ApiResponse(responseCode = "200", description = "쿠폰 발급 성공",
                content = @Content(schema = @Schema(implementation = CouponResponse.class))),
            @ApiResponse(responseCode = "404", description = "쿠폰이 존재하지 않거나 만료됨"),
            @ApiResponse(responseCode = "409", description = "이미 발급받은 쿠폰"),
            @ApiResponse(responseCode = "422", description = "발급 가능한 수량 초과")
        }
    )
    @PostMapping("/limited-issue")
    ResponseEntity<CustomApiResponse<CouponResponse>> limitedIssueCoupon(
        @Valid @RequestBody CouponRequest request
    );
}

위와 같이 명세는 인터페이스에서 정의되며, 실제 처리는 다음과 같이 CouponController에서 수행된다:

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/v1/coupons")
public class CouponController implements CouponAPI {

    private final CouponUseCase couponUseCase;

    @Override
    public ResponseEntity<CustomApiResponse<CouponResponse>> limitedIssueCoupon(
        @Valid @RequestBody CouponRequest request
    ) {
        // 1) Request DTO → Command 변환
        IssueLimitedCouponCommand command = request.toCommand();

        // 2) UseCase 실행 (Service 호출)
        CouponResult result = couponUseCase.issueLimitedCoupon(command);

        // 3) 결과 → Response DTO 변환 → 공통 응답 포맷으로 래핑
        return ResponseEntity.ok(CustomApiResponse.success(
            new CouponResponse(
                result.userCouponId(),
                result.userId(),
                result.couponType(),
                result.discountRate(),
                result.issuedAt(),
                result.expiryDate()
            )
        ));
    }
}

흐름 요약

1. CouponRequest (요청 DTO)

   클라이언트에서 전달된 JSON 요청은 CouponRequest 객체로 매핑된다. @Valid를 통해 기본적인 검증도 함께 수행된다.

2. Command 객체 변환

   CouponRequest는 toCommand() 메서드를 통해 IssueLimitedCouponCommand로 변환된다. 이 객체는 애플리케이션 계층에서 사용하는 유즈케이스 입력 모델로, 불필요한 외부 의존을 제거한 순수 데이터 캡슐화 객체이다.

    java
    CopyEdit
    public record IssueLimitedCouponCommand(Long userId, String couponCode) { }
   

3. UseCase 실행

   CouponUseCase는 issueLimitedCoupon() 메서드를 통해 도메인 계층을 호출하고 핵심 로직을 수행한다.

   이 과정에서 쿠폰 존재 여부, 재고, 중복 발급 여부, 만료 여부 등을 도메인 계층에서 검증하게 된다.

4. 결과 변환 및 응답

   UseCase에서 반환된 결과는 CouponResult라는 응용 계층 DTO로 매핑되며, 다시 CouponResponse로 가공된다. 마지막으로 CustomApiResponse.success()로 감싸져 통일된 API 응답 형태로 반환된다.

이 구조의 장점은 다음과 같다:

• 입력, 도메인, 출력 모델을 명확히 구분하여 변경에 유연함
• 인터페이스로 API 명세 분리 → Swagger 문서화와 구현 분리
• 단일 진입점인 UseCase를 통해 비즈니스 흐름이 명확해짐
• 응답 래핑을 통한 일관된 API 응답 포맷 제공

2. UseCase: 유즈케이스 실행 및 도메인 호출

이번 구조에서는 Facade를 따로 두지 않고, CouponController가 직접 CouponUseCase를 호출한다.

CouponUseCase는 실제 비즈니스 흐름을 처리하는 응용 계층의 유즈케이스 인터페이스이고, 그 구현체인 CouponService가 주요 로직을 담당한다.

@Service
@RequiredArgsConstructor
public class CouponService implements CouponUseCase {

    private final CouponReader couponReader;
    private final CouponIssueWriter couponIssueWriter;
    private final CouponIssueReader couponIssueReader;

    @Override
    public CouponResult issueLimitedCoupon(IssueLimitedCouponCommand command) {
        // 1) 쿠폰 조회
        Coupon coupon = couponReader.findByCode(command.couponCode());

        // 2) 쿠폰 유효성 확인 (만료, 재고 등)
        coupon.validateUsable();

        // 3) 중복 발급 여부 확인
        if (couponIssueWriter.hasIssued(command.userId(), coupon.getId())) {
            throw new CouponException.AlreadyIssuedException(command.userId(), command.couponCode());
        }

        // 4) 쿠폰 발급 이력 저장
        CouponIssue issue = couponIssueWriter.save(command.userId(), coupon);

        // 5) 응답용 Result DTO 반환
        return CouponResult.from(issue);
    }
}

흐름 요약

• Reader/Writer 분리 구조
  • CouponReader: 쿠폰 조회 전용 포트
  • CouponIssueWriter: 발급 처리 및 중복 체크
  • CouponIssueReader: 발급 여부 확인 (apply 시 사용)
• 도메인 규칙은 Coupon 엔티티에서 책임지고, 서비스는 흐름만 조율
• 결과는 도메인 객체인 CouponIssue를 CouponResult 응용 DTO로 변환하여 반환

Facade는 왜 없는가?

현재는 유즈케이스 하나만 단순하게 실행하면 되므로 추가 조율(Facade)이 필요 없는 구조다.

알림, 포인트 차감, 이벤트 발행 등과 같은 부가 처리가 없는 경우,

불필요하게 Facade 레이어를 도입하지 않고 간단하고 명확한 흐름을 유지하는 것이 더 낫다.

3. Domain: 핵심 비즈니스 로직과 엔티티

도메인 계층은 시스템의 핵심 비즈니스 규칙과 상태를 표현하는 영역이다.

이번 구조에서는 Coupon 엔티티가 선착순 발급 방식의 핵심 개념과 제약을 담고 있으며, 모든 비즈니스 유효성 검사와 상태 변화는 이 객체 내부에서 수행된다.

@Entity
@Table(name = "coupon")
@Getter
@NoArgsConstructor
public class Coupon {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String code;

    @Enumerated(EnumType.STRING)
    @Column(nullable = false)
    private CouponType type;

    @Column(nullable = false)
    private Integer discountRate;

    @Column(nullable = false)
    private Integer totalQuantity;

    @Column(nullable = false)
    private Integer remainingQuantity;

    @Column(nullable = false)
    private LocalDateTime validFrom;

    @Column(nullable = false)
    private LocalDateTime validUntil;

    // 생성자 및 팩토리 메서드 생략...

    /**
     * 쿠폰 사용 가능 여부 검증 (만료 or 재고 소진 여부)
     */
    public void validateUsable() {
        if (isExpired()) {
            throw new CouponException.ExpiredException();
        }
        if (isExhausted()) {
            throw new CouponException.AlreadyExhaustedException();
        }
    }

    /**
     * 재고 차감 로직
     */
    public void decreaseQuantity() {
        validateUsable(); // 보호 로직 내장
        this.remainingQuantity -= 1;
    }

    /**
     * 할인 금액 계산 (정액/정률)
     */
    public Money calculateDiscount(Money orderAmount) {
        return switch (this.type) {
            case FIXED -> Money.wons(this.discountRate);
            case PERCENTAGE -> orderAmount.multiplyPercent(this.discountRate);
        };
    }

    private boolean isExpired() {
        return LocalDateTime.now().isAfter(this.validUntil);
    }

    private boolean isExhausted() {
        return this.remainingQuantity <= 0;
    }
}

📌 주요 도메인 규칙 요약

• 쿠폰 유효성 검사

  validateUsable() 메서드를 통해 쿠폰의 만료 여부와 발급 가능 수량을 확인한다.

  유효하지 않은 경우에는 도메인 전용 예외를 발생시켜 잘못된 사용을 방지한다.

• 발급 수량 차감 처리

  decreaseQuantity()는 정상적으로 발급이 가능할 때,

  남은 발급 수량을 1 줄이는 역할을 한다.

  단순한 수학 연산이 아니라, 쿠폰 발급의 핵심 상태 변경을 도메인 객체가 스스로 책임지고 수행하는 구조다.

• 할인 금액 계산

  쿠폰 타입에 따라 할인 금액 계산 방식이 달라진다.

  • FIXED : 정액 할인
  • PERCENTAGE : 주문 금액의 일정 비율 할인

기존 방식과의 차이점

이전 구조에서는 issuedUserIds 같은 메모리 내 Set으로 중복 여부를 관리했지만, 지금은 DB 조회 방식(couponIssueWriter.hasIssued(...))을 통해 처리하고 있다.

또한 도메인 예외는 흩어진 개별 클래스가 아닌, CouponException이라는 공통 예외 클래스의 정적 내부 클래스 형태로 통일되었다.

public class CouponException extends RuntimeException {

    public static class AlreadyIssuedException extends CouponException {
        public AlreadyIssuedException(Long userId, String couponCode) {
            super("이미 발급된 쿠폰입니다: userId=" + userId + ", couponCode=" + couponCode);
        }
    }

    public static class AlreadyExhaustedException extends CouponException {
        public AlreadyExhaustedException() {
            super("쿠폰 재고가 모두 소진되었습니다.");
        }
    }

    public static class ExpiredException extends CouponException {
        public ExpiredException() {
            super("쿠폰이 만료되었습니다.");
        }
    }

    public CouponException(String message) {
        super(message);
    }
}

도메인 계층의 핵심

• 불변 조건(invariant)을 보장하는 validateUsable(), decreaseQuantity()는 내부 로직 외부 노출 없이 캡슐화
• 외부 레이어(Service 등)는 도메인 객체의 상태를 직접 수정하지 않고, 메서드 호출을 통해 규칙을 위임
• 예외 상황도 도메인 객체 내에서 직접 판단하고, 적절한 도메인 예외를 던짐

5. 응답 생성 및 반환

Service에서 처리된 결과는 컨트롤러로 반환되며,

컨트롤러는 이를 클라이언트에 전달할 응답 DTO(Response)로 변환한다.

이번 구조에서는 도메인 계층의 처리 결과를 CouponIssue 엔티티로 받은 뒤,

이를 CouponResult라는 응용 계층의 DTO로 변환하고,

마지막으로 CouponResponse라는 프레젠테이션 계층의 DTO로 가공해 API 응답을 생성한다.

Domain(CouponIssue)
    → CouponResult (Application DTO)
        → CouponResponse (Response DTO)

이처럼 입력과 출력 모두에서 별도의 DTO를 사용하면,

API 스펙이 변경되더라도 내부 도메인 로직에는 영향을 거의 주지 않기 때문에

유지보수성과 확장성 면에서 매우 유리하다.

📌 계층 간 책임 분리 흐름 정리

Controller
  → Request DTO (CouponRequest)
  → Command (IssueLimitedCouponCommand)
  → UseCase (CouponService)
  → Domain (Coupon, CouponIssue)
  → Result DTO (CouponResult)
  → Response DTO (CouponResponse)
  → HTTP 응답 (CustomApiResponse)

책임 정리

핵심 인사이트

API의 입력/출력과 내부 도메인 모델을 명확히 분리함으로써,

도메인은 외부 변화로부터 보호되고, 컨트롤러는 오직 입출력 처리에만 집중할 수 있다.

이러한 설계 방식은 변화에 유연하고, 계층 간 책임이 명확하게 구분된 클린 아키텍처 구조를 완성시켜 준다.

패키지 구조 예시

이번 프로젝트에서는 기능별 모듈(Context)을 중심으로 패키지를 나누고,

각 모듈 내부를 계층(Application / Domain / Interfaces / Infrastructure) 기준으로 구분하는 방식을 사용했다.

예를 들어, 쿠폰 기능의 전체 패키지 구조는 다음과 같다:

kr.hhplus.be.server
├── application
│   └── coupon                        # [Application Layer - UseCase, Command, Result]
│       ├── ApplyCouponCommand.java
│       ├── ApplyCouponResult.java
│       ├── CouponResult.java
│       ├── CouponService.java
│       ├── CouponUseCase.java
│       └── IssueLimitedCouponCommand.java
│
├── domain
│   └── coupon                        # [Domain Layer - Entity, Repository Interface, Exception]
│       ├── Coupon.java
│       ├── CouponException.java
│       ├── CouponIssue.java
│       ├── CouponIssueReader.java
│       ├── CouponIssueWriter.java
│       ├── CouponReader.java
│       └── CouponType.java
│
├── infrastructure
│   └── coupon                        # [Infrastructure Layer - Repository 구현체]
│       ├── CouponIssueReaderImpl.java
│       ├── CouponIssueWriterImpl.java
│       └── CouponReaderImpl.java
│
└── interfaces
    └── coupon                        # [Interface Layer - Controller, DTO]
        ├── CouponAPI.java
        ├── CouponController.java
        ├── CouponRequest.java
        └── CouponResponse.java

패키징 전략 설명

• Context 기반 모듈화

  coupon, order, payment, product 등 도메인 기능 단위로 폴더를 나누고, 각 폴더 안에서 계층별로 구조화한다.

• 계층적 구분

  각 모듈 안에서는 기능을 기준으로가 아니라, 클린 아키텍처의 레이어(Application, Domain, Interfaces, Infrastructure)에 따라 파일을 나눈다.

  • application: 유즈케이스 구현, Command/Result DTO
  • domain: 엔티티, 도메인 서비스, 예외, Repository 인터페이스
  • interfaces: API 엔드포인트, Request/Response DTO
  • infrastructure: 실제 DB 연동 구현체 (JPA 등)

• 의존성 방향 준수

  application은 domain에만 의존하고,

  interfaces, infrastructure는 application 또는 domain에 의존하지만,

  그 반대는 절대 없다.

  → 계층 간 의존성은 항상 안쪽에서 바깥쪽으로 향하지 않는다.

이 구조의 장점은 다음과 같다:

• 관심사 분리에 따라 역할이 명확해지고, 유지보수가 쉬워짐
• 테스트 시 각 계층만 독립적으로 검증할 수 있음
• 기능별 모듈이 잘 분리되어 있어, 팀 단위 개발/배포에 유리함
• 추후 도메인 별 CQRS, 이벤트 발행 등도 무리 없이 확장 가능

테스트 전략 및 품질 향상

계층을 명확히 분리한 클린 아키텍처의 또 다른 큰 장점은 테스트 작성이 매우 쉬워진다는 점이다.

각 레이어는 자기 책임만을 갖도록 설계되어 있기 때문에, 작은 단위로 테스트를 격리하고 집중해서 작성할 수 있다.

이번 쿠폰 발급 기능 구현에서는 도메인부터 서비스 레이어까지 다음과 같은 전략으로 테스트를 진행했다.

도메인 단위 테스트

도메인 계층에서는 Coupon 엔티티가 갖고 있는 비즈니스 로직 중심의 메서드들을 단독으로 테스트했다.

예를 들어, 다음과 같은 사항들을 검증했다:

• 만료된 쿠폰은 CouponException.ExpiredException을 던지는지
• 발급 수량이 0인 경우 CouponException.AlreadyExhaustedException을 던지는지
• calculateDiscount()가 정해진 할인 정책에 따라 정확히 계산되는지

이러한 테스트는 스프링 컨텍스트나 DB 없이 순수 자바 객체 수준에서 빠르게 실행되며,

비즈니스 규칙이 제대로 동작하는지를 단순하고 명확하게 검증할 수 있었다.

서비스 레이어 테스트 (Mock 기반)

서비스 레이어에서는 외부 의존성을 가진 CouponReader, CouponIssueWriter, CouponIssueReader 등을 Mockito로 Mock 처리하여 테스트했다.

이렇게 하면 DB 없이도 각 포트의 동작을 자유롭게 시뮬레이션하고, 로직만을 격리하여 검증할 수 있다.

예를 들어, 다음과 같은 테스트 케이스를 작성했다:

@ExtendWith(MockitoExtension.class)
class CouponServiceTest {

    @Mock
    private CouponReader couponReader;

    @Mock
    private CouponIssueWriter couponIssueWriter;

    @Mock
    private CouponIssueReader couponIssueReader;

    @InjectMocks
    private CouponService couponService;

    private final String couponCode = "TEST10";
    private final long userId = 1L;

    @Test
    @DisplayName("쿠폰 정상 발급 성공")
    void issueCoupon_success() {
        // given
        Coupon coupon = createValidCoupon();
        CouponIssue issued = new CouponIssue(userId, coupon);
        IssueLimitedCouponCommand command = new IssueLimitedCouponCommand(userId, couponCode);

        given(couponReader.findByCode(couponCode)).willReturn(coupon);
        given(couponIssueWriter.hasIssued(userId, coupon.getId())).willReturn(false);
        given(couponIssueWriter.save(userId, coupon)).willReturn(issued);

        // when
        CouponResult result = couponService.issueLimitedCoupon(command);

        // then
        assertThat(result).isNotNull();
        assertThat(result.userId()).isEqualTo(userId);
        verify(couponReader).findByCode(couponCode);
        verify(couponIssueWriter).save(userId, coupon);
    }

이 테스트에서는 쿠폰이 정상적으로 발급되었는지,

그리고 save() 메서드가 실제로 호출되었는지를 검증한다.

이외에도 다음과 같은 다양한 상황별 테스트를 작성했다:

• 이미 발급된 사용자인 경우 예외 발생
• 만료된 쿠폰일 경우 예외 발생
• 수량이 소진된 쿠폰일 경우 예외 발생
• 쿠폰을 발급받지 않은 사용자가 쿠폰을 적용하려 할 경우 예외 발생
• 쿠폰 할인 정책이 정확하게 적용되는지 확인

또한 테스트 코드 내에서 반복되는 쿠폰 생성 로직은 아래와 같은 픽스처 메서드로 공통화하여 재사용성을 높였다:

private Coupon createValidCoupon() {
    return Coupon.create(
            couponCode,
            CouponType.PERCENTAGE,
            10,
            100,
            LocalDateTime.now().minusDays(1),
            LocalDateTime.now().plusDays(1)
    );
}

이렇게 함으로써 테스트 코드가 깔끔하고 읽기 쉬워졌으며, 새로운 테스트 케이스를 추가할 때도 부담 없이 확장할 수 있었다.

💡 설계 후기 및 인사이트

이번 설계와 구현을 진행하면서 클린 아키텍처가 가지는 진정한 가치에 대해 체감할 수 있었다.

처음에는 단순히 Controller → Service → Repository 구조만으로 충분해 보였지만,

유즈케이스 중심의 구조 분리, Command/Result 객체의 도입, 응답 DTO 계층 분리를 적용하면서

각 계층의 책임이 더욱 명확해지고 유지보수가 쉬워졌다.

특히 다음과 같은 점에서 큰 만족감을 느꼈다:

• 테스트 가능한 구조

  도메인과 서비스가 잘 분리되어 있어, 각 계층을 Mock 또는 Stub으로 대체하며 테스트할 수 있었고,

  실제 DB 없이도 복잡한 시나리오를 단위 테스트 수준에서 모두 커버할 수 있었다.

• 유연성과 확장성

  예를 들어, 현재는 선착순 발급 방식이지만 추후 추첨 방식으로 변경되어도

  Domain 계층의 로직만 수정하면 되고, Controller나 Application 계층에는 영향이 거의 없다.

  새로운 검증 로직이 필요해도 도메인에 캡슐화하여 추가할 수 있고,

  기존 흐름을 깨지 않고도 유즈케이스를 확장해나갈 수 있는 구조가 갖춰져 있었다.

• SOLID 원칙과 설계 철학의 체화

  단순히 “클린 아키텍처”라는 이름을 따르는 게 아니라,

  내부적으로는 의존성 역전(DIP), 단일 책임 원칙(SRP), 개방-폐쇄 원칙(OCP) 등의 철학이 자연스럽게 녹아들게 되었다.

  이로 인해 요구사항 변경에 유연하고, 테스트와 리팩토링이 쉬운 구조를 실제로 구현할 수 있었다.

아키텍처 설계의 본질적인 가치

이번 주 클린 아키텍처 기반의 설계와 구현을 진행하면서 다시 한 번 느낀 것은, 헥사고날 아키텍처든 클린 아키텍처든 결국에는 SOLID 원칙을 얼마나 잘 지키는가가 핵심이라는 점이었다. 요구사항은 언제든지 변할 수 있기 때문에, 변화에 유연하게 대응할 수 있는 구조를 만드는 것이 설계의 시작이자 목적이라는 걸 체감할 수 있었다.

이러한 이유로 수많은 디자인 패턴과 아키텍처가 등장했고, 이들과 함께 빠른 검증을 가능하게 하는 테스터블한 코드 구조가 결합되어 왔다. 처음에는 이러한 구조가 다소 번거롭고 생산성이 떨어지는 것처럼 느껴질 수 있지만, 시간이 지남에 따라 유지보수성과 확장성이 좋아지고 결과적으로 생산성이 더욱 향상되는 구조라는 것을 직접 경험하게 되었다.

그리고 곰곰이 생각해보면 단순히 코드 구조나 패턴을 아는 것을 넘어서, 왜 이렇게 설계해야 하는지, 그 구조가 장기적으로 어떤 이점을 주는지에 대한 고민이 훨씬 더 중요하다는 생각이 든다. 정말 공부할 것도 많고, 갈수록 더 재밌어진다

초반에는 정말 막막했다. 학교나 학원에서도 설계 과제를 해본 적은 있었지만, 이번처럼 "진짜 내가 주도해서 만들어가야 하는 상황"은 또 처음이었던 것 같다. 특히나 이 과제는 내가 스스로 시나리오를 세우고, 도메인을 정의하고, 설계를 해야 하는 방식이라 더더욱 그랬다. 머릿속에 구상이 안 잡히니까 손도 안 움직이고, 문서 한 줄 쓰는 것도 망설이게 되더라. 무엇보다 ‘설계에 정답이 없다’는 사실이 마음을 더 무겁게 했던 것 같다.

하지만 멘토링과 발제 자료 복기, 그리고 다른 팀원분들의 설계 방향을 참고하면서 조금씩 나만의 기준을 세워갔다. ‘정답은 없다, 내가 정답을 만드는 것이다’라는 생각으로 방향을 정했고, 그때부터 본격적으로 설계를 시작했다. 이동규 코치님 멘토링에서 ‘이벤트 스토밍’이라는 개념을 들은 게 결정적이었다. 이걸 단순히 문서 한 장으로 생각하지 않고, 도메인을 깊이 있게 탐색하고 도출하는 도구로써 받아들이게 되었다. 객체지향적인 설계를 하고 싶다는 욕심도 있었기 때문에, 도메인 모델링을 할 때 꽤 많은 시간을 들였다.

동시성 문제나 외부 이벤트 처리까지도 생각하다 보니 자연스럽게 트랜잭셔널 아웃박스 패턴을 공부하게 되었고, 이 역시 설계에 반영했다. 시퀀스 다이어그램, 상태 다이어그램, 클래스 다이어그램, ERD까지 가능한 모든 시각적 자료를 활용해서 구조를 정리하려고 노력했다. 문서를 작성하는 과정 자체가 ‘정리를 위한 정리’가 아니라, 실제로 코드로 옮겨갈 기반이라는 인식을 하면서 더 몰입할 수 있었다.

심화과제에서는 API 명세와 Mock API 구현을 진행했다. 지난주 과제와 이어지는 흐름이라 익숙한 부분도 있었지만, 이번에는 더 실제 서비스에 가깝게 인터페이스를 나누고 구조를 유연하게 구성하고자 노력했다. Swagger 명세를 위한 인터페이스를 따로 두고, 컨트롤러에서 implements를 통해 구현하는 방식으로 역할을 분리했다. 서비스 계층도 인터페이스를 만들고, Mock 객체를 별도로 구현해서 컨트롤러에 주입하는 형태로 구성했다. 이렇게 하면 실제 구현으로 전환할 때 유연하게 대체가 가능하다고 판단했다. 다만 이 과정에서 몇 가지 고민이 생겼다.

• Mock 객체는 테스트 대상인가? TDD처럼 테스트 코드를 작성해야 할까?
• 컨트롤러의 Swagger용 코드와 Mock 코드가 섞이는 게 너무 보기 싫었는데, 내가 선택한 API 인터페이스 분리 방식이 실무에서도 의미 있는 접근일까?

예를 들어 쿠폰 응답 값을 Mock으로 처리할 때, 실제 도메인에서는 할인율과 타입을 Enum으로 나눠놨지만, 명세에서는 문자열로 묶어서 처리했는데, 이런 건 도메인 모델을 미리 설계해서 반영해야 하는 걸까?

이런 질문들이 계속 머릿속을 맴돌았고, 실제 서비스 설계를 해본 경험이 많지 않다 보니 계속 ‘이렇게 해도 될까?’라는 생각이 들었다. 하지만 그럼에도 불구하고 결국에는 기본과제 + 심화과제 + nice to have까지 모두 마무리할 수 있었고, 지금까지의 과정을 되돌아보면 굉장히 큰 성취라고 느낀다.

물론 설계를 하다 보면 계속 구조가 바뀌고, 그에 따라 문서를 반복적으로 수정해야 했던 건 꽤 지치기도 했다. 처음부터 명확하게 방향이 잡혀서 일사천리로 진행되면 좋겠지만, 아직은 실력을 쌓는 단계이고, 시행착오를 겪으며 배우는 중이라고 생각한다. 완벽하게 하는 것보다, 이번 주에는 진심으로 몰입하고 성장했다는 사실이 더 중요하다고 믿는다.

이번 주는 정말 여러모로 값진 시간이었다. 기획, 설계, 분석, 테스트, 문서화까지 하나의 사이클을 경험하며 확실히 시야가 넓어진 느낌이다. 다음 주는 이 흐름을 잘 이어가되, 설계나 구현을 조금 더 스마트하게, 반복을 줄이면서도 완성도 있게 다듬어보는 걸 목표로 삼고 있다.

가장 좋았던 건, 멘토링과 코치님들의 피드백이었다.
다른 분들의 질문을 들으며 내가 놓친 시각을 얻을 수 있었고, 코치님들의 설명은 단순한 이론이 아니라 실제 경험을 기반으로 한 살아있는 조언이었다. 덕분에 과제의 방향성이 명확해졌고, 개념 하나하나가 현실적인 감각으로 다가왔다. 예를 들어 TDD라는 개념도 처음엔 "테스트를 먼저 쓴다"는 정도로만 이해했지만, 막상 해보니 더 중요한 건 설계의 흐름이었다.
“이 로직은 어느 계층에 있어야 하지?”,
“이 책임은 도메인이 가져가야 할까, 서비스에서 처리해야 할까?”
테스트를 작성하다 보면 자연스럽게 객체지향 설계에 대한 고민으로 이어졌다. 그리고 그게 바로 TDD의 핵심이라는 걸 깨달을 수 있었다.

이번 과제는 DB 없이 in-memory 환경에서 동작하는 구조였고, 여러 요청이 동시에 들어올 때 Race Condition이 발생할 수 있도록 설계되어 있었다. 지금까지 실무에서는 DB 트랜잭션으로 대부분의 동시성 문제를 넘겨왔기 때문에, 직접 애플리케이션 레벨에서 동시성 문제를 해결해보는 건 처음이었다.

결과가 들쭉날쭉하고, 로그를 추적하면서 문제의 원인을 파악하고, 락을 걸어 순서를 제어하는 과정에서
ReentrantLock, synchronized, AtomicLong 등 자바의 동기화 도구들을 하나씩 찾아보고 적용했다.
그리고 이걸 공부하다 보니 자연스럽게 운영체제 수업에서만 보던 프로세스 동기화 개념들까지 연결되기 시작했다.

무엇보다 좋았던 건, 이렇게 문제를 해결하면서 지금까지 막연하게 공부해왔던 CS 개념들이 실제로 내 코드와 연결되는 걸 경험했다는 점이다. 그동안 『컴퓨터 밑바닥의 비밀』 같은 책이나 OS 강의를 보면서 “개발자라면 알아야지”라는 생각으로 억지로 공부했지만, 항상 “이걸 도대체 어디에 써먹지?”라는 생각이 들었다. 그런데 이번 주, 실제 문제를 겪고 나니 그 개념들이 정말 필요하다는 걸 처음으로 체감했다.

문제를 해결하다 보니 처음 듣는 개념들과 알고리즘들이 튀어나오기 시작했다.
Dining Philosophers Problem, Readers-Writers Problem, Producer-Consumer Problem… 처음엔 이름조차 생소했지만, 하나하나 찾아보면서 “이런 문제들이 실제 동시성 제어에서 어떤 역할을 하는가”를 이해하게 됐다.

• Dining Philosophers Problem은 자원을 점유하면서 생길 수 있는 교착 상태(Deadlock) 를 설명하는 문제였고,
• Readers-Writers Problem은 읽기와 쓰기 작업의 동시성 제어에 대한 접근 방식을 고민하게 만들었고,
• Producer-Consumer Problem은 작업 순서 보장과 자원 공유의 어려움을 보여주는 사례였다.

지금 내가 마주한 문제들이 이들과 완전히 같진 않지만, 동시성을 안전하게 제어하기 위한 고민이라는 본질에서 깊이 연결된다는 걸 느낄 수 있었다. 그래서 자연스럽게 구글링도 더 깊이 하게 됐다. 단순히 테스트를 통과하기 위해서가 아니라 단순히 외우는 공부와는 차원이 다른 몰입감을 느꼈고, “아, 이게 진짜 내 공부구나” 라는 생각이 처음으로 들었다. 문제 해결 시 봤던 docs 는 다음과 같다.

• Java Concurrency - Oracle Docs
• Java Locks API
• Dining Philosophers Problem
• Readers-Writers Problem - Readers Preference
• Java Volatile Keyword - Baeldung

한 가지 아쉬운 점이 있다면,
시간 관리를 잘 하지 못해 막판에 급하게 마무리하게 된 부분이다.
다음 주부터는 과제 요구사항을 더 빠르게 파악하고, 설계 흐름부터 먼저 잡는 방식으로 시간을 써보려 한다.

그리고 궁금한 개념은 넘기지 말고, 짧게라도 정리하고 넘어가자. 멘토링이나 Q&A를 듣고 나면 “그래, 맞아” 하고 끝나는 게 아니라, “이걸 내 코드에 적용하면 어떻게 될까?” 까지 고민해보는 게 진짜 내 공부라는 걸 느꼈으니까!

현재 회사에서는 법률 도메인을 기반으로 사용자에게 '법률 서비스'를 편리하게 제공해주기 위한 플랫폼을 개발하고 있다. 사수 없이 처음부터 백엔드와 인프라구성을 도맡아서 서비스를 만들었다. 이제 막 런칭되어, 사용자가 많이 없는 부분이 아쉽고 서비스를 만들고 나니 '내가 작성한 코드가 규모있는 서비스에서 트래픽을 감당할 수 있을까?', 빠른 출시로 인해 MVP 개발 할 당시 TDD를 알고 있었지만, 그떄 당시에는 '제품을 만드는 것' 에만 집중해서 결국 만들고 운영을 할 수 있을 정도의 서버를 개발했다.

이게 최선인가? 고민이 시작됐다

곰곰히 생각해보니, '내가 작성한 코드가 최선인가?', '사용자 유입이 급증한다면 서버는 안정적으로 실행 할 수 있을까?' 라는 고민에 빠지게 됐다. 사수나 CTO가 없었고, 공식문서와 구글링 그리고 chatgpt 의 도움을 받아 개발을 한건데, 다른 개발자들은 요구사항 & 기획이 주어졌을 떄, 어떤 논리로 접근하고 기술을 선정해서 문제를 해결하는지 궁금해졌다.

그래서 성장을 위해서 나는?

개발을 시작할 땐, 어떤 것이든 '구현만 하면된다' 라는 생각으로 개발을 했지만, 현업에서 경험해보고 여러 개발자들과 소통하다보니까, 좋은 개발자는 단순 '구현' 만이 아닌 'CS를 기반한 깊이있는 문제 해결'을 동반한 개발해야 된다고 깨달았다. 우연히 항해플러스에 내가 부족하다고 생각하는 부분, 현업에서 요구하는 부분이 매우 유사하다고 판단되어 나는 한 단계 성장을 위해 '항해 플러스 백엔드' 과정에 참여하게 됐다.

과정이 끝나고나서의 내모습

이 과정이 끝나면 나는 약 1년 6개월의 경력이 있는 개발자가 된다. 하지만 이 과정으로 인해 TDD, Redis&Kafka 를 사용한 대규모 처리 등 능숙하진 않을 지라도 어떻게 접근하고, 생각해서 문제를 해결해야하는지 확실히 알고 있는 개발자가 되어있을거라고 기대한다.

따라서 나의 목표는 블랙배지다. 가능할까? 미지수다. 왜냐하면 커리큘럼에 있는 내용들의 절반이상, 거의 모르는 상태이다. 하지만 지금까지 해왔던 것 보다 조금은 더 이 과정에 몰입한다면 못할 건 없다고 생각한다.

마지막으로

이 과정에 임하면서 마인드셋하는 키워드는 #몰입 #네트워킹 이렇게 두가지가 떠오른다. 몰입하며 한주의 과제에 집중하고 해결해서 다른 개발자들과 소통을 통해 내가 부족한 게 무엇인지, 배울게 무엇인지 파악해서 성장하자.

Stay Hungry, Stay foolish

우리 서비스에는 LLM을 활용한 법률 챗봇이 있다.

법률 도메인이라는 특성상 질문 유형이 어느 정도 한정적일 것이라 예상했지만, 실제 운영 데이터를 확인해보니 유사한 질문과 답변이 중복으로 여러 개 저장되고 있었고 이로 인해 LLM 호출 비용도 꾸준히 증가하고 있었다.

초기 MVP 단계에서는 매번 LLM을 호출해 답변을 생성하는 방식이었지만,

사용자 유입이 증가할 경우 비용 부담이 커지고 응답 속도도 느려질 것이 명확했다.

따라서, 불필요한 LLM 호출을 줄이고 빠른 응답을 제공하기 위해 "캐싱"을 도입하기로 결정했다.

단순한 문자열 기반의 캐싱이 아니라, 질문을 벡터화하여 의미적으로 유사한 질문을 빠르게 찾아주는 방식을 선택했다.

구현 방법: 벡터DB + RedisSearch 기반의 다단계 검색

이 문제를 해결하기 위해 다음과 같은 검색 전략을 설계했다.

1단계: AI 캐싱 (RedisSearch 활용)

• 사용자가 24시간 내 동일하거나 유사한 질문을 입력한 경우, RedisSearch에서 즉시 검색하여 캐싱된 값을 반환한다.
• 임베딩 벡터를 기반으로 벡터 유사도 검색을 수행하여 비슷한 질문이 있다면 빠르게 응답.
• 사용한 기술: Redis + RediSearch + mxbai-embed-large (임베딩 모델)

2단계: RDBMS 검색 (PostgreSQL + pgvector)

• Redis에 캐싱된 값이 없을 경우, PostgreSQL의 pgvector 확장을 활용하여 저장된 임베딩 벡터와 비교한다.
• HNSW(탐색 최적화) 기반의 벡터 검색을 활용하여 LLM 호출 없이 기존 데이터를 찾아 응답.
• 사용한 기술: PostgreSQL + pgvector + HNSW Index

3단계: LLM 호출

• Redis와 RDBMS에서 모두 유사한 질문을 찾지 못한 경우에만 LLM을 호출한다.
• 이때 새롭게 생성된 질문과 답변은 임베딩하여 Redis & PostgreSQL에 저장하여, 다음 번에는 캐싱될 수 있도록 한다.
• 사용한 기술: OpenAI API, Llama-3 기반 모델, FastAPI 서버

기술 선택의 이유

우리는 단순한 문자열 기반 캐싱이 아니라, 의미 기반 검색을 수행해야 했다.

이를 위해 임베딩 벡터를 활용한 벡터DB 기반 캐싱을 설계했다.

왜 RedisSearch를 사용했는가?

1. 빠른 검색 속도 – 인메모리 캐싱이므로 매우 빠르게 응답 가능
2. 간단한 구축 가능 – 대규모 벡터 스토어 대비 운영 부담이 적음
3. RediSearch의 KNN(Nearest Neighbor) 검색 기능 지원

왜 PostgreSQL + pgvector를 사용했는가?

1. 우리 서비스의 규모상 대형 벡터DB (FAISS, Pinecone 등)까지는 필요 없음
2. PostgreSQL의 pgvector 확장은 유지보수 부담 없이 쉽게 사용 가능
3. HNSW 기반 인덱스 최적화 적용 가능

왜 mxbai-embed-large 모델을 선택했는가?

✔️ 초기에는 nomic-embed-text와 비교 테스트를 진행했으나, ✔️ 법률 도메인 특성상 보다 정확한 유사도 검색이 필요하여 mxbai-embed-large 모델을 선택했다. ✔️ 또한, 유사도 임계치를 0.9로 높게 설정하여 정확도가 높은 결과만 반환하도록 최적화했다.

** 구현 과정**

** 1. RedisSearch를 활용한 벡터 캐싱**

// 질문을 임베딩하여 Redis에 저장
public void saveAiChat(String query, String response) {
    String normalizedQuery = normalizeTextForRedis(query);
    String queryHash = hashQuery(query);

    List<Double> embedding = generateEmbeddingAsList(normalizedQuery);
    byte[] queryVectorBinary = convertToFloat32Binary(embedding);
    String base64Vector = Base64.getEncoder().encodeToString(queryVectorBinary);

    String key = "ai_chat:" + System.currentTimeMillis();
    Map<String, String> chatData = new HashMap<>();
    chatData.put("query", normalizedQuery);
    chatData.put("query_hash", queryHash);
    chatData.put("response", response);
    chatData.put("query_vector", base64Vector);

    redisModulesCommands.hset(key, chatData);
    redisModulesCommands.expire(key, 86400); // 24시간 TTL 설정
}

✔ 주요 포인트

✔️ 질문을 임베딩하여 Redis에 저장 ✔️ query_vector 필드를 활용한 벡터 기반 검색 ✔️ MD5 해시 기반의 빠른 문자열 매칭 검색도 함께 적용

2. PostgreSQL + pgvector 기반 RDBMS 검색

CREATE TABLE llm_chat_result (
    id SERIAL PRIMARY KEY,
    query TEXT,
    response TEXT,
    query_embedding VECTOR(1024) -- 벡터 저장
);

CREATE INDEX ON llm_chat_result USING hnsw (query_embedding vector_l2_ops);

✔ 주요 포인트

✔️ gvector 확장을 활용하여 벡터 저장 ✔️ HNSW 인덱스를 적용하여 검색 최적화 ✔️ 벡터 유사도 검색을 통해 기존 질문 재활용

3. 전체 검색 흐름

public String findAiChat(String query) {
    // 1. RedisSearch에서 검색
    Optional<Map<String, String>> redisResult = findSimilarByVector(query);
    if (redisResult.isPresent()) {
        return redisResult.get().get("response");
    }

    // 2. PostgreSQL에서 검색
    Optional<String> dbResult = findInPostgres(query);
    if (dbResult.isPresent()) {
        return dbResult.get();
    }

    // 3. LLM 호출
    return callLlmAndCache(query);
}

결과: 최적화 효과

결론:

✔️ 즉시 응답 가능 (Redis 캐싱 덕분에 100ms 내 응답) ✔️ 비용 절감 (반복되는 질문에 대한 LLM 호출 방지) ✔️ 확장성 강화 (pgvector를 활용한 유사 질문 검색 최적화)

느낀 점 & 개선 방향

✔️ 법률 도메인 특성상 질문이 유사하게 반복되므로, 벡터 기반 캐싱이 효과적 ✔️ 임베딩 모델을 적절히 선택하는 것이 중요 (mxbai-embed-large vs nomic-embed-text) ✔️ 향후 FAISS/Pinecone 같은 대형 벡터 스토어 도입을 고려할 수 있음

마무리

이번 개선 작업을 통해,

LLM 챗봇의 비용을 절감하고, 응답 속도를 획기적으로 줄이는 데 성공했다.

이제 남은 과제는 더 정밀한 임베딩 모델 선택과, 벡터DB의 확장성 테스트가 될 것이다.

(아니 벨로그 마크다운 왜이래.... 이모티콘을 쓰게 만드네...)

FastAPI는 가볍고 빠르게 API를 개발할 수 있는 프레임워크다. 비동기 I/O를 쉽게 지원하며, Pydantic을 활용한 데이터 검증과 직렬화가 편리하다. 하지만 내가 FastAPI를 사용했던 이유는 비동기 처리 때문이 아니라 단순히 사용하기 편하고 경량화된 프레임워크였기 때문이었다.

FastAPI를 사용하면서 API 개발 자체는 간결하고 효율적이었지만, 점점 기능이 확장되면서 더 복잡한 요구사항을 처리해야 했다. 그 과정에서 Spring으로 마이그레이션할 필요성이 생겼다.

2. Spring으로 마이그레이션하며 겪은 어려움

Spring은 개발자에게 많은 기능을 제공해주는 편리한 프레임워크지만, 처음 실무에서 접했을 때 여러 가지 어려움이 있었다. 특히 JPA 연관관계 설정과 자동 구성(Auto Configuration), 상속 관계에서 발생하는 문제에서 많은 시행착오를 겪었다.

2.1 JPA 성능 최적화: Fetch Join vs 네이티브 쿼리, 페이징 충돌 문제 해결

FastAPI에서는 SQLAlchemy를 사용하여 데이터 조회 최적화를 진행했지만, Spring에서는 JPA(Hibernate)를 사용하면서 여러 성능 이슈가 발생했다. 특히 연관관계를 맺은 엔티티를 조회할 때 불필요한 조인과 다량의 쿼리가 실행되는 문제를 해결하는 과정에서 중요한 경험을 얻었다.

2.1.1 문제 상황

• Fetch Join의 장점과 한계
  • 연관된 엔티티를 한 번의 쿼리로 가져올 수 있어 N+1 문제를 해결할 수 있음.
  • 하지만 컬렉션을 포함한 Fetch Join은 페이징과 충돌하는 문제가 있음.
  • LIMIT이나 OFFSET을 사용할 경우 데이터베이스 내부적으로 모든 데이터를 조회한 후 페이징을 적용하기 때문에 성능 저하 발생.
• 네이티브 쿼리 활용의 필요성
  • 특정 경우에는 Fetch Join 대신 네이티브 쿼리를 활용하는 것이 성능적으로 더 유리했음.
  • 복잡한 다중 조인 시, JPA의 JPQL보다 직접 SQL을 작성하여 최적화하는 것이 더 효과적.
  • 인덱스 힌트 및 서브쿼리를 활용해 불필요한 조인을 제거.

2.1.2 해결 방법

Case 1: 단순한 1:N 조회 → Fetch Join 사용

• @EntityGraph 또는 JOIN FETCH를 사용하여 단일 쿼리로 데이터를 가져옴.
• ex) SELECT u FROM User u JOIN FETCH u.orders WHERE u.id = :id
• Fetch Join은 데이터가 적고 페이징이 필요 없는 경우 가장 효과적.

Case 2: 다대다 관계 + 페이징 → 네이티브 쿼리 적용

• JPA의 createNativeQuery를 활용하여 페이징 쿼리를 직접 작성.
• ex) SELECT * FROM orders o JOIN users u ON o.user_id = u.id WHERE u.status = 'ACTIVE' LIMIT 10 OFFSET 0
• JPA의 Fetch Join을 사용하면 불필요한 모든 데이터를 조회한 후 페이징이 적용되므로, 네이티브 SQL을 사용하여 성능 개선.

Case 3: 대량 데이터 조회 최적화 → DTO Projection 적용

• 엔티티를 직접 조회하는 것이 아니라, JPQL을 활용한 DTO 매핑을 사용하여 불필요한 필드 조회를 줄임.
• ex) SELECT new com.example.dto.UserOrderDTO(u.id, u.name, o.id, o.totalPrice) FROM User u JOIN u.orders o WHERE u.status = 'ACTIVE'
• 필요하지 않은 연관관계까지 불러오는 JPA 기본 동작을 차단하여 성능 최적화.

2.1.3 성능 개선 결과

• Fetch Join으로 N+1 문제를 해결한 경우
  • 기존: API 호출 시 평균 500ms → 개선 후 120ms로 단축 (약 4배 속도 개선)
  • 원인: 개별 SQL 호출이 많았던 문제 해결
• 네이티브 쿼리 적용 후 페이징 최적화한 경우
  • 기존: 페이징 요청 시 평균 900ms → 개선 후 250ms로 단축 (약 3.6배 개선)
  • 원인: Fetch Join으로 인해 전체 데이터가 로딩된 후 페이징 적용되는 비효율적 동작을 네이티브 SQL로 변경하여 해결
• DTO Projection을 적용한 경우
  • 기존: 엔티티 조회 후 불필요한 필드 포함하여 전송 (800ms) → 필요한 필드만 조회 후 300ms로 단축
  • 원인: 불필요한 필드까지 로드되면서 쿼리 최적화가 되지 않던 문제 해결

이 과정을 통해 JPA의 기본 동작을 그대로 따르는 것이 항상 최적은 아니며, 상황에 맞게 Fetch Join, 네이티브 쿼리, DTO Projection을 적절히 활용해야 한다는 점을 체감했다.

2.1.4 CQRS 패턴 적용

이 과정에서 CQRS(Command Query Responsibility Segregation) 패턴을 알게 되었고, 읽기와 쓰기를 분리하는 방식이 성능 최적화에 적절하다는 점을 체감했다.

CQRS 패턴이란?

CQRS(Command Query Responsibility Segregation)은 읽기(쿼리)와 쓰기(커맨드)의 책임을 분리하는 아키텍처 패턴이다. 단일 데이터 모델을 사용하여 읽기와 쓰기를 모두 수행하는 전통적인 방식과 달리, 읽기 전용 모델과 쓰기 전용 모델을 분리함으로써 성능 최적화와 확장성을 높일 수 있다. 이 패턴을 적용하면서, 복잡한 조회는 별도의 최적화된 쿼리를 활용하고, 쓰기 연산은 도메인 로직을 통해 일관성을 유지하는 접근 방식을 고려했다.

2.2 상속 관계에서의 Discriminator Column(DTYPE) 문제

JPA에서 @Inheritance(strategy = InheritanceType.JOINED)을 사용하여 상속 관계를 정의할 때, @DiscriminatorColumn을 통해 DTYPE을 명시적으로 관리했다. 그러나, 필드 셰도윙(Field Shadowing) 문제로 인해 데이터가 null이 되는 문제가 발생했다.

2.2.1. 문제 상황

• 부모 클래스와 자식 클래스에서 같은 이름의 변수를 정의하면, JPA가 올바르게 매핑하지 못하는 현상이 발생.
• 이를 통해 특정 필드 값이 null로 저장되거나 조회할 때 잘못된 데이터가 반환되는 이슈가 발생.
• 특히, @MappedSuperclass를 사용하지 않고 SINGLE_TABLE 전략을 사용할 경우 DTYPE이 예상과 다르게 동작할 가능성이 있음.

2.2.2. 해결 방법

• 부모 클래스와 자식 클래스 간의 중복 필드 제거.
• 필요한 경우 DTO 변환을 통해 명확하게 데이터 매핑을 수행.
• JOINED 전략을 사용했지만, 필드 셰도윙 문제로 인해 데이터 정합성을 유지하기 어려운 경우가 발생할 수 있음. 이를 방지하기 위해 부모 클래스와 자식 클래스 간의 필드 중복을 최소화하고, 명확한 데이터 매핑을 수행해야 함..

이 과정에서 JPA의 동작 방식과 상속 매핑 전략을 더욱 깊이 이해하게 되었으며, ORM을 사용할 때 발생할 수 있는 예기치 않은 문제들에 대한 대응력을 키울 수 있었다.

2.3 자동 구성(Auto Configuration)과 제어의 역전(IoC)

Spring은 다양한 자동 구성을 제공하여 개발자가 직접 설정하지 않아도 편리하게 사용할 수 있도록 지원한다. 하지만 이러한 자동 구성은 내부 동작을 정확히 이해하지 못하면 오히려 장애를 유발할 수 있다.

2.3.1. 문제 상황

• Spring Boot가 제공하는 ObjectMapper, Jackson 등의 자동 설정을 잘 모르고 사용하면 디버깅이 어려운 문제가 발생.
• 특정 설정을 덮어씌우는 바람에 예상과 다른 동작이 나오는 경우가 있었음.
• 디버깅 과정에서 IoC(제어의 역전, Inversion of Control)를 이해해야 했음.

2.3.2. 해결 방법

• 자동 설정이 어떻게 동작하는지 명확히 이해하고, 필요한 경우 수동으로 설정 값을 지정.
• @ConfigurationProperties, @Bean 등을 활용하여 원하는 설정을 명확히 정의.
• application.yml에서 설정 값을 명확히 관리하여 불필요한 오버라이딩을 방지.

이 과정에서 제어의 역전(IoC)이란 무엇인지 더 깊이 이해하게 되었고, Spring이 많은 것을 자동으로 해주지만 결국 개발자가 도구를 정확히 이해하고 사용해야 한다는 점을 배웠다.

3. 마이그레이션을 통해 배운 점

Spring으로 마이그레이션하면서 가장 크게 배운 점은 다음과 같다.

3.1. FastAPI는 비동기 I/O 때문이 아니라 경량화된 구조가 좋아서 선택했지만, 대규모 서비스에서는 Spring의 강력한 지원이 필요했다.

3.2. JPA 연관관계를 잘못 설정하면 성능이 심각하게 저하될 수 있으며, 이를 해결하기 위해 CQRS 패턴과 네이티브 쿼리를 활용하는 것이 효과적이었다.

3.3. 상속 관계에서 Discriminator Column을 활용할 때, 필드 셰도윙 문제를 방지하기 위해 데이터 매핑을 명확하게 해야 한다.

3.4. Spring의 자동 구성은 개발을 편리하게 해주지만, 내부 동작을 모르면 예상치 못한 문제가 발생할 수 있다.

3.5. 제어의 역전(IoC) 개념을 체감하면서, 프레임워크가 자동으로 처리해주는 것들을 정확히 이해하고 활용해야 한다는 점을 깨달았다.

4. 결론

FastAPI와 Spring은 각각 장단점이 있으며, 특정 기술을 선택할 때는 그 기술이 필요한 이유를 정확히 이해하는 것이 중요하다. FastAPI는 빠른 개발과 간결한 구조가 강점이었지만, 복잡한 비즈니스 로직을 다루고 대규모 트래픽을 처리하는 데는 Spring이 더 적합했다.

FastAPI에서 Spring으로 마이그레이션하던 중 다음과 같은 에러가 발생했다:

2024-12-31 10:08:03 WARN [http-nio-127.0.0.1-8000-exec-2] o.h.e.jdbc.spi.SqlExceptionHelper - SQL Error: 0, SQLState: 42804
2024-12-31 10:08:03 ERROR [http-nio-127.0.0.1-8000-exec-2] o.h.e.jdbc.spi.SqlExceptionHelper - ERROR: column "search_vector" is of type tsvector but expression is of type character varying
Hint: You will need to rewrite or cast the expression.

이 에러는 PostgreSQL의 tsvector 타입 컬럼(search_vector)에 character varying 타입 데이터를 직접 삽입하려 했기 때문에 발생했다. 기존 FastAPI 애플리케이션에서는 이러한 문제가 없었으나, Spring으로 마이그레이션하면서 이슈가 드러났다.

2. 원인 분석

PostgreSQL의 search_vector 컬럼은 전문 검색(Full Text Search)을 지원하기 위해 tsvector 타입으로 설정되어 있다. Spring JPA는 엔티티 매핑 시 이를 일반 문자열(character varying)로 처리하려고 시도하였고, 타입 불일치로 인해 SQL 오류가 발생했다.

3. 해결 방법

3.1. 애플리케이션에서의 접근 방식

처음에는 애플리케이션 계층에서 search_vector 값을 적절히 변환하거나 삽입을 방지하려는 접근을 고려했다. 하지만 다음과 같은 이유로 더 적합한 방식은 아니라고 판단했다:

• 애플리케이션 계층에서 변환 로직 추가 시 코드 복잡도가 증가.
• 데이터베이스에 가까운 로직은 데이터베이스에서 처리하는 것이 유지보수성과 성능 측면에서 더 유리.

3.2. 데이터베이스 트리거를 활용한 해결

PostgreSQL 트리거를 사용하여 search_vector 값을 자동으로 업데이트하도록 설정했다. 이를 통해 애플리케이션 계층에서는 search_vector 컬럼을 업데이트하지 않고도 데이터베이스가 알아서 처리하도록 만들었다.

4. 트리거 설정

4.1. 트리거 함수 정의

CREATE FUNCTION users_search_vector_trigger() RETURNS trigger AS $$
BEGIN
    NEW.search_vector := to_tsvector('english', 
        COALESCE(NEW.username, '') || ' ' || 
        COALESCE(NEW.email, '')
    );
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

4.2. 트리거 생성

CREATE TRIGGER users_search_vector_update
    BEFORE INSERT OR UPDATE ON users
    FOR EACH ROW
EXECUTE FUNCTION users_search_vector_trigger();

이 트리거는 users 테이블에 데이터가 삽입되거나 업데이트될 때마다 search_vector 컬럼을 자동으로 갱신한다.

5. 애플리케이션 계층 변경

5.1. search_vector 필드의 업데이트 방지

Spring JPA에서 search_vector 컬럼이 애플리케이션에서 수정되지 않도록 아래와 같이 설정한다:

@Column(name = "search_vector", columnDefinition = "tsvector", updatable = false)
private String searchVector;

5.2. 업데이트 로직 수정

@Transactional
public UserResponse updateUser(int userId, UserUpdate request) {
    User user = userRepository.findById(userId)
    .orElseThrow(() -> new CommonException(ErrorCode.USER_NOT_FOUND));

    if (request.getPassword() != null) {
        request = UserUpdate.builder()
                ...
                ...
    }

    user.update(request);
    return userMapper.mapToDTO(user);
}

이제 search_vector 필드는 애플리케이션 코드에서 업데이트되지 않으며, 데이터베이스에서 트리거로 자동 처리된다.

6. 이점

6.1. 데이터 일관성 보장

• 모든 데이터 변경이 데이터베이스 계층에서 일관되게 처리된다.
• 애플리케이션 로직의 실수나 누락으로 인한 문제를 방지한다.

6.2. 성능 최적화

• search_vector 갱신 로직이 데이터베이스 내부에서 처리되어 네트워크 오버헤드가 감소한다.
• PostgreSQL의 전문 검색 인덱스(GIN 또는 GiST)와 결합해 성능을 극대화할 수 있다.

6.3. 코드 단순화

• 애플리케이션 코드에서 불필요한 로직을 제거하여 가독성과 유지보수성이 향상된다.

7. 결론

이번 문제 해결 과정에서 중요한 것은 올바른 접근 방식을 선택하는 것이었다. 처음에는 Spring 애플리케이션에서 모든 것을 해결하려 했지만, 과감하게 데이터베이스 레벨의 해결책으로 방향을 전환했다.

PostgreSQL 트리거를 활용한 해결책은 단순히 문제를 해결하는 것을 넘어, 시스템 전체의 품질을 향상시켰다. 코드는 더 간결해졌고, 성능은 개선되었으며, 유지보수도 더 쉬워졌다.

이 경험은 문제를 한 걸음 뒤로 물러서서 바라보고, 빠르게 실행하며 개선하는 과정의 중요성을 다시 한 번 상기시켜 주었다. 현재 정식 출시 전이지만, 이러한 접근은 더 나은 시스템을 만들고 사용자에게 더 나은 서비스를 제공하는 기반이 될 것이다.

서비스의 유저 타입들은 @Inheritance(strategy = InheritanceType.JOINED)와 @DiscriminatorColumn을 사용하여 구분한다. 이때 필드를 중복 정의하면서 shadowing 문제가 발생했는데, 다음과 같은 현상이 나타났다:

1. Getter와 toString() 메서드의 불일치
   • toString()에서는 부모 클래스의 firm 필드를 사용해 데이터를 출력.
   • getFirm() 메서드는 자식 클래스의 firm 필드를 참조하여 null을 반환.
2. 데이터 접근 불가 현상
   • 리플렉션으로 firm 필드 값을 직접 확인하면 데이터가 존재하지만, getter 메서드를 호출하면 null이 반환됨.
3. Entity Graph와 LAZY 로딩 설정 문제 없음
   • 데이터 접근 문제는 JPA 설정상의 문제 때문이 아니라, 필드 shadowing으로 인해 발생.

원인 분석

1. JPA 상속 구조 검토

• 부모 클래스(User)에는 이미 firm 필드가 정의되어 있음.
• 자식 클래스(LawyerUser)에서도 firm 필드를 중복 정의함으로써 shadowing 현상이 발생.

2. 필드 shadowing 현상

• JPA 엔티티에서 동일한 필드명을 부모와 자식 클래스에 정의하면 shadowing 문제가 발생한다. 이로 인해:
  • toString() 메서드는 부모 클래스의 firm 필드를 참조.
  • getFirm() 메서드는 자식 클래스의 firm 필드를 참조하여 초기화되지 않은 값을 반환.

User 클래스

@Getter
@Entity
@Table(name = "users", schema = "")
@Inheritance(strategy = InheritanceType.JOINED)
@DiscriminatorColumn(name = "dtype", discriminatorType = DiscriminatorType.STRING)
@DiscriminatorValue("general") // 기본값
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "id", nullable = false)
    private Integer id;
    ..
    ..

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "firm_id", nullable = true) // 소속 Firm
    private Firm firm;
}

문제 해결

수정 전 코드

@Entity
@DiscriminatorValue("layers")
@Table(name = "users_lawyer", schema = "lemon")
public class LawyerUser extends User {
@Column(name = "firm", length = 255)
private String firm; // 중복 정의된 필드

@Column(name = "license_number", length = 100)
private String licenseNumber;

@Column(name = "license_file", length = 255)
private String licenseFile;

@Column(name = "firm_phone", length = 20)
private String firmPhone;
}

해결책

• 중복 정의된 firm 필드 제거: 부모 클래스(User)에서 정의된 firm 필드를 그대로 사용하도록 변경.

수정 후 코드

@Entity
@DiscriminatorValue("layers")
@Table(name = "users_lawyer", schema = "lemon")
public class LawyerUser extends User {

@Column(name = "license_number", length = 100)
private String licenseNumber;

@Column(name = "license_file", length = 255)
private String licenseFile;

// firm 필드 제거 - 이미 User 클래스에 정의되어 있음

@Column(name = "firm_phone", length = 20)
private String firmPhone;
}

경험을 통해 배운 점

1. JPA 상속 관계 설계 시 주의점
   • 부모 클래스의 필드를 자식 클래스에서 중복 정의하지 않도록 주의해야 한다.
   • 엔티티 구조를 설계할 때, 상속 계층 구조를 꼼꼼히 검토하는 것이 중요하다.
2. 디버깅의 중요성
   • 처음에는 JPA 프록시나 Lombok 관련 문제로 오해했지만, 디버깅을 통해 문제의 본질을 파악할 수 있었다.
   • Reflection API를 활용해 필드 값과 실제 타입을 확인한 것이 문제 해결에 큰 도움이 되었다.
3. JPA와 객체 지향 설계 원칙의 조화
   • 상속 구조를 설계할 때, 객체 지향 원칙뿐만 아니라 JPA의 동작 방식도 함께 고려해야 한다.

마무리

이번 문제는 단순히 코드 수정에 그치지 않고, 설계의 중요성을 다시 돌아보는 계기가 되었다. 처음에는 원인을 찾는 데 어려움을 겪었고, 문제의 본질을 파악하기 위해 디버깅과 가설 검증을 반복하며 꽤 오랜시간이 걸렸다. JPA 프록시 문제나 설정 오류로 오인하며 여러 단계를 거쳤지만, 결국 중복 정의된 필드가 원인임을 발견했다.

문제 해결 후에는 "생각보다 간단하네"라는 허무함이 들었다. 그러나 이 과정을 통해 설계의 작은 실수가 데이터 접근과 동작에 얼마나 큰 영향을 미칠 수 있는지 실감했다.

추가 설명

Shadowing 문제는 상위 클래스(부모)와 하위 클래스(자식) 간에 같은 이름의 필드나 변수가 정의될 때 발생하는 문제. 하위 클래스에서 같은 이름의 필드를 다시 정의하면, 이 필드가 상위 클래스의 필드를 가리게(덮어씌우게) 된다. 결과적으로, 상위 클래스의 필드에 접근하려고 해도 하위 클래스의 필드가 대신 사용된다.

이 현상은 JPA뿐만 아니라 일반적인 객체 지향 프로그래밍에서도 발생할 수 있으며, 다음과 같은 부작용을 초래한다

• 혼란: 코드가 의도한 대로 동작하지 않거나, 어떤 필드가 참조되고 있는지 명확하지 않음.
• 디버깅 어려움: 문제의 원인이 shadowing인지, 설정 문제인지 파악하기 어려움.
• 데이터 불일치: 읽기와 쓰기가 서로 다른 필드를 참조하면서 데이터가 일관되지 않게 됨.

해결 방법은 중복 정의를 피하고, 명확한 설계를 통해 하나의 필드만 사용하도록 하는 것

현재 회사의 API 서버는 FastAPI로 구현되어 있으며, AI 요청은 비동기 방식으로 처리하고 있다. 하지만 동시 요청이 늘어날 경우 Celery와 Redis 구조로도 한계가 있을 것으로 판단했다. 특히 회사의 비전이 B2C에서 B2B까지 확장되는 상황이므로, 더 커지기 전에 서버를 나누는 방향으로 구조 전환을 결정했다. 이번 전환에서 중요한 점은 빠른 개발 속도와 QA 병행이었다. 이를 위해 최대한 단순하고 직관적인 폴더 구조를 잡았다.

폴더 구조의 목적과 이유

폴더 구조를 설계하면서 가장 중요하게 생각한 점은 생산성과 명확성이다.

• 생산성: 새로운 기능을 빠르게 추가하고, 유지보수가 용이해야 한다.
• 명확성: 팀원들이 코드의 역할과 위치를 바로 이해할 수 있어야 한다.

폴더 구조

📁 config: 설정 관련 파일 (보안, CORS, DB 등)

📁 controller: API 요청 처리

📁 dto

• 📂 request : 요청 DTO
• 📂 response : 응답 DTO
• 📂 mapper : DTO ↔ Entity 변환

📁 exception: 예외 처리

📁 filter: 필터 및 인터셉터

📁 gateway: 외부 API 연동 및 게이트웨이

📁 model

• 📂 entity : DB 테이블과 매핑되는 클래스
• 📂 vo : 값 객체 또는 불변 객체
• 📂 enums : 상태값 및 타입 정의

📁 repository: 데이터베이스 접근

📁 service: 비즈니스 로직

📁 utils: 공통 유틸리티 클래스

📄 LemonApiServerSpringApplication.java: 메인 실행 클래스

결론

물론 이게 최선의 구조는 아닐 수 있다. DDD, 클린 아키텍처, 헥사고날 아키텍처와 같은 패턴이 존재하지만 상황에 맞게 구조를 잡는 것이 더 중요하다고 생각한다.

처음부터 API 서버와 AI 서버를 나누었다면 더 깔끔했을 수 있겠지만, 당시에는 MVP가 명확하지 않았다. 중간 점검을 통해 아키텍처를 조금 더 일찍 트래킹했으면 좋았을 것 같다는 아쉬움이 남는다.

다만 지금의 구조는 생산성과 명확성에 집중했고, 빠르게 대응하면서도 확장 가능한 첫걸음이 되리라 믿는다. 앞으로 상황에 맞게 조금씩 리팩토링 해봐야겠다.