이 프로젝트는 MSA(Microservice Architecture) 구조를 기반으로 한 풀필먼트 시스템으로, Kafka를 활용한 이벤트 기반 통신을 구현합니다. 각 도메인 서비스는 독립적인 마이크로서비스로 구성되어 있으며, Kafka 이벤트 토픽을 통해 비동기적으로 통신합니다.
프로젝트는 다음과 같은 5개의 모듈로 구성되어 있습니다:
- common: 공통 모듈 (Kafka 설정 등 공유 코드)
- order: 주문 서비스 (포트: 9001)
- stock: 재고 관리 서비스 (포트: 9002)
- delivery: 배송 서비스 (포트: 9003)
- return: 반품 및 알림 서비스 (포트: 9004)
- 주요 역할: 주문 생성, 주문 상태 관리 API 개발 및 DB 연동
- Kafka 역할: 주문 이벤트 프로듀서 및 주문 이벤트 컨슈머
- 담당 업무:
- 주문 생성 및 관리 API 구현
- 주문 상태 변경 시 이벤트 발행
- 다른 서비스의 이벤트 구독 및 처리
- 주요 역할: 재고 상태 관리, 재고 예약 로직 개발
- Kafka 역할: 재고 이벤트 프로듀서 및 재고 부족 알림 이벤트 컨슈머
- 담당 업무:
- 재고 관리 API 구현
- 주문 이벤트 구독 및 재고 예약 처리
- 재고 상태 변경 시 이벤트 발행
- 주요 역할: 배송 요청 API 개발, 배송 상태 추적 및 업데이트
- Kafka 역할: 배송 이벤트 프로듀서 및 배송 상태 이벤트 컨슈머
- 담당 업무:
- 배송 요청 처리 및 상태 관리
- 주문 이벤트 구독 및 배송 처리
- 배송 상태 변경 시 이벤트 발행
- 주요 역할: 반품/교환 처리 로직 개발 및 알림 서비스 구현
- Kafka 역할: 반품 이벤트 프로듀서 및 이벤트 기반 알림 컨슈머
- 담당 업무:
- 반품/교환 요청 처리
- 다양한 이벤트 구독 및 알림 발송
- 반품 상태 변경 시 이벤트 발행
시스템 내 주요 이벤트 흐름은 다음과 같습니다:
-
주문 생성 흐름:
- 주문 서비스: 주문 생성 → 주문 생성 이벤트 발행
- 재고 서비스: 주문 생성 이벤트 구독 → 재고 확인/예약 → 재고 상태 이벤트 발행
- 배송 서비스: 재고 확인 이벤트 구독 → 배송 준비 → 배송 상태 이벤트 발행
- 알림 서비스: 각 상태 이벤트 구독 → 고객 알림 발송
-
재고 부족 흐름:
- 재고 서비스: 재고 부족 확인 → 재고 부족 이벤트 발행
- 주문 서비스: 재고 부족 이벤트 구독 → 주문 상태 업데이트
- 알림 서비스: 재고 부족 이벤트 구독 → 고객 알림 발송
-
반품/교환 흐름:
- 반품 서비스: 반품 요청 접수 → 반품 이벤트 발행
- 주문 서비스: 반품 이벤트 구독 → 주문 상태 업데이트
- 재고 서비스: 반품 이벤트 구독 → 재고 업데이트
- 알림 서비스: 반품 처리 이벤트 구독 → 고객 알림 발송
- order
- return
- 언어: Kotlin
- 프레임워크: Spring Boot 3.2.0
- 빌드 도구: Gradle (Kotlin DSL)
- 메시지 브로커: Apache Kafka
- Java 버전: JDK 17
- JDK 17
- Gradle 8.x
- Docker (Kafka 실행용)
Kafka는 Docker Compose를 통해 로컬 환경에서 실행할 수 있습니다:
# Kafka 실행 (별도의 docker-compose.yml 파일 필요)
docker-compose up -d각 서비스는 독립적으로 실행할 수 있습니다:
# 공통 모듈 빌드
./gradlew :common:build
# 각 서비스 실행
./gradlew :order:bootRun
./gradlew :stock:bootRun
./gradlew :delivery:bootRun
./gradlew :return:bootRun- 1번 팀원: 주문 서비스 담당
- 2번 팀원: 재고 관리 서비스 담당
- 3번 팀원: 배송 서비스 담당
- 4번 팀원: 반품 및 알림 서비스 담당
- 각자 맡은 도메인 서비스는 독립 마이크로서비스 형태로 구현 (각자 분리된 코드베이스/DB)
- Kafka 이벤트 토픽 기반 비동기 통신으로 서비스 간 데이터 연동 및 이벤트 전파
- 정기적인 통합 테스트로 메시지 흐름 최종 확인 및 장애 대응 시나리오 수행
- 역할 교차 학습을 위해 구현 중간에 프로듀서-컨슈머 역할과 API 호출 역할을 순환하며 수행 가능
- 각 서비스별 API 설계 및 이벤트 스키마 정의
- 서비스 내부 로직 구현 및 단위 테스트
- Kafka 프로듀서/컨슈머 구현
- 서비스 간 통합 테스트
- 장애 시나리오 테스트 및 대응 방안 수립
- 각 서비스별 단위 테스트
- 서비스 간 통합 테스트
- 장애 시나리오 테스트 (네트워크 단절, 서비스 다운 등)
- Kafka 토픽 모니터링
- 서비스 상태 모니터링
- 이벤트 흐름 추적
이 프로젝트는 일관된 코드 스타일을 유지하기 위해 EditorConfig와 ktlint를 사용합니다.
EditorConfig는 다양한 편집기와 IDE에서 일관된 코딩 스타일을 유지하는 데 도움을 줍니다. 프로젝트 루트에 있는 .editorconfig 파일에 정의된 규칙을 따릅니다.
주요 설정:
- 들여쓰기: 공백 사용
- 일반 파일: 2칸 들여쓰기
- Kotlin/Java 파일: 4칸 들여쓰기
- 최대 줄 길이: 140자
- UTF-8 인코딩
- 줄 끝 문자: LF (Line Feed)
- 파일 끝에 빈 줄 추가
- 후행 공백 제거
ktlint는 Kotlin 코드를 위한 정적 코드 분석 도구로, 코드 스타일을 검사하고 수정합니다. 이 프로젝트는 공식 Kotlin 코딩 컨벤션을 따릅니다.
ktlint는 Gradle 플러그인으로 설정되어 있으며, 다음 명령어로 사용할 수 있습니다:
# 코드 스타일 검사
./gradlew ktlintCheck
# 코드 스타일 자동 수정
./gradlew ktlintFormat- 공식 Kotlin 코딩 컨벤션 준수
- 와일드카드 임포트 사용 금지
- 클래스, 함수, 변수 등의 이름은 Kotlin 명명 규칙을 따름
- 클래스: PascalCase (예: OrderService)
- 함수/변수: camelCase (예: processOrder)
- 상수: UPPER_SNAKE_CASE (예: MAX_RETRY_COUNT)
- 들여쓰기는 4칸 사용
- 최대 줄 길이는 140자
- 후행 쉼표 사용 권장
- 중괄호 스타일: 같은 줄에 시작, 새 줄에 닫기
IntelliJ IDEA에서는 EditorConfig와 ktlint 플러그인을 설치하여 사용할 수 있습니다:
- EditorConfig 플러그인 설치 (기본 내장됨)
- ktlint 플러그인 설치 (Settings > Plugins > Marketplace에서 "ktlint" 검색)
- 코드 스타일 설정 (Settings > Editor > Code Style > Kotlin)에서 "Set from..." > "EditorConfig" 선택
VS Code에서는 다음 확장을 설치하여 사용할 수 있습니다:
- EditorConfig for VS Code
- Kotlin Language Server
- ktlint (선택 사항)
코드 리뷰 시 다음 사항을 확인합니다:
- ktlint 검사 통과 여부
- 코딩 컨벤션 준수 여부
- 명명 규칙 준수 여부
- 주석 및 문서화 적절성