기록

한국어 검색의 가장 큰 특징은 “단어의 경계가 명확하지 않다”는 점이다. 영어는 공백으로 단어가 구분되지만, 한국어는 띄어쓰기 오류나 복합명사 때문에 단순 문자열 비교로는 정확한 검색이 어렵다. 예를 들어 “무선마우스”, “무선 마우스”, “무선형 마우스”는 모두 사용자가 같은 제품을 찾으려는 의도지만, 문자열 기준으로는 완전히 다른 단어다. 이런 문제를 해결하기 위해 Elasticsearch에서는 Nori 분석기를 사용한다. Nori는 한국어 형태소 분석기(morphological analyzer)로, 문장을 의미 단위로 분해하고 색인과 검색을 돕는다.1. Nori 분석기의 기본 원리Elasticsearch는 데이터를 저장하기 전에 “토큰화(tokenization)” 과정을 거친다. 이 과정에서 텍스트..

검색 API의 목표는 사용자의 짧은 질의(q)를 받아 의미 있는 결과를 빠르고 안정적으로 반환하는 것이다. Query 서버는 Spring WebFlux 기반의 논블로킹 아키텍처 위에서 Elasticsearch와 통신하며, ReactiveElasticsearchOperations로 네이티브 쿼리를 유연하게 구성한다. 본 편에서는 컨트롤러→서비스→리포지토리 흐름, 검색 점수 모델 설계, 페이징·정렬·필터 확장, 에러·관측·성능 고려까지 단계적으로 정리한다.1. 전체 흐름 요청은 ProductQueryController → ProductQueryService → ProductQueryRepository → Elasticsearch 순으로 진행된다. 컨트롤러는 파라미터를 검증해 서비스로 전달하고, 서비스는 리포..

상품 검색 엔진의 핵심은 단순한 데이터 저장이 아니라, “검색 가능한 데이터로 변환하는 것”이다.API 서버가 Kafka를 통해 발행한 상품 등록 이벤트는 Query 서버(Spring WebFlux)를 거쳐 Elasticsearch로 전달되며, 이 과정을 담당하는 것이 바로 상품 색인기(Product Indexer) 이다. 색인기는 데이터를 읽고, 가공하고, 분석기를 적용해 검색 효율이 높은 형태로 재구성한다. 1. Query 서버 구조Query 서버는 Spring WebFlux 기반으로 구현되어 있으며, Kafka Listener와 Reactive Elasticsearch를 결합해 완전 비동기 방식으로 동작한다.색인기는 등록 요청이 몰려와도 스레드를 점유하지 않으며, Reactor 기반 스트림으로 I/..

이전 편에서 전체 구조와 CQRS 설계를 살펴보았다. 이번 글에서는 그중 API 서버(Spring MVC) 가 어떻게 상품 등록 요청을 처리하고, 이를 Kafka 이벤트로 발행하는지를 구체적으로 다룬다. 이 서버는 시스템의 Command 사이드(Command Side) 로, 사용자의 “쓰기” 요청을 받아 시스템 내 “변화”를 만들어내는 역할을 담당한다. 실제 상품 데이터는 즉시 저장되지 않고, 이벤트 형태로 브로커에 발행되어 비동기적으로 처리된다. 이로써 API 서버는 빠르고 안정적으로 응답을 반환하며, 검색 서버(Query Side)는 색인 작업에 집중할 수 있다.1. 구조 개요상품 등록 흐름은 단순하면서도 명확한 3단계로 구성된다.[1] ProductController → [2] ProductServ..

대규모 상품 데이터를 효율적으로 검색하기 위해서는, 데이터의 생성·저장·조회가 동일한 시스템에서 동시에 처리되지 않도록 분리해야 한다. 이번 글에서는 이러한 원리를 바탕으로 CQRS(Command Query Responsibility Segregation) 구조를 적용한 상품 검색 엔진(Product Search Engine) 설계를 다룬다. 시스템은 크게 두 개의 서버로 구성된다.1. 전체 구조 개요상품 검색 엔진은 다음과 같은 구조를 가진다.주요 구성 요소구성 요소 역할API 서버 (Command)상품 등록 및 수정 요청을 처리하고 Kafka로 이벤트를 발행한다.Kafka 브로커등록된 상품 정보를 이벤트 스트림 형태로 전달한다.Query 서버 (Search)Kafka 이벤트를 수신하여 Elastics..

1. 들어가며Swagger(OpenAPI)는 단순한 API 목록 도구가 아니라, API 보안 구조까지 함께 명세화할 수 있는 문서 시스템이다.JWT(JSON Web Token) 기반 인증을 사용하는 서비스라면 Swagger UI의 Authorize 버튼을 통해 실제 토큰을 입력하고 인증된 요청을 테스트할 수 있다.이번 글에서는 Spring Boot 3.x와 Spring Security 환경에서 JWT 인증을 Swagger(OpenAPI) 문서에 통합하는 방법을 설명한다. 2. Swagger에서의 보안 구조 이해OpenAPI 명세는 components.securitySchemes와 security 섹션을 이용해 인증 방식을 정의한다.JWT 인증은 HTTP Bearer 스킴으로 정의되며, Swagger UI..

1. 들어가며Swagger(OpenAPI)는 단순히 API 목록을 보여주는 도구가 아니라, 코드에 어노테이션을 부여해 API의 목적, 요청 구조, 응답 모델을 명세화하는 문서 도구이다. 이 글에서는 OpenAPI 3.x 기준으로 자주 사용하는 Swagger 어노테이션을 정리한다. 2. 어노테이션 기반 문서화의 구조Spring Boot에서 springdoc-openapi는 Controller, DTO, Validation 정보를 스캔해 /v3/api-docs에 반영한다. 이때 Swagger 어노테이션들은 각 역할별로 다음처럼 매핑된다.적용 범위어노테이션 역할API 그룹@Tag컨트롤러 단위 그룹 지정개별 엔드포인트@OperationAPI 요약 및 상세 설명파라미터@ParameterPath, Query, He..

1. 들어가며Swagger는 단순히 API를 시각화하는 도구가 아니라, 애플리케이션의 Controller와 DTO를 분석해 **자동으로 OpenAPI 문서(JSON)**를 생성한다. 이 글에서는 Spring Boot 3.x 기준으로 Swagger(OpenAPI)를 프로젝트에 적용하는 구체적인 방법을 다룬다.2. springdoc-openapi 개요Spring Boot 3에서는 springfox가 더 이상 권장되지 않는다.대신 springdoc-openapi가 공식적으로 OpenAPI 3.x를 완전 지원하며, Spring MVC 및 WebFlux 양쪽 모두를 지원한다.springdoc은 내부적으로 io.swagger.v3.oas.models.* 패키지를 사용해 OpenAPI 명세를 생성하며,이 명세를 /v..