mainlib990의 개인 보고서

[mainlib990]

0. 개발 회고 요약 (Executive Summary)

이번 프로젝트에서 리뷰(Review) 도메인의 핵심 기능 개발 및 아키텍처 설계를 주도했습니다. 저의 기여는 다음 세 가지 핵심 영역으로 요약할 수 있습니다.

• 첫째, 유지보수성과 확장성을 고려한 아키텍처를 설계하고 구축했습니다.

  • 복잡한 Review 도메인의 문제를 해결하기 위해, Persistence Model과 Domain Model을 분리하는 것을 시작으로 Hexagonal Architecture를 도입했습니다. 이를 통해 비즈니스 로직의 순수성을 확보하고, 외부 기술 변화에 유연하게 대처할 수 있는 기반을 마련했습니다. 또한, CQRS, 이벤트 기반 처리, 스냅샷 패턴 등을 적용하여 시스템의 확장성과 안정성을 크게 향상시켰습니다.

• 둘째, 기술적 난제를 해결하며 팀의 성장을 이끌었습니다.

  • '갱신 손실(Lost Update)'이 발생할 수 있는 치명적인 동시성 이슈를 발견하고, 다이어그램과 CLI 시연을 통해 팀의 이해를 도우며 해결책(스키마 분리, 비관적 락) 도입을 주도했습니다.
  • UUID 기본 키 사용 시 발생할 수 있는 데이터베이스 인덱스 파편화 문제를 지적하고, created_at 기반의 클러스터형 인덱스 생성을 제안하는 등 팀의 데이터베이스 성능에 대한 이해도를 높이는 데 기여했습니다.

• 셋째, 실용적인 엔지니어링과 미래에 대한 깊은 고찰을 병행했습니다.

  • 대규모 아키텍처 리팩토링 중에는 TDD가 비효율적임을 인지하고, 테스팅 트로피 전략과 블랙박스 테스트 관점을 팀에 제안하며 실용적인 테스트 접근법을 공유했습니다.
  • 팀의 현재 역량과 프로젝트 제약(Java 버전, 공통 모듈 수정 제약)을 고려하여 Optimistic Locking, 비동기 처리, Reactive 프로그래밍 모델 등의 이상적인 기술들을 무리하게 도입하지 않는 대신, 그 필요성과 장단점을 명확히 정리하여 미래 개선 과제로 제시하는 성숙하고 책임감 있는 자세를 견지했습니다.

이 보고서는 위와 같은 저의 고민과 경험, 그리고 프로젝트의 성과와 향후 발전 방향을 상세히 기술합니다.

---

1. 담당한 작업

프로젝트 내에서 리뷰(Review) 도메인의 핵심 기능 구현을 담당했습니다. 여기에는 리뷰 작성, 조회, 수정, 삭제의 CRUD 기능과 리뷰 좋아요(Like) 기능이 포함됩니다. 기능 구현을 넘어, 복잡한 비즈니스 요구사항을 체계적으로 관리하고 향후 확장성을 고려한 아키텍처 설계를 주도했습니다. 단, 리뷰 모듈 내의 스케줄러(Scheduler) 및 배치(Batch) 처리 부분은 저의 담당 범위에 포함되지 않았습니다.

2. 기술적 성과

단순한 기능 완성을 넘어, 유지보수성과 확장성을 극대화하는 엔지니어링 설계에 집중했으며, 이는 다음의 기술적 성과로 이어졌습니다.

• DDD(도메인 주도 설계) 기반의 비즈니스 로직 중심 개발

  • 복잡한 리뷰 도메인을 효과적으로 관리하기 위해 DDD 방법론을 전면적으로 적용했습니다. Persistence Model과 Domain Model의 분리 필요성을 강하게 느껴 이 둘을 분리했으며, Domain Model은 Rich Model로, Persistence Model은 Anemic Model로 설계했습니다. Aggregate Root를 사용하여 자식 엔티티와의 무결성을 보장하며, Value Objects (예: ReviewRatingDomain)를 적극 활용하여 도메인 로직 수행 전 유효성 검사를 확실히 했습니다.

• Hexagonal Architecture를 통한 유연한 설계

  • Persistence/Domain Model 분리 원칙은 자연스럽게 Hexagonal Architecture 도입의 시발점이 되었습니다. 핵심 비즈니스 로직(Application Core)이 외부 환경(UI, DB, 외부 API)의 변화에 영향을 받지 않도록 Port와 Adapter 패턴을 적극 도입했습니다.
  • UseCase Port를 통해 애플리케이션 코어로의 접근점을 만들었으며, Application Service와 Domain Service의 역할을 명확히 구분했습니다. Application Service는 서비스 오케스트레이션과 Fail-Fast Principle을 적용한 유효성 검증을 담당했고, Domain Service는 순수 비즈니스 로직에 집중하도록 했습니다.
  • 다른 모듈의 도메인과 상호작용 시, Anti-Corruption Layer (ACL)를 두어 외부 도메인 모델이 내 도메인에 영향을 주지 않도록 분리하고 안전하게 로직을 수행했습니다.

• CQRS(Command Query Responsibility Segregation)를 고려한 확장성 확보

  • 쓰기(Command)와 읽기(Query) 작업의 책임을 분리하는 CQRS 패턴을 설계에 적용했습니다. ReviewCommandService와 ReviewQueryService를 분리하여 각 작업의 복잡도를 낮추고, 추후 읽기/쓰기 작업의 부하에 따라 독립적으로 최적화 및 확장할 수 있는 기반을 다졌습니다.

3. 문제점 및 해결 과정 (STAR 기법 적용)

• Situation (상황):
  Review 모듈은 도서, 사용자 등 다른 여러 모듈과 상호작용이 많아 프로젝트 내에서 가장 복잡한 도메인 중 하나였습니다. 초기 단계에서 JPA의 @Entity를 도메인 모델로 그대로 사용할 경우, Persistence 로직(JPA 어노테이션)과 순수 비즈니스 로직이 한 클래스에 뒤섞여 코드 복잡도가 급격히 증가하고 장기적인 유지보수가 극도로 어려워질 것이라 판단했습니다. 또한, Like 기능이나 통계(ReviewStat) 처리와 같이 강한 일관성이 필수는 아닌 비핵심 로직들이 메인 트랜잭션에 엮여 시스템 전반의 확장성을 저해할 우려가 있었습니다.

• Task (과제):
  향후 기능 추가 및 변경이 용이하고, 시스템 전반의 확장성을 확보하며, 복잡한 비즈니스 규칙을 체계적으로 관리할 수 있는 Review 모듈을 설계하는 것이 목표였습니다.

• Action (행동):

  1. Persistence Model과 Domain Model 분리 및 Hexagonal Architecture 도입:

     • JPA @Entity와 비즈니스 로직의 혼재 문제를 해결하기 위해, Persistence Model과 Domain Model을 명확히 분리했습니다. Domain Model은 Rich Domain Model로 설계하여 비즈니스 로직을 포함하고, Persistence Model은 Anemic Domain Model로 단순한 데이터 저장소 역할을 하도록 했습니다.
     • 이러한 모델 분리 원칙은 자연스럽게 Hexagonal Architecture로의 전환을 유도했습니다. Port와 Adapter 패턴을 통해 애플리케이션 코어와 외부 인프라의 의존성을 역전시켜 비즈니스 로직이 외부 기술에 종속되지 않도록 했습니다.
     • 아키텍처 경계 강화를 위한 스냅샷 패턴 적용: Application Service가 Port를 통해 Adapter로 데이터를 전달할 때, 라이브 도메인 객체 대신 불변(Immutable) 스냅샷(Snapshot)을 전달하도록 설계했습니다. 이는 Adapter 계층에서 개발자의 실수로 인해 핵심 비즈니스 로직 수행이 끝난 도메인 객체의 상태가 변경되는 것을 원천적으로 방지하여 시스템의 안정성과 데이터 일관성을 크게 향상시켰습니다.

  2. Like 기능 및 통계 처리 분리 설계:

     • Like 기능은 즉각적인 동기화 처리가 불필요하며, 향후 다른 기술 스택(예: Redis)으로 전환 가능성이 높은 비중요 모듈임을 인지했습니다. 이에 Review의 핵심 비즈니스 로직과 분리하여 최종적 일관성(Eventual Consistency)을 가질 수 있도록 설계했습니다.
     • 유사하게, ReviewStat과 같은 통계 데이터 처리 역시 강한 일관성을 요구하지 않으므로, 추후 별도 모듈로 분리될 수 있도록 염두에 두고 설계를 진행했습니다.
     • 이러한 모듈 간 의존성을 줄이고 확장성(Scalability) 이점을 얻기 위해 이벤트 기반 아키텍처를 활용하여 변경 사항을 전파하도록 했습니다. (현재는 common 모듈 변경에 대한 제약으로 동기적 이벤트 발행 방식을 채택했습니다.)

• Result (결과):

  • 유지보수성 및 가독성 향상: 각 계층과 서비스의 역할이 명확해져 코드의 의도를 파악하기 쉬워졌고, 비즈니스 요구사항 변경 시 수정 범위가 최소화되었습니다.
  • 테스트 용이성 확보: Domain Model과 Domain Service가 특정 기술에 의존하지 않는 순수 POJO가 됨에 따라, 빠르고 안정적인 단위 테스트 작성이 가능해졌습니다.
  • 높은 확장성 및 유연성: 외부 환경 변화에 강건하며, Like나 통계와 같은 비핵심 기능들이 메인 비즈니스 로직에 부담을 주지 않는 확장성 있는 구조를 구축했습니다. common 모듈 수정 제약으로 인한 동기적 이벤트 발행 방식은 아쉬운 점으로 남았으나, 이는 현 프로젝트 상황을 고려한 실용적인 결정이었습니다.

4. 협업 및 피드백

프로젝트의 목표가 '과정보다 결과에 집중'이었기에, 매 PR마다 코드 리뷰를 진행하기보다는 전체적인 그림을 맞추고 주요 기술적 난제를 함께 해결하는 데 집중했습니다.

• 동시성 문제 해결을 위한 기술 논의 주도

  • 프로젝트 초기에 여러 사용자가 동시에 데이터를 수정할 때 '갱신 손실(Lost Update)'이 발생할 수 있는 동시성 이슈를 발견했습니다. 이 문제의 심각성과 해결의 필요성을 팀원들에게 설득하기 위해, 다이어그램을 그려가며 트랜잭션 처리 과정의 문제점을 시각적으로 설명하고, CLI를 통해 실제 데이터가 손실되는 시나리오를 직접 시연했습니다.
  • 단순히 문제 제기에 그치지 않고, JPA의 영속성 컨텍스트(Persistence Context) 캐싱 메커니즘과 트랜잭션 고립성 레벨(Isolation Level)과 같은 근본적인 개념을 함께 설명하며 팀의 공감대를 형성했습니다.
  • 구체적인 해결책으로, 중간 상태 관리를 위한 스키마 분리와 비관적 락(Pessimistic Lock)의 적용을 제안했습니다. 스키마 분리를 통해 락의 범위를 최소화하여 동시성을 확보하면서도 데이터 일관성을 지킬 수 있음을 논리적으로 증명했고, 팀은 이 제안을 받아들였습니다. 이 과정을 통해 시스템의 일관성과 확장성을 동시에 향상시키는 중요한 성과를 거두었습니다.

• 데이터베이스 성능 향상을 위한 지식 공유 및 논의 주도

  • 팀원들과 함께 데이터베이스 인덱싱에 대한 심도 있는 논의를 주도했습니다. 많은 테이블에서 관습적으로 사용되던 UUID 기본 키가 클러스터형 인덱스(Clustered Index)로 자동 설정될 경우, 데이터의 물리적 저장 순서가 무작위가 되어 심각한 인덱스 파편화와 쓰기 성능 저하를 유발함을 지적했습니다.
  • 이에 대한 구체적인 해결책으로, UUID 기본 키에 클러스터형 인덱스를 설정하는 대신, 순차적으로 증가하는 created_at 컬럼을 기준으로 클러스터형 인덱스를 생성해야 한다고 제안했습니다. 이를 통해 새로운 데이터가 항상 테이블의 끝에 추가되도록 하여 쓰기 성능을 최적화하는 방법을 공유했습니다.
  • 개인적으로는 이 주제에 대해 더 깊이 고찰하고 체계적으로 학습한 후 실제 코드에 적용해보고자, 이번에는 지식 공유와 제안에 집중했습니다.

5. 테스트 전략 및 고찰

• 테스팅 트로피(Testing Trophy) 전략 채택: 팀 논의를 통해, 단위 테스트보다는 통합 테스트와 E2E 테스트에 더 집중하여 높은 신뢰도를 가진 테스트 코드를 효율적으로 작성하는 '테스팅 트로피' 전략을 채택했습니다.
• 의도된 테스트 작성 지연: 제가 담당한 Review 모듈은 초기 레이어드 아키텍처에서 Hexagonal 아키텍처로 전환하는 등 구조적인 변경이 매우 클 것으로 예상되었습니다. 이러한 대규모 리팩토링 중에는 TDD 방식이 비효율적이며, 잦은 구현 변경으로 인해 테스트 코드가 계속해서 깨지는 문제를 야기할 것이라 판단했습니다. 이에, 아키텍처가 안정화될 때까지 테스트 코드 작성을 의도적으로 미루는 실용적인 접근을 선택했습니다.
• 테스트 전략 가이드: 비록 직접 많은 테스트를 작성하지는 못했지만, 팀원들에게 테스트 전략을 지속적으로 공유하고 가이드했습니다. 먼저 API 레벨에서 블랙박스 테스트(Black-box testing) 관점으로 접근하여, 내부 구현을 전혀 알지 못한 채 오직 입출력만 검증하는 E2E 테스트(ReviewTest.java 참고)를 작성하자고 제안했습니다. 이를 통해 핵심 기능의 동작을 보장함과 동시에, 중간 계층을 참조하지 않아 내부 리팩토링에 깨지지 않는 견고한 테스트를 만들 수 있었습니다. E2E로 커버하기 어려운 예외 처리 등은 통합 테스트로 보완하는 방향을 제시했습니다.
• 아쉬운 점 및 향후 계획: 결과적으로 시간 부족으로 인해 충분한 테스트 코드를 작성하지 못한 점은 아쉬움으로 남습니다. 만약 시간이 충분했다면, 제안했던 전략에 따라 모든 Happy Path를 E2E 테스트로 커버하고, 예외 처리 로직 등을 통합 테스트로 보완하여 코드 커버리지와 안정성을 크게 높였을 것입니다.

6. 코드 품질 및 최적화

• 가독성 및 유지보수성: DDD와 Hexagonal Architecture의 도입, 그리고 VO의 적극적인 활용은 코드의 의도를 명확하게 하고 각 객체의 책임을 분리하여 전반적인 코드 품질을 크게 향상시켰습니다. 특히, 엔티티 생성 시 Fluent API 스타일을 적용하여 가독성을 높이고, 비즈니스 로직의 복잡성을 관리하여 향후 유지보수 비용을 절감하는 데 크게 기여했습니다.
• 성능 최적화 기반 마련: CQRS 패턴을 설계에 적용함으로써, 향후 읽기 전용 저장소(Read-Only Replica) 분리, 캐싱 전략 도입 등 다양한 성능 최적화 기법을 적용할 수 있는 확장 가능한 구조를 마련했습니다.

7. 향후 개선 사항 및 제안

• Hexagonal Architecture의 점진적 확대: 제가 담당한 모듈에 성공적으로 적용된 Hexagonal Architecture를, 향후 개발될 다른 복잡한 도메인 모듈에도 점진적으로 확대 적용할 것을 제안합니다. 단, 모든 모듈에 강제하기보다는, 복잡도와 팀의 상황을 고려한 실용적인 접근이 필요합니다. 제가 package-by-feature 형태로 패키지 구조를 설계한 것은, 이러한 점진적 전환 및 향후 MSA로의 발전을 용이하게 하기 위함이었습니다.

• 이벤트 기반 아키텍처 고도화 (비동기 및 Black-Box 패턴 적용):

  • 현재는 common 모듈 변경에 대한 제약으로 인해 동기적 이벤트 발행 방식을 채택했습니다. 하지만 장기적으로는 메시지 브로커(예: 메시지 큐 또는 이벤트 스트리밍 플랫폼)를 도입하여 이벤트를 비동기적으로 처리하고, 발행자와 구독자 간의 의존성을 완전히 분리하는 Black-Box 패턴을 적용할 것을 제안합니다. 이는 시스템의 처리량을 극대화하고, 장애 격리 및 시스템 회복탄력성을 크게 향상시킬 수 있습니다.

• CQRS 아키텍처의 물리적 분리:

  • 현재 논리적으로 분리된 CQRS를, 향후 트래픽 증가 시 물리적으로 분리하는 것을 제안합니다. Command와 Query가 사용하는 데이터베이스를 분리하여 각 작업의 부하를 완전히 격리하고 시스템의 전반적인 안정성과 성능을 향상시킬 수 있습니다.

• Optimistic Locking 도입을 통한 동시성 제어 개선:

  • 현재는 팀의 개념적 이해도 차이를 고려하여 도입하지 않았지만, 데이터베이스 부하를 줄이고 애플리케이션의 확장성을 높이는 데 Optimistic Locking이 매우 효과적입니다. 동시성 제어의 책임을 데이터베이스에서 애플리케이션으로 옮김으로써, 고성능 및 고가용성 시스템 구축에 기여할 수 있습니다. 장기적으로 팀원들의 학습과 논의를 거쳐 도입을 검토할 것을 제안합니다.

• 장기적인 아키텍처 진화 방향: Reactive 프로그래밍 모델 도입 검토:

  • 현재 Application Service 계층에서 발생하는 다수의 블로킹 I/O 작업은 시스템의 잠재적인 병목 지점이 될 수 있습니다. 장기적으로는 Spring WebFlux와 같은 Reactive 프로그래밍 모델로의 전환을 제안합니다. 이는 한정된 리소스로 더 많은 동시 요청을 효율적으로 처리하여 시스템의 확장성을 크게 향상시킬 수 있습니다.
  • 다만, 이는 프로젝트 전체의 프로그래밍 패러다임을 바꾸는 중대한 변화이므로, 충분한 팀의 공감대 형성 및 학습 곡선을 고려한 단계적인 도입 전략이 필수적입니다.
  • 가상 스레드(Virtual Thread)는 기존 블로킹 모델의 단점을 완화하지만, 현재 Java 17 환경에서는 적용 불가능합니다. 또한, Virtual Thread는 경량 스레딩 모델이며, Reactive 모델이 제공하는 논블로킹 패러다임과는 근본적인 차이가 있습니다. 매우 높은 I/O 처리량이 요구되는 상황에서는 Reactive 모델이 더 효율적인 선택일 수 있음을 인지하고 있습니다.