🚀 Project Nexus

Project Nexus는 마이크로서비스 아키텍처를 기반으로 한 주문-재고 관리 시스템입니다.

📋 프로젝트 개요

이 프로젝트는 분산 시스템의 핵심 패턴과 모범 사례를 구현한 MVP입니다:

• Saga 패턴 (Choreography): 이벤트 기반 서비스 간 통신
• Transactional Outbox: 메시지 손실 방지
• 비관적 잠금: 재고 정합성 보장
• 멱등성 보장: 중복 요청 방지
• Rate Limiting: API 보호
• DLT (Dead Letter Topic): 실패한 메시지 처리

🏗️ 아키텍처

┌─────────────┐         ┌──────────────┐
│ Order       │────────▶│  PostgreSQL  │
│ Service     │         │  (Order DB)  │
└──────┬──────┘         └──────────────┘
       │
       │ OrderCreatedEvent
       ▼
┌─────────────┐         ┌──────────────┐
│   Kafka     │         │  PostgreSQL  │
│             │         │ (Inventory)  │
└──────┬──────┘         └──────────────┘
       │                      ▲
       │ StockReservedEvent   │
       │ /FailedEvent         │
       ▼                      │
┌─────────────┐               │
│ Inventory   │───────────────┘
│ Service     │
└─────────────┘

🚀 빠른 시작

사전 요구사항

• Java 21 (LTS)
• Docker & Docker Compose
• Gradle 8.9 (또는 Gradle Wrapper 사용)

로컬 실행

1. 인프라 시작

cd Nexus
docker compose up -d

이 명령은 다음 서비스를 시작합니다:

• PostgreSQL 16 (Order DB: 5432, Inventory DB: 5433)
• Apache Kafka 3.8.0 (9092)
• Redis 7.2.x (6379)

2. 서비스 빌드 및 실행

# Order Service
cd Nexus/order-service
../gradlew bootRun

# Inventory Service (새 터미널)
cd Nexus/inventory-service
../gradlew bootRun

3. API 테스트

# 주문 생성
curl -X POST http://localhost:8080/orders \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-key-123" \
  -d '{
    "customerId": "customer-001",
    "items": [
      {
        "productId": "PROD-001",
        "quantity": 2
      }
    ]
  }'

# 주문 조회
curl http://localhost:8080/orders/1

📁 프로젝트 구조

NexusProject/
├── Nexus/
│   ├── order-service/          # 주문 서비스
│   ├── inventory-service/       # 재고 서비스
│   ├── compose.yaml            # Docker Compose 설정
│   └── performance-tests/      # K6 성능 테스트
├── Development_Guide.md        # 개발 가이드
├── Plan.md                     # 개발 계획
└── README.md                   # 이 파일

🧪 테스트

단위 테스트

cd Nexus
./gradlew test

성능 테스트

# K6 설치 필요
cd Nexus/performance-tests
k6 run k6-concurrency-test.js
k6 run k6-load-test.js

📊 모니터링

Prometheus & Grafana

docker compose -f Nexus/compose.yaml --profile monitoring up -d

• Prometheus: http://localhost:9090
• Grafana: http://localhost:3000 (admin/admin)

🔧 기술 스택

• Core: Java 21, Spring Boot 3.3.5
• Database: PostgreSQL 16
• Messaging: Apache Kafka 3.8.0
• Cache: Redis 7.2.x
• Build: Gradle 8.9
• Migration: Flyway 10.10.x
• Testing: Testcontainers 1.19.x
• Monitoring: Prometheus, Grafana

📚 문서

• Development Guide - 개발 환경 구성 가이드
• Plan - 4주 MVP 개발 계획
• RUNBOOK - 운영 가이드

🤝 기여

이 프로젝트는 학습 목적으로 작성되었습니다.

📄 라이선스

이 프로젝트는 교육 목적으로 제공됩니다.