이 프로젝트는 NestJS 프레임워크를 사용하여 구현된 배달 서비스 마이크로서비스 아키텍처입니다. 사용자 관리, 상품 관리, 주문 처리, 결제 처리, 알림 서비스 등 다양한 기능을 제공합니다. 이 애플리케이션은 확장성, 유지보수성, 그리고 장애 격리를 위해 마이크로서비스 패턴을 따르고 있습니다.
이 애플리케이션은 다음과 같은 마이크로서비스로 구성되어 있습니다:
- Gateway 서비스: API 게이트웨이로 모든 클라이언트 요청을 처리하고 적절한 마이크로서비스로 라우팅합니다. JWT 기반 인증을 처리하고 API 엔드포인트를 제공합니다.
- User 서비스: 사용자 관리 및 인증을 담당합니다. 사용자 등록, 로그인, 프로필 관리 기능을 제공합니다. PostgreSQL 데이터베이스를 사용합니다.
- Product 서비스: 상품 정보 관리를 담당합니다. 상품 목록 조회, 상세 정보 조회 기능을 제공합니다. PostgreSQL 데이터베이스를 사용합니다.
- Order 서비스: 주문 처리를 담당합니다. 주문 생성, 주문 상태 관리, 배송 정보 관리 기능을 제공합니다. MongoDB 데이터베이스를 사용합니다.
- Payment-Command 서비스: 결제 처리를 담당합니다. 결제 처리, 결제 상태 관리 기능을 제공합니다. PostgreSQL 데이터베이스를 사용하며, MongoDB도 함께 사용합니다.
- Payment-Query 서비스: 결제 정보 조회를 담당합니다. 결제 내역 조회 기능을 제공합니다. 개발 환경에서는 MongoDB를 사용하고, 프로덕션 환경에서는 PostgreSQL을 사용할 수 있도록 구성되어 있습니다.
- Notification 서비스: 알림 처리를 담당합니다. 주문 상태 변경, 결제 완료 등의 이벤트에 대한 알림을 처리합니다. MongoDB 데이터베이스를 사용합니다.
- 동기식 통신: 서비스 간 직접 통신은 gRPC 프로토콜을 사용하여 이루어집니다. 각 서비스는 proto 파일에 정의된 인터페이스를 통해 통신합니다.
- 비동기식 통신: 이벤트 기반 통신은 Kafka를 통해 이루어집니다. 이를 통해 서비스 간 느슨한 결합을 유지합니다.
- PostgreSQL: User, Product, Payment-Command 서비스에서 사용되며, 관계형 데이터를 저장합니다.
- MongoDB: Order, Notification, Payment-Query 서비스에서 사용되며, 문서 기반 데이터를 저장합니다. Payment-Command 서비스에서도 일부 데이터를 저장합니다.
- Redis: 캐싱 및 세션 관리에 사용됩니다.
- 백엔드 프레임워크: NestJS (Node.js 기반)
- 언어: TypeScript
- 패키지 매니저: pnpm v9.1.1
- 데이터베이스:
- PostgreSQL v16: 관계형 데이터 저장
- MongoDB v8: 문서 기반 데이터 저장
- 서비스 간 통신:
- gRPC: 동기식 서비스 간 통신
- Kafka v3.8.0: 비동기식 이벤트 기반 통신
- 캐싱: Redis
- 컨테이너화 및 오케스트레이션:
- Docker, Docker Compose: 로컬 개발 및 테스트
- Kubernetes: 프로덕션 배포
- Helm: Kubernetes 리소스 관리
- 인증 및 보안: JWT (JSON Web Tokens)
- 테스트: Jest
- Node.js (v16 이상)
- pnpm (v9.1.1 이상)
- Docker 및 Docker Compose
- Git
- 저장소 클론:
$ git clone <repository-url>
$ cd delivery- 의존성 설치:
$ pnpm install- 각 서비스의 환경 변수 설정:
envs/gateway/.env: API 게이트웨이 설정 (JWT 시크릿, 포트 등)envs/user/.env: 사용자 서비스 설정 (데이터베이스 연결 정보 등)envs/product/.env: 상품 서비스 설정 (데이터베이스 연결 정보 등)envs/order/.env: 주문 서비스 설정 (데이터베이스 연결 정보 등)envs/payment-command/.env: 결제 명령 서비스 설정 (데이터베이스 연결 정보 등)envs/payment-query/.env: 결제 조회 서비스 설정 (데이터베이스 연결 정보 등)envs/notification/.env: 알림 서비스 설정 (데이터베이스 연결 정보 등)
각 환경 변수 파일에는 다음과 같은 정보가 포함되어야 합니다:
- 데이터베이스 연결 정보 (호스트, 포트, 사용자 이름, 비밀번호, 데이터베이스 이름)
- gRPC 서버 설정 (호스트, 포트)
- 기타 서비스별 설정
# 개발 모드
$ pnpm run start
# 개발 모드 (변경 감지)
$ pnpm run start:dev
# 프로덕션 모드
$ pnpm run start:prod프로젝트에는 세 가지 Docker Compose 설정 파일이 있습니다:
- docker-compose.yml: 개발 환경을 위한 기본 설정 파일로, 소스 코드에서 직접 빌드합니다.
- docker-compose.image-test.yml: 미리 빌드된 Docker 이미지를 테스트하기 위한 설정 파일입니다.
- docker-compose.prod.yml: 프로덕션 환경을 위한 간소화된 설정 파일로, 외부 데이터베이스를 사용합니다.
모든 서비스와 데이터베이스를 한 번에 실행:
$ docker-compose up특정 서비스만 실행:
$ docker-compose up gateway user백그라운드에서 실행:
$ docker-compose up -d미리 빌드된 Docker 이미지를 테스트:
$ docker-compose -f docker-compose.image-test.yml up프로덕션 환경에서 실행:
$ docker-compose -f docker-compose.prod.yml up -d- Gateway API: http://localhost:3000
- 각 서비스는 내부 gRPC 포트를 통해 통신합니다.
- 데이터베이스 포트:
- PostgreSQL (User): 6001
- PostgreSQL (Product): 6002
- MongoDB (Order): 6003
- PostgreSQL (Payment-Command): 6005
- MongoDB (Payment-Command): 6010
- MongoDB (Payment-Query): 6011
- MongoDB (Notification): 6006
- Kafka:
- 내부 통신 포트: 9092
- 외부 접근 포트: 29092
# 단위 테스트
$ pnpm run test
# e2e 테스트
$ pnpm run test:e2e
# 테스트 커버리지
$ pnpm run test:covAPI 문서는 Postman 컬렉션으로 제공됩니다. docs/NestJS Microservice.postman_environment.json 파일을 Postman으로 가져와서 사용할 수 있습니다.
주요 API 엔드포인트:
- 인증:
/auth/register,/auth/login - 상품:
/product - 주문:
/order - 결제 명령:
/payment-command - 결제 조회:
/payment-query - 알림:
/notification
delivery-microservices-messaging/
├── .github/ # GitHub 관련 설정
├── .idea/ # IDE 설정 (JetBrains)
├── apps/ # 마이크로서비스 애플리케이션
│ ├── gateway/ # API 게이트웨이 (포트: 3000)
│ │ ├── src/ # 소스 코드
│ │ │ ├── auth/ # 인증 관련 코드
│ │ │ ├── health/ # 헬스 체크 관련 코드
│ │ │ ├── order/ # 주문 관련 코드
│ │ │ └── product/ # 상품 관련 코드
│ │ ├── .env # 개발 환경 변수
│ │ ├── prod.env # 프로덕션 환경 변수
│ │ └── Dockerfile # Docker 빌드 설정
│ ├── user/ # 사용자 서비스
│ │ ├── src/ # 소스 코드
│ │ │ ├── auth/ # 인증 관련 코드
│ │ │ └── user/ # 사용자 관련 코드
│ │ ├── .env # 개발 환경 변수
│ │ ├── prod.env # 프로덕션 환경 변수
│ │ └── Dockerfile # Docker 빌드 설정
│ ├── product/ # 상품 서비스
│ │ ├── src/ # 소스 코드
│ │ │ └── product/ # 상품 관련 코드
│ │ ├── .env # 개발 환경 변수
│ │ ├── prod.env # 프로덕션 환경 변수
│ │ └── Dockerfile # Docker 빌드 설정
│ ├── order/ # 주문 서비스
│ │ ├── src/ # 소스 코드
│ │ │ └── order/ # 주문 관련 코드
│ │ ├── .env # 개발 환경 변수
│ │ ├── prod.env # 프로덕션 환경 변수
│ │ └── Dockerfile # Docker 빌드 설정
│ ├── payment-command/ # 결제 명령 서비스
│ │ ├── src/ # 소스 코드
│ │ │ └── payment/ # 결제 관련 코드
│ │ ├── .env # 개발 환경 변수
│ │ ├── prod.env # 프로덕션 환경 변수
│ │ └── Dockerfile # Docker 빌드 설정
│ ├── payment-query/ # 결제 조회 서비스
│ │ ├── src/ # 소스 코드
│ │ │ └── payment/ # 결제 관련 코드
│ │ ├── .env # 개발 환경 변수
│ │ ├── prod.env # 프로덕션 환경 변수
│ │ └── Dockerfile # Docker 빌드 설정
│ └── notification/ # 알림 서비스
│ ├── src/ # 소스 코드
│ │ └── notification/ # 알림 관련 코드
│ ├── .env # 개발 환경 변수
│ ├── prod.env # 프로덕션 환경 변수
│ └── Dockerfile # Docker 빌드 설정
├── envs/ # 환경 변수 설정 파일
│ ├── gateway/ # 게이트웨이 환경 변수
│ ├── user/ # 사용자 서비스 환경 변수
│ ├── product/ # 상품 서비스 환경 변수
│ ├── order/ # 주문 서비스 환경 변수
│ ├── payment-command/ # 결제 명령 서비스 환경 변수
│ ├── payment-query/ # 결제 조회 서비스 환경 변수
│ └── notification/ # 알림 서비스 환경 변수
├── docs/ # 문서
│ ├── auth-login-scripts.md # 인증 및 로그인 스크립트 문서
│ ├── dockerhub_image_push.txt # Docker Hub 이미지 푸시 가이드
│ ├── NestJS Microservice.postman_environment.json # Postman 환경 설정
│ └── post_order.md # 주문 생성 관련 문서
├── k8s/ # 쿠버네티스 및 Helm 관련 설정
│ ├── delivery/ # 배달 서비스 쿠버네티스 설정
│ ├── helm/ # Helm 차트
│ ├── infra/ # 인프라 관련 설정
│ └── kubernetes/ # 쿠버네티스 기본 설정
├── libs/ # 공유 라이브러리
│ └── common/ # 공통 모듈
│ ├── src/ # 소스 코드
│ │ ├── const/ # 상수
│ │ ├── dto/ # 데이터 전송 객체
│ │ ├── grpc/ # gRPC 관련 코드
│ │ └── interceptor/ # 인터셉터
│ └── tsconfig.lib.json # TypeScript 설정
├── node_modules/ # 노드 모듈 (패키지 의존성)
├── postgres/ # PostgreSQL 데이터 디렉토리
│ ├── user/ # 사용자 서비스 데이터
│ ├── product/ # 상품 서비스 데이터
│ └── payment_command/ # 결제 명령 서비스 데이터
├── mongo/ # MongoDB 데이터 디렉토리
│ ├── order/ # 주문 서비스 데이터
│ ├── payment_command/ # 결제 명령 서비스 데이터
│ ├── payment_query/ # 결제 조회 서비스 데이터
│ └── notification/ # 알림 서비스 데이터
├── proto/ # gRPC 프로토콜 정의
│ ├── notification.proto # 알림 서비스 프로토콜
│ ├── order.proto # 주문 서비스 프로토콜
│ ├── payment.proto # 결제 서비스 프로토콜
│ ├── product.proto # 상품 서비스 프로토콜
│ └── user.proto # 사용자 서비스 프로토콜
├── .dockerignore # Docker 빌드 제외 파일
├── .eslintrc.js # ESLint 설정
├── .gitignore # Git 제외 파일
├── .prettierrc # Prettier 설정
├── build-and-push-ps.ps1 # PowerShell 스크립트 (Docker 이미지 빌드 및 푸시)
├── build-and-push.sh # Bash 스크립트 (Docker 이미지 빌드 및 푸시)
├── docker-compose.image-test.yml # Docker Compose 이미지 테스트 설정
├── docker-compose.prod.yml # Docker Compose 프로덕션 설정
├── docker-compose.yml # Docker Compose 개발 설정
├── nest-cli.json # NestJS CLI 설정
├── package.json # 프로젝트 메타데이터 및 의존성
├── pnpm-lock.yaml # pnpm 락 파일
├── README.md # 프로젝트 문서
├── run-docker-compose.ps1 # PowerShell 스크립트 (Docker Compose 실행)
├── tsconfig.build.json # TypeScript 빌드 설정
├── tsconfig.json # TypeScript 기본 설정
└── webpack.config.js # Webpack 설정
이 프로젝트는 서비스 간 비동기 통신을 위해 Kafka를 사용합니다. Kafka는 높은 처리량, 내구성, 확장성을 제공하는 분산 이벤트 스트리밍 플랫폼입니다.
개발 및 테스트 환경에서는 Docker Compose를 통해 Kafka가 자동으로 설정됩니다:
- Kafka 버전: 3.8.0 (Bitnami 이미지)
- 내부 통신 포트: 9092
- 외부 접근 포트: 29092
- KRaft 모드 활성화 (ZooKeeper 없이 실행)
- 주문 생성 → 결제 처리 → 알림 발송
- 결제 완료 → 주문 상태 업데이트 → 알림 발송
- 주문 상태 변경 → 알림 발송
각 서비스는 관련 이벤트를 생성하고 소비하여 느슨하게 결합된 마이크로서비스 아키텍처를 구현합니다.
프로젝트는 쿠버네티스 배포를 위한 설정 파일을 포함하고 있습니다. k8s/kubernetes 디렉토리에서 다음과 같은 쿠버네티스 리소스 예제를 확인할 수 있습니다:
- 파드 (Pod)
- 레플리카셋 (ReplicaSet)
- 디플로이먼트 (Deployment)
- 네임스페이스 (Namespace)
- 컨피그맵 (ConfigMap)과 시크릿 (Secret)
- 라이브니스 프로브 (Liveness Probe)와 레디니스 프로브 (Readiness Probe)
- 서비스 (NodePort, ClusterIP)
- 퍼시스턴트 볼륨 (PersistentVolume)과 퍼시스턴트 볼륨 클레임 (PersistentVolumeClaim)
또한 k8s/helm 디렉토리에서 Helm 차트를 통한 배포 예제를 확인할 수 있습니다. 실제 배포 설정은 k8s/delivery 디렉토리에서 확인할 수 있으며, 인프라 관련 설정은 k8s/infra 디렉토리에 있습니다.
- 이 저장소를 포크합니다.
- 새로운 브랜치를 생성합니다:
git checkout -b feature/your-feature-name - 변경 사항을 커밋합니다:
git commit -m 'Add some feature' - 포크한 저장소에 푸시합니다:
git push origin feature/your-feature-name - Pull Request를 생성합니다.
이 프로젝트는 MIT 라이센스를 따릅니다.