spring-boot-examples/docs/elasticsearch.md at eef061c1c95c29fea3b933031f4aeba052813b1b

Files

Elex eef061c1c9 2025-04-08T19:56:24

2025-04-08 19:56:24 +09:00

7.7 KiB

Raw Blame History

스프링 부트에서 엘라스틱서치(Elasticsearch)를 사용하는 방법

엘라스틱서치(Elasticsearch)는 분산 검색 엔진으로, 대규모 데이터의 검색, 분석, 저장을 효율적으로 처리할 수 있는 도구입니다. 스프링 부트에서 엘라스틱서치를 사용하면 Spring Data Elasticsearch를 통해 쉽게 통합할 수 있으며, REST API나 Java 클라이언트를 활용해 데이터를 조작할 수 있습니다. 아래에서는 설정부터 사용 방법까지 단계별로 설명하겠습니다.

1. 의존성 추가

스프링 부트 프로젝트에서 엘라스틱서치를 사용하려면 pom.xml에 spring-boot-starter-data-elasticsearch 의존성을 추가합니다.

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

참고: 스프링 부트 버전에 따라 엘라스틱서치 클라이언트 버전이 달라질 수 있으니, 사용하는 엘라스틱서치 서버 버전과 호환되도록 확인하세요 (예: Elasticsearch 8.x 사용 시 최신 클라이언트 필요).

2. `application.yaml` 설정

엘라스틱서치 서버와의 연결을 설정합니다.

spring:
  elasticsearch:
    uris: http://localhost:9200  # 엘라스틱서치 서버 URL
    username: elastic            # 기본 사용자 이름 (선택)
    password: yourpassword       # 비밀번호 (선택, 기본 인증 사용 시)

옵션:
- uris: 단일 또는 다중 노드 URL (예: http://node1:9200,http://node2:9200).
- username/password: 엘라스틱서치 보안 설정(X-Pack) 활성화 시 필요.

3. 엔티티 클래스 정의

엘라스틱서치에 저장할 데이터를 표현하는 엔티티 클래스를 정의합니다. @Document 어노테이션을 사용해 인덱스를 지정합니다.

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 = "users")  // 인덱스 이름 지정
public class User {

    @Id
    private String id;

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

    @Field(type = FieldType.Integer)
    private int age;

    // Getter, Setter, Constructor
    public User() {}

    public User(String id, String name, int age) {
        this.id = id;
        this.name = name;
        this.age = age;
    }

    // ... getters and setters ...
}

@Document: 인덱스 이름과 설정(샤드 수, 복제본 수 등)을 정의.
@Id: 문서의 고유 식별자.
@Field: 필드 타입과 매핑 설정.

4. 리포지토리 인터페이스 생성

Spring Data Elasticsearch는 JPA와 유사하게 리포지토리 인터페이스를 제공합니다.

import org.springframework.data.elasticsearch.repository.ElasticsearchRepository;

public interface UserRepository extends ElasticsearchRepository<User, String> {
    List<User> findByName(String name);  // 이름으로 검색
    List<User> findByAgeGreaterThan(int age);  // 나이 기준 검색
}

기능: 기본 CRUD 메서드(save, findById, delete 등)와 쿼리 메서드 자동 생성.

5. 서비스 및 컨트롤러 구현

리포지토리를 사용해 데이터를 조작하는 서비스와 컨트롤러를 작성합니다.

@Service
public class UserService {

    private final UserRepository userRepository;

    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public User saveUser(User user) {
        return userRepository.save(user);
    }

    public Optional<User> findUserById(String id) {
        return userRepository.findById(id);
    }

    public List<User> findUsersByName(String name) {
        return userRepository.findByName(name);
    }

    public void deleteUser(String id) {
        userRepository.deleteById(id);
    }
}

@RestController
@RequestMapping("/api/users")
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        return userService.saveUser(user);
    }

    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable String id) {
        return userService.findUserById(id)
            .map(ResponseEntity::ok)
            .orElseGet(() -> ResponseEntity.notFound().build());
    }

    @GetMapping("/search")
    public List<User> searchUsersByName(@RequestParam String name) {
        return userService.findUsersByName(name);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable String id) {
        userService.deleteUser(id);
        return ResponseEntity.noContent().build();
    }
}

6. 커스텀 쿼리 사용 (옵션)

복잡한 검색 쿼리가 필요할 경우 ElasticsearchRestTemplate을 사용합니다.

@Configuration
public class ElasticsearchConfig {

    @Bean
    public ElasticsearchRestTemplate elasticsearchTemplate(RestHighLevelClient client) {
        return new ElasticsearchRestTemplate(client);
    }
}

@Service
public class CustomUserService {

    private final ElasticsearchRestTemplate template;

    public CustomUserService(ElasticsearchRestTemplate template) {
        this.template = template;
    }

    public List<User> searchByName(String name) {
        NativeSearchQuery searchQuery = new NativeSearchQueryBuilder()
            .withQuery(QueryBuilders.matchQuery("name", name))
            .build();
        SearchHits<User> searchHits = template.search(searchQuery, User.class);
        return searchHits.get().map(SearchHit::getContent).collect(Collectors.toList());
    }
}

ElasticsearchRestTemplate: 저수준 API로 복잡한 쿼리 실행.
QueryBuilders: 쿼리 빌더를 사용해 검색 조건 정의.

7. 테스트

엘라스틱서치가 실행 중인지 확인하고, 애플리케이션을 실행합니다. 예를 들어:

데이터 추가: POST /api/users에 { "id": "1", "name": "John", "age": 30 } 요청.
검색: GET /api/users/search?name=John으로 이름 검색.

추가 팁

의존성 버전 확인:
- 엘라스틱서치 서버 버전과 클라이언트 버전이 일치해야 합니다. 스프링 부트 3.x는 기본적으로 Elasticsearch 8.x를 지원합니다.
- 필요 시 spring.elasticsearch.restclient.version 속성으로 버전 조정.
인덱스 관리:
- 인덱스는 자동 생성되지만, 매핑을 미리 정의하려면 @Mapping 어노테이션이나 엘라스틱서치 API 사용.

운영 환경 설정:

spring:
  elasticsearch:
    uris: http://prod-es:9200
    username: elastic
    password: securepassword

로컬 테스트:

Docker로 엘라스틱서치를 실행:

docker run -d -p 9200:9200 -e "discovery.type=single-node" elasticsearch:8.12.0

결론

스프링 부트에서 엘라스틱서치를 사용하려면 spring-boot-starter-data-elasticsearch 의존성을 추가하고, application.yaml으로 연결 설정을 정의한 후, 엔티티와 리포지토리를 작성하면 됩니다. 간단한 CRUD는 ElasticsearchRepository로 처리하고, 복잡한 쿼리는 ElasticsearchRestTemplate을 활용할 수 있습니다. 이를 통해 검색 성능을 극대화하고 대규모 데이터를 효율적으로 관리할 수 있습니다. 추가 질문이 있다면 언제든 물어보세요!

7.7 KiB Raw Blame History