[Spring] Example<T> 인터페이스

코드를 보다가 Example<T> 인터페이스를 활용한 경우가 있었다. 

Example<T>를 언제 사용하고, 왜 사용하는지 알아보자. 

 

Example<T> 인터페이스란 ?

Spring Data Core에서 제공하는 것으로, QBE(Query By Example)을 지원하는 기능이다. 

객체 자체를 쿼리 조건으로 활용하여 간단한 검색을 수행할 수 있다. 

 

 

 

주요 개념

• 도메인 객체(엔티티) 자체를 검색 조건으로 활용
• Null 값은 무시 (필드 값이 있는 것만 검색 조건으로 사용)
• 동적 쿼리 생성 가능
• 별도의 JPQL이나 SQL을 작성할 필요 없음

👉 간단한 검색에서는 유용하겠으나.. 실무에서는 복잡한 검색이 더 많이 때문에 그냥 저런 기능이 있구나 정도만 알아도 될 것 같다. 

 

 

 

사용 예시

User probe = new User();
probe.setName("Alice");  // 이름이 Alice인 사용자 검색

Example<User> example = Example.of(probe);

name 필드만 값이 있으므로, 해당 필드만 검색 조건으로 사용됨

 

 

 

ExampleMatcher

Example은 완전 일치 비교를 수행하지만, ExampleMatcher를 사용하면 일부 필드를 무시하거나 문자열 검색을 유연하게 만들 수 있다. 

// 1. 검색 조건 객체 생성
User probe = new User();
probe.setName("alice");  // 대소문자 구분 없이 검색
probe.setAge(25);        // 나이 25세인 경우만 검색

// 2. ExampleMatcher 설정 (대소문자 무시 & 부분 검색)
ExampleMatcher matcher = ExampleMatcher.matching()
    .withIgnoreCase("name")  // name 필드는 대소문자 무시
    .withStringMatcher(ExampleMatcher.StringMatcher.CONTAINING);  // 부분 검색 (like '%alice%')

// 3. Example 생성
Example<User> example = Example.of(probe, matcher);

 

List<User> users = userRepository.findAll(example);

👉 이름에 alice가 포함되면서 나이가 25인 사용자 조회 

 

 

 

한계점

• AND 조건만 지원 (OR 조건 직접 지정 불가)
• 숫자 비교(>, <) 와 같은 연산 불가
• 조인 테이블의 필드 검색 어려움
• 속성에 null이 있으면 자동 무시되므로 null을 포함하는 검색이 어려움

👉 복잡한 검색이 필요하면 Specification이나 QueryDSL을 사용하는 것이 효율적이다. 

 

 

---

 

참고 자료

https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/domain/Example.html

https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/domain/ExampleMatcher.html

https://docs.spring.io/spring-data/relational/reference/query-by-example.html