#Clean Architecture

클린 아키텍처로 문서 분석 시스템을 구축하면서 내린 설계 결정들을 돌아봅니다. 잘한 것과 아쉬운 것을 솔직하게, 그리고 다시 만든다면 무엇을 바꿀지 이야기합니다.

상태, 카테고리, 날짜 범위, 도메인을 조합하는 복잡한 동적 검색 요구사항을 QueryDSL로 해결하고, 소프트 딜리트와 인덱스 설계까지 고민한 경험을 공유합니다.

외부 API 호출 실패를 조용히 삼키지 않고, Dead Letter Queue 패턴과 Google Chat 알림으로 운영 가시성을 확보한 경험을 공유합니다.

AI 분석 API의 느린 응답을 Reactor의 Flux 스트리밍으로 처리하고, AbstractApiClient 추상 클래스로 공통 관심사를 분리한 경험을 공유합니다.

Kafka, RabbitMQ, Redis Streams 중 Redis Streams를 선택한 이유와 트레이드오프, TransactionalEventListener로 데이터 정합성을 지키는 방법, Consumer Group으로 at-least-once를 보장하는 구조를 정리합니다.

파일 업로드/다운로드 설계에서 Presigned URL 방식을 선택한 이유와, FileStorage 인터페이스(Port)와 CephFileStorage(Adapter)로 기술 독립성을 확보한 과정을 정리합니다.

AnalysisStatus와 AnalysisStep Enum으로 분석 파이프라인의 상태 전이 규칙을 캡슐화한 설계를 소개합니다. 정보전문가 패턴과 상태 머신을 결합해 잘못된 상태 전이를 도메인 수준에서 차단하는 방법을 다룹니다.

Spring Boot 3.5 + Java 21 기반 문서 분석 시스템을 설계하면서 클린 아키텍처와 Gradle 멀티 모듈 구조를 선택한 이유와 그 과정을 정리했습니다.

공고 목록 3초 로딩과 151개 쿼리를 겪고, Repository를 Reader/Writer로 분리해 200ms까지 줄인 이야기

PG 연동 코드를 UseCase에 직접 넣었다가 테스트 불가능해진 뒤, 3계층으로 분리하고 에러 처리를 체계화한 이야기

OrderEntity에 비즈니스 로직을 넣었다가 테스트가 지옥이 되어, 도메인 모델을 따로 빼게 된 이야기

UseCase에 HTTP 호출을 직접 넣었다가 타임아웃이 트랜잭션을 롤백시킨 뒤, Port & Adapter로 분리한 이야기