Spring Boot와 ElasticSearch로 검색 API 만들기

소개

이 글은 Spring Boot와 ElasticSearch 연동을 처음 접하는 개발자를 위해 검색 API 구축 과정을 쉽게 설명한다. 핵심은 데이터 색인(indexing), 검색 쿼리 구성, 그리고 Spring Data Elasticsearch를 활용한 편리한 레포지토리 구성이다. 전체 흐름을 이해하면 검색 성능 개선이나 확장에도 도움이 된다.

사전 준비

다음 환경을 기준으로 설명한다.

• Java 11 이상
• Spring Boot 2.7.x 또는 3.x
• Elasticsearch 7.x 또는 8.x(버전 호환 확인 필요)
• 간단한 REST 클라이언트 도구(Postman 등)

프로젝트 설정

Spring Boot에서 ElasticSearch 연동을 위해 의존성을 추가한다. Maven 예제는 아래와 같다.

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
</dependency>

Gradle이나 다른 빌드 도구를 쓸 때도 기본 개념은 동일하다. 의존성은 spring data elasticsearch 예제에서 자주 사용된다.

설정 파일

application.yml에 Elasticsearch 호스트와 포트를 지정한다. 인증이 필요한 경우 username, password 항목 추가가 필요하다.

spring:
  elasticsearch:
    client:
      elasticsearch:
        hosts: http://localhost:9200
        # username: user
        # password: pass

도메인 모델과 매핑

Elasticsearch는 도큐먼트를 색인한다. Spring Data Elasticsearch의 @Document와 @Field를 사용해 매핑을 정의한다.

package com.example.search.model;

import org.springframework.data.annotation.Id;
import org.springframework.data.elasticsearch.annotations.Document;
import org.springframework.data.elasticsearch.annotations.Field;
import org.springframework.data.elasticsearch.annotations.FieldType;

@Document(indexName = "products")
public class Product {
  @Id
  private String id;

  @Field(type = FieldType.Text)
  private String name;

  @Field(type = FieldType.Text)
  private String description;

  @Field(type = FieldType.Double)
  private double price;

  // getters, setters, constructors
}

레포지토리 구성

기본적인 CRUD와 검색 쿼리는 ElasticsearchRepository로 처리한다. 복잡한 쿼리는 NativeSearchQueryBuilder를 사용한다.

package com.example.search.repository;

import org.springframework.data.elasticsearch.repository.ElasticsearchRepository;
import com.example.search.model.Product;

public interface ProductRepository extends ElasticsearchRepository<Product, String> {
  // 쿼리 메소드 추가 가능
}

서비스와 검색 구현

간단한 키워드 검색 예제를 만든다. Spring Data의 QueryBuilders를 활용하면 full-text 검색을 쉽게 구성할 수 있다.

package com.example.search.service;

import org.elasticsearch.index.query.QueryBuilders;
import org.springframework.data.elasticsearch.core.ElasticsearchOperations;
import org.springframework.data.elasticsearch.core.query.NativeSearchQueryBuilder;
import org.springframework.data.elasticsearch.core.query.NativeSearchQuery;
import org.springframework.stereotype.Service;
import com.example.search.model.Product;
import java.util.List;

@Service
public class SearchService {
  private final ElasticsearchOperations operations;

  public SearchService(ElasticsearchOperations operations) {
    this.operations = operations;
  }

  public List<Product> searchByKeyword(String keyword) {
    NativeSearchQuery query = new NativeSearchQueryBuilder()
      .withQuery(QueryBuilders.multiMatchQuery(keyword, "name", "description"))
      .build();
    return operations.search(query, Product.class)
      .map(searchHit -> searchHit.getContent())
      .toList();
  }
}

컨트롤러

REST API 엔드포인트를 만들어 검색 결과를 반환한다. 검색 파라미터와 페이징을 추가하면 실무에 유용하다.

package com.example.search.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import com.example.search.model.Product;
import com.example.search.service.SearchService;
import java.util.List;

@RestController
public class SearchController {
  private final SearchService searchService;

  public SearchController(SearchService searchService) {
    this.searchService = searchService;
  }

  @GetMapping("/api/search")
  public List<Product> search(@RequestParam String q) {
    return searchService.searchByKeyword(q);
  }
}

테스트와 검증

샘플 데이터를 색인하고 API를 호출해 결과를 확인한다. 인덱스 매핑과 분석기(Analyzer)를 체크해 한국어 처리가 필요한 경우 nori 분석기 같은 플러그인을 적용한다.

실무 고려사항

• 데이터 동기화: DB와 색인 일관성을 유지하는 방식 결정
• 역색인 분석기 설정: 한국어 토큰화 필요 시 추가 설정
• 페이징과 정렬: 대용량 결과 처리 전략 수립
• 모니터링: 클러스터 상태와 성능 지표 수집

맺음말

여기까지의 내용으로 spring boot elasticsearch 연동 기초를 이해할 수 있다. 프로젝트에 맞게 매핑, 분석기, 쿼리 전략을 조정하면 검색 품질을 높일 수 있다. 추가적으로 spring data elasticsearch 예제 중심으로 코드를 확장하면 더 다양한 검색 기능을 구현할 수 있다.