🔍 hello-search-api

ElasticSearch 기반의 E-commerce 상품 검색 API

📋 목차

개요
주요 기능
기술 스택
프로젝트 구조
아키텍처 특징
실행 방법
API 스펙
개발 가이드
주의사항
TODO

🎯 개요

hello-search-api는 ElasticSearch를 활용하여 다양한 조건의 상품 검색 기능을 제공하는 API 서버입니다.
전자상거래(E-commerce) 환경을 모델링하여, 실시간 이벤트 처리 및 고급 검색 기능을 제공합니다.

✨ 핵심 특징

🚀 빠른 검색: ElasticSearch 기반 실시간 검색
🔄 이벤트 기반: RabbitMQ를 통한 비동기 이벤트 처리
📊 실시간 집계: Redis 기반 판매량 실시간 집계
🇰🇷 한글 최적화: Nori Analyzer를 활용한 한글 형태소 분석
🎨 직관적인 API: Swagger UI를 통한 API 문서화

🛠 기술 스택

🎯 Backend

☕ Java 21
🍃 Spring Boot 3.4.2
🐘 Gradle 8.x

💾 Database & Storage

🐬 MySQL 8.x - JPA 기반 데이터 저장
🔍 ElasticSearch 8.x - 검색 엔진
🗄️ Redis - 데이터 집계 및 캐싱

📨 Message Queue

🐰 RabbitMQ - 이벤트 처리

📚 주요 라이브러리

Spring Data Elasticsearch
Spring Data JPA
Spring AMQP
Spring Security
SpringDoc OpenAPI
Jasypt
Lombok

📁 프로젝트 구조

hello-search-api/
├── 📦 presentation/          # 🎨 REST API Controllers & DTOs
│   ├── admin/               # 관리자 검색 API
│   ├── product/             # 상품 API
│   ├── banner/              # 배너 API
│   └── provider/            # 공급자 API
│
├── 🎯 application/           # 💼 비즈니스 로직 (Service Layer)
│   ├── admin/
│   ├── product/
│   ├── order/
│   ├── banner/
│   └── provider/
│
├── 🎲 domain/                # 🏛️ 도메인 모델
│   ├── entity/              # JPA 엔티티
│   ├── elastic/             # ElasticSearch Documents
│   └── rabbitmq/            # 메시지 객체
│
├── 🔧 infra/                 # ⚙️ 인프라 계층
│   ├── config/              # 설정 클래스
│   ├── repository/          # JPA Repository
│   ├── elasticrepository/   # ElasticSearch Repository
│   ├── consumer/            # RabbitMQ Consumer
│   ├── aggregator/          # 데이터 집계
│   └── batch/               # 배치 작업
│
└── HelloSearchApiApplication.java

✨ 주요 기능

🔎 검색 기능

기능	설명	기술
🔍 상품 검색	키워드, 가격 범위, 카테고리 필터링	Match Query, Range Query
💡 자동완성	실시간 추천어 제공	Prefix Query
🎯 유사 상품	상품 기반 추천	More Like This
🌐 통합 검색	상품/주문/배너/공급자 통합 검색	Bool Query
✨ 검색어 강조	결과 내 키워드 강조 표시	Highlight

🔄 이벤트 처리

주문 발생 → 🐰 RabbitMQ → 📥 Consumer → 🗄️ Redis 집계 → ⏰ Batch(1분) → 🔍 ElasticSearch

단계	설명	기술
1️⃣ 이벤트 수신	실시간 주문 이벤트 처리	RabbitMQ
2️⃣ 데이터 집계	판매량 실시간 집계	Redis HashOps
3️⃣ 배치 동기화	1분마다 ElasticSearch 동기화	Spring Scheduler

⚡ 검색 최적화

🇰🇷 한글 형태소 분석 - Nori Analyzer
🔗 통합 검색 필드 - combinedField (copyTo)
📊 정렬 & 페이징 - SortOption + from/size
🗑️ Soft Delete - 논리적 삭제 패턴

🚀 실행 방법

1️⃣ 사전 준비

필수 서비스
다음 서비스들이 실행되어 있어야 합니다:

서비스	버전	포트
🐬 MySQL	8.x	3306
🔍 ElasticSearch	8.x	9200
🗄️ Redis	latest	6379
🐰 RabbitMQ	latest	5672

2️⃣ 프로젝트 클론

git clone https://github.com/seunggulee1007/hello-search-api.git
cd hello-search-api

3️⃣ 환경 변수 설정

# 🔐 Jasypt 암호화 키 설정 (필수)
export JASYPT_PASSWORD=your_secret_key

# 🗄️ Redis 설정 (선택, 기본값: localhost:6379)
export REDIS_SERVER_HOST=localhost
export REDIS_SERVER_PORT=6379

4️⃣ application.yml 설정

⚠️ 보안 정보
민감한 정보는 Jasypt로 암호화되어 있습니다.

필요 시 다음 정보를 확인/수정하세요:

🐬 데이터베이스 연결 정보
🔍 ElasticSearch 연결 정보 (SSL 인증서 포함)
🐰 RabbitMQ 연결 정보

5️⃣ 프로젝트 빌드 및 실행

# 빌드
./gradlew clean build

# 실행
./gradlew bootRun

🎉 서버가 실행되었습니다!
서버: http://localhost:9998

6️⃣ API 문서 확인

📚 Swagger UI
http://localhost:9998/swagger-ui/index.html

📡 API 스펙

🛍️ 상품 검색 API

Method	Endpoint	Description
🔍 `GET`	`/api/v1/elastic/product`	상품 검색
💡 `GET`	`/api/v1/elastic/product/autocomplete`	자동완성
🎯 `GET`	`/api/v1/elastic/product/similar/{productId}`	유사 상품 검색
➕ `POST`	`/api/v1/elastic/product`	상품 저장
❌ `DELETE`	`/api/v1/elastic/product/{id}`	상품 삭제

👨‍💼 관리자 API

Method	Endpoint	Description
🌐 `GET`	`/api/v1/elastic/admin/all`	통합 검색 (상품/주문/배너/공급자)

🎨 배너 API

Method	Endpoint	Description
➕ `POST`	`/api/v1/elastic/banner`	배너 저장
❌ `DELETE`	`/api/v1/elastic/banner/{id}`	배너 삭제

🏢 공급자 API

Method	Endpoint	Description
➕ `POST`	`/api/v1/elastic/provider`	공급자 저장
❌ `DELETE`	`/api/v1/elastic/provider/{id}`	공급자 삭제

📝 API 호출 예시

1️⃣ 상품 검색

GET /api/v1/elastic/product?keyword=노트북&minPrice=1000000&maxPrice=3000000&page=1&size=10

응답:

[
  {
    "id": 1,
    "name": "Apple MacBook Pro 14",
    "price": 2700000,
    "categoryName": "노트북",
    "providerName": "Apple"
  }
]

2️⃣ 자동완성

GET /api/v1/elastic/product/autocomplete?keyword=노트&requestCount=5

3️⃣ 유사 상품 검색

GET /api/v1/elastic/product/similar/123?requestCount=10

4️⃣ 통합 검색 (관리자)

GET /api/v1/elastic/admin/all?keyword=검색어&page=1&size=20

응답:

{
  "products": [...],
  "orders": [...],
  "banners": [...],
  "providers": [...]
}

🏗️ 아키텍처 특징

📐 계층형 아키텍처

┌─────────────────────────────────────────┐
│  🎨 Presentation Layer                  │
│  (Controllers, Request/Response DTOs)   │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│  💼 Application Layer                   │
│  (Services, Business Logic)             │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│  🏛️ Domain Layer                        │
│  (Entities, Documents, Messages)        │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│  ⚙️ Infrastructure Layer                │
│  (Repositories, Config, Consumers)      │
└─────────────────────────────────────────┘

🔄 이벤트 기반 아키텍처

📦 주문 발생
    ↓
🐰 RabbitMQ (이벤트 전달)
    ↓
📥 Consumer (이벤트 수신)
    ↓
🗄️ Redis (실시간 집계)
    ↓
⏰ Batch Processor (1분마다)
    ↓
🔍 ElasticSearch (동기화 완료)

⚡ 검색 최적화 전략

기능	설명	효과
🇰🇷 Nori Analyzer	한글 형태소 분석기	자연스러운 한글 검색
🔗 combinedField	여러 필드 통합 검색	검색 성능 향상
✨ Highlight	검색어 강조 표시	사용자 경험 개선
🗑️ Soft Delete	논리적 삭제 패턴	데이터 복구 가능

⚠️ 주의사항

🔧 필수 사전 준비

중요! 다음 서비스들이 모두 실행 중이어야 합니다.

✅ MySQL 8.x
✅ ElasticSearch 8.x (SSL 인증서 elasticsearch.jks 필요)
✅ Redis
✅ RabbitMQ
✅ Jasypt 암호화 키 (JASYPT_PASSWORD) 환경 변수 설정

🔐 보안

환경	상태	설명
🟡 개발	인증 없음	모든 API 자유 접근 가능
🔴 운영	⚠️ 주의	반드시 인증/인가 시스템 구현 필요

📊 ElasticSearch 인덱스

인덱스	용도
`product_index`	🛍️ 상품 검색
`order_index`	📦 주문 검색
`banner_index`	🎨 배너 검색
`provider_index`	🏢 공급자 검색

⏰ 배치 작업

🔄 판매량 집계: 1분마다 자동 실행
📊 동기화: Redis → ElasticSearch

👨‍💻 개발 가이드

📚 코딩 컨벤션

프로젝트의 코딩 컨벤션 및 아키텍처 원칙은 .cursor/rules/ 폴더를 참고하세요!

📄 규칙 파일

overview.mdc
architecture.mdc
coding-conventions.mdc
elasticsearch.mdc
event-driven.mdc

📄 규칙 파일

api-design.mdc
spring-config.mdc
security-performance.mdc
tdd.mdc ⭐ NEW
checklist.mdc

📝 TODO

🔴 우선순위 높음 (Critical)

🚨 예외 처리 표준화 (ErrorResponse DTO 정의)
🔐 인증/인가 시스템 구현 (JWT 기반)
🧪 테스트 코드 확충 (단위/통합 테스트)

🟡 우선순위 중간 (Important)

🚦 API Rate Limiting 추가
📊 모니터링 시스템 구축 (ELK Stack, APM)
🐳 Docker 환경 구성 (docker-compose)
📋 API 응답 포맷 표준화

🟢 우선순위 낮음 (Nice to Have)

⚡ 성능 테스트 및 최적화
🔍 코드 품질 개선 (SonarQube)
🎯 검색 결과 개인화
🔥 인기 검색어 집계 기능

📄 라이센스

이 프로젝트는 개인 학습 및 포트폴리오 목적으로 제작되었습니다.

💬 문의

프로젝트 관련 문의사항은 GitHub Issues를 통해 남겨주세요.

⭐ Star로 응원해주세요! ⭐

Made with ❤️ by seunggulee1007

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
.cursor/rules		.cursor/rules
gradle/wrapper		gradle/wrapper
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
build.gradle		build.gradle
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle		settings.gradle

Folders and files

Latest commit

History

Repository files navigation

🔍 hello-search-api

ElasticSearch 기반의 E-commerce 상품 검색 API

📋 목차

🎯 개요

✨ 핵심 특징

🛠 기술 스택

🎯 Backend

💾 Database & Storage

📨 Message Queue

📚 주요 라이브러리

📁 프로젝트 구조

✨ 주요 기능

🔎 검색 기능

🔄 이벤트 처리

⚡ 검색 최적화

🚀 실행 방법

1️⃣ 사전 준비

2️⃣ 프로젝트 클론

3️⃣ 환경 변수 설정

4️⃣ application.yml 설정

5️⃣ 프로젝트 빌드 및 실행

6️⃣ API 문서 확인

📡 API 스펙

🛍️ 상품 검색 API

👨‍💼 관리자 API

🎨 배너 API

🏢 공급자 API

📝 API 호출 예시

🏗️ 아키텍처 특징

📐 계층형 아키텍처

🔄 이벤트 기반 아키텍처

⚡ 검색 최적화 전략

⚠️ 주의사항

🔧 필수 사전 준비

🔐 보안

📊 ElasticSearch 인덱스

⏰ 배치 작업

👨‍💻 개발 가이드

📚 코딩 컨벤션

📝 TODO

🔴 우선순위 높음 (Critical)

🟡 우선순위 중간 (Important)

🟢 우선순위 낮음 (Nice to Have)

📄 라이센스

💬 문의

⭐ Star로 응원해주세요! ⭐

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages