검색 기능이 원하는 결과를 못 찾을 때 디버깅하기

검색 결과가 없다는 버그는 사용자 경험을 심각하게 해친다. 내용은 명백히 있는데 "검색 결과 없음"이 나온다.

먼저 실제로 데이터가 있는지 확인한다

데이터베이스에서 직접 조회해본다:

# Postgres 예시
psql -d production -c "SELECT * FROM products WHERE title ILIKE '%검색어%' LIMIT 5"

결과가 없으면 데이터 자체가 없거나 인덱싱되지 않은 것. 결과가 있으면 검색 API 로직 문제다.

API 요청을 직접 테스트한다

curl -i 'https://example.com/api/search?q=검색어&limit=10'

response body를 본다. API가 진짜 검색어를 받았는가? 데이터베이스에 쿼리를 전달했는가?

검색어 인코딩을 확인한다

URL 인코딩이 제대로 되지 않으면 서버가 검색어를 잘못 해석한다:

# 올바른 인코딩
curl 'https://example.com/api/search?q=%EA%B2%80%EC%83%89%EC%96%B4'

# 잘못된 인코딩 (공백이나 특수문자가 그대로)
curl 'https://example.com/api/search?q=검색어'

JavaScript fetch를 사용할 때는 URLSearchParams를 사용하면 자동으로 인코딩된다:

const params = new URLSearchParams({ q: '검색어' })
fetch(`/api/search?${params}`)

검색 쿼리 로직을 로그로 확인한다

API 서버의 로그에서 실제로 어떤 쿼리가 실행됐는지 본다:

[DEBUG] Search query: SELECT * FROM products WHERE title ILIKE '%검색%'
[DEBUG] Rows returned: 0

0개가 나왔다면 조건이 너무 엄격하거나, 데이터 타입 불일치, 또는 대소문자 차이일 수 있다.

더 느슨한 조건으로 테스트해본다

# 첫 글자만으로 검색
curl 'https://example.com/api/search?q=검'

# 전체 단어로 검색
curl 'https://example.com/api/search?q=검색어'

# 부분 일치로 검색
curl 'https://example.com/api/search?q=색어'

어느 조건에서는 결과가 나오고 어느 조건에서는 안 나온다면, 쿼리의 WHERE 조건을 확인해야 한다.

데이터베이스 텍스트 검색 옵션을 점검한다

Postgres ILIKE는 대소문자 무시, 하지만 여전히 정확한 텍스트 일치여야 한다:

-- 이건 작동
SELECT * FROM products WHERE title ILIKE '%검색%'

-- 이건 안 될 수도 (한글 토큰화 필요)
SELECT * FROM products WHERE title @@ plainto_tsquery('검색')

Full-text search를 사용한다면 토큰화 설정을 확인해야 한다. 한글은 특별한 설정이 필요할 수 있다.

검색 결과 필터링이 너무 많지 않은지 확인한다

// 문제: 검색 후 추가 필터
const results = await searchProducts(query)  // 10개
const filtered = results.filter(p => p.inStock && p.active)  // 0개

// 해결: 데이터베이스에서 필터링
const results = await searchProducts(query, { inStock: true, active: true })

JavaScript에서 필터링하면 API는 데이터를 반환했는데 화면에는 아무것도 안 나타난다.

로컬과 운영 환경의 데이터를 비교한다

로컬에서는 검색이 되는데 운영에서는 안 될 수 있다:

• 운영 DB의 데이터 인덱싱이 다를 수 있다
• 컬럼 이름이나 타입이 다를 수 있다
• 캐시된 검색 결과를 사용 중일 수 있다

운영에 배포 후 첫 검색은 특히 주의 깊게 봐야 한다.