[BADATA] 위치 검색 창에 디바운싱 쓰로틀링 중첩 문제 해결하기

 

위치 검색창 디바운스·AbortController 적용으로 중복 요청 제거 PR

Performance: 위치 검색창 디바운스·AbortController 적용으로 중복 요청 제거 by arty0928 · Pull Request #298

 

들어가며..

CS 스터디에서 디바운딩/쓰로틀링 개념을 배운 김에, BADATA 프로젝트에서 위치 검색을 진행하는 과정에서 적용한 디바운싱 코드를 다시 확인했다. 
그런데 디바운싱과 쓰로틀링을 중첩해서 사용하고 있어 input 창에 위치를 타이핑할 때마다 API 요청이 가는 상황이었다.

 

---

문제 상황

'서울시 강남구'를 천천히 타이핑하면 타이핑 하나당 API 요청이 보내져서 요청횟수가 22회가 보내진다.

 

INP(Interaction to Next Paint)가 111ms 소요되고 있다. 

또한 타임라인에서 볼 수 있듯이 노란 막대 즉 메인 스레드가 연속되어 나타난다. 즉, '서울시 강남구'를 매번 입력할 때마다 JS 가 실행되고 있다. 하지만 이 부분은 키워드 검색할 때 마다 아래 관련 키워드가 포함된 리스트 내역을 UI로 보여줘야 하므로 네트워크 요청 최소화 이후 다시 확인해야 할 듯 하다. 

 

 

 

 

렌더링 총 23회, SearchPosPage의 렌더링 비용이 가장 컸다.

 

즉, 디바운싱 적용 전에서는 총 3가지의 문제점이 발생한다.

1. 입력할 때마다 즉시 API 호출

2. 불필요한 네트워크 비용이 발생

3. 검색창에 입력할 때마다 매번 리렌더링 발생

 

즉, 디바운스 + 스로틀을 중첩해서 사용해서 '멈칫할 때마다 1회씩' 호출이 일어난 것이었다.

 

 

---

 

문제 1 : 디바운스 + 쓰로틀의 중첩 사용

지금 코드 흐름에서 왜 2개를 같이 쓰면 안 좋을까?

import { useCallback, useEffect, useRef, useState } from 'react';

import {
  searchPlaces,
  type PlaceSearchResult,
  type SearchPlacesParams,
} from '@/features/rental/search/utils/address/searchPlaces';

// 디바운싱 훅
const useDebounce = (value: string, delay: number) => {
  const [debouncedValue, setDebouncedValue] = useState(value);

  useEffect(() => {
    const handler = setTimeout(() => {
      setDebouncedValue(value);
    }, delay);

    return () => {
      clearTimeout(handler);
    };
  }, [value, delay]);

  return debouncedValue;
};

// 스로틀링 훅
const useThrottle = <T extends unknown[]>(callback: (...args: T) => void, delay: number) => {
  const lastRunRef = useRef(0);

  return useCallback(
    (...args: T) => {
      const now = Date.now();
      if (now - lastRunRef.current >= delay) {
        lastRunRef.current = now;
        callback(...args);
      }
    },
    [callback, delay],
  );
};

// 키워드 검색 훅
export const useSearchPlaces = () => {
  const [keyword, setKeyword] = useState('');
  const [searchResults, setSearchResults] = useState<PlaceSearchResult[]>([]);
  const [isLoading, setIsLoading] = useState(false);
  const [isLoadingMore, setIsLoadingMore] = useState(false);
  const [hasNext, setHasNext] = useState(true);
  const [page, setPage] = useState(1);

  // 디바운스된 키워드 (500ms) - 공백 제거
  const debouncedKeyword = useDebounce(keyword.trim(), 500);

  // 검색 실행 함수
  const performSearch = useCallback(
    async (searchKeyword: string, pageNum: number = 1, append: boolean = false) => {
      const trimmedKeyword = searchKeyword.trim();
      if (!trimmedKeyword) {
        setSearchResults([]);
        return;
      }

      if (pageNum === 1) {
        setIsLoading(true);
      } else {
        setIsLoadingMore(true);
      }

      try {
        const params: SearchPlacesParams = {
          keyword: trimmedKeyword,
          page: pageNum,
          size: 15,
        };

        const results = await searchPlaces(params);

        if (append) {
          setSearchResults((prev) => [...prev, ...results]);
        } else {
          setSearchResults(results);
        }

        setHasNext(results.length === 15 && pageNum < 3);
      } catch (error) {
        console.error('검색 오류:', error);
        if (!append) {
          setSearchResults([]);
        }
        // API 호출 제한 에러인 경우 사용자에게 알림
        if (error instanceof Error && error.message.includes('API 호출 제한')) {
          console.warn('API 호출 제한으로 인해 검색이 일시적으로 중단되었습니다.');
        }
      } finally {
        setIsLoading(false);
        setIsLoadingMore(false);
      }
    },
    [],
  );

  // 스로틀링된 검색 함수 (300ms)
  const throttledSearch = useThrottle(performSearch, 300);

  // 디바운스된 키워드가 변경될 때 검색 실행
  useEffect(() => {
    if (debouncedKeyword) {
      setPage(1);
      setHasNext(true);
      throttledSearch(debouncedKeyword, 1, false);
    } else {
      setSearchResults([]);
    }
  }, [debouncedKeyword, throttledSearch]);

  // 다음 페이지 로드 함수
  const loadNextPage = useCallback(() => {
    if (!hasNext || isLoadingMore || isLoading) return;

    const nextPage = page + 1;
    setPage(nextPage);
    performSearch(keyword.trim(), nextPage, true);
  }, [hasNext, isLoadingMore, isLoading, page, keyword, performSearch]);

  // 키워드 설정 함수
  const setKeywordOptimized = useCallback((value: string) => {
    setKeyword(value);
  }, []);

  return {
    keyword,
    setKeyword: setKeywordOptimized,
    searchResults,
    isLoading,
    isLoadingMore,
    hasNext,
    loadNextPage,
  };
};

 

현재 흐름을 정리하면 다음과 같다.

 

keyword 입력 → debounce(500ms) → debouncedKeyword 변함 → useEffect → throttle(300ms) 로 performSearch 호출

 

1. 디바운스

사용자가 단어 사이마다 0.5초 내외로 잠깐씩 멈추면, 그 멈춤다가 1회 호출된다. 

특히 한글로 '서울시 강남구'를 타이핑하는 과정에서 조합 중간중간에 500ms 이상 멈춤이 생기기 쉬워서, 조합 단계별로 여러번 요청되고 있었다. (내가 성능을 보려고 일부러 한자한자 타이핑한것도 있지만...)

ㄱ → 가 → 강 으로 값이 여러 중간 상태를 거치면서 단어/조합 과정에서 자주 멈춤이 발생하고, 디바운스가 그때그때 발화한다.

 

2. 쓰로틀

디바운스 뒤에도 쓰로틀을 한번 더 걸면, '변화 시점 근처'에서 추가 호출이 발생한다. 디바운스를 통과한 호출이 스로틀 경계와 만나면 1회 호출이 2회가 되기도 한다.

 

=> 즉, 디바운싱으로 인해서 '멈춤'마다 1회 + 쓰로틀 경계에서 1회 추가 

 

 

또한 react 18의 strictmode의 이펙트 2회 실행까지 겹쳐서 네트워크 요청 숫자가 더 늘어난 것이었다.

 

문제 2. React 18 StrictMode(개발 모드)의 '더블 마운트' 

 

개발 모드에서 StrictMode는 마운트 → 언마운트 → 재마운트를 즉시 수행한다.

이때 ref(스로틀의 lastRunRef)도 초기화가 되는데,

첫 마운트에서 스로틀이 1회 허용, 언마운트로 ref = 0 이 리셋, 재마운트 후 다시 1회 허용

→ 같은 효과가 2번 발생하고 있었다.

 

이 부분은 개발 모드에서만 발생하고 프로덕션 빌드에서는 사라지니 신경쓸 필요는 없었다.

 

 

문제 3. AbortController 의 부재로 모든 요청이 끝까지 진행

 

현재 디바운스 + 스로틀 중첩으로 생각보다 자주 요청이 진행되고 있는데 Abort가 없어서 모든 요청이 끝까지 진행되고 있다. 즉 현재 네트워크 요청이 22번 진행된 것은 

(디바운스 멈춤 횟수) × (스로틀 경계/StrictMode 증폭) + (프리플라이트) + (취소 없음으로 전부 완료) 의 결과였다.

 

 

 

---

 

 

해결 1. 쓰로틀은 제거하여 디바운스만 적용하기

검색은 “최종 확정값 1회 호출”이 목표다.
그런데 스로틀(주기 제한)은 중간값도 주기적으로 실행시키기 때문에, 디바운스 뒤에 스로틀을 또 걸면 멈춤마다 1회 + 경계에서 1회 추가 같은 의도치 않은 호출이 섞였다.

 

쓰로틀 적용한 것을 모두 지우고, 디바운스만 남겨서 '멈춤 구간마다 1회'로 수렴시킨다.

-// 스로틀링 훅
-const useThrottle = <T extends unknown[]>(callback: (...args: T) => void, delay: number) => {
-  const lastRunRef = useRef(0);
-  return useCallback((...args: T) => {
-    const now = Date.now();
-    if (now - lastRunRef.current >= delay) {
-      lastRunRef.current = now;
-      callback(...args);
-    }
-  }, [callback, delay]);
-};
@@
-// 스로틀링된 검색 함수 (300ms)
-const throttledSearch = useThrottle(performSearch, 300);
@@
-// 디바운스된 키워드가 변경될 때 검색 실행
-useEffect(() => {
-  if (debouncedKeyword) {
-    setPage(1);
-    setHasNext(true);
-    throttledSearch(debouncedKeyword, 1, false);
-  } else {
-    setSearchResults([]);
-  }
-}, [debouncedKeyword, throttledSearch]);
+// 디바운스된 키워드가 변경될 때 검색 실행 (스로틀 제거)
+useEffect(() => {
+  if (!debouncedKeyword) {
+    setSearchResults([]);
+    return;
+  }
+  setPage(1);
+  setHasNext(true);
+  performSearch(debouncedKeyword, 1, false);
+}, [debouncedKeyword, performSearch]);

 

 

 

해결 2. StrictMode 2회 중복 호출 가드

 export const useSearchPlaces = () => {
   const [page, setPage] = useState(1);
+  // 같은 요청(키워드, 페이지, append 여부) 중복 방지 가드
+  const lastReqRef = useRef<string | null>(null);

  const performSearch = useCallback(
    async (searchKeyword: string, pageNum: number = 1, append: boolean = false) => {
       const trimmedKeyword = searchKeyword.trim();
       if (!trimmedKeyword) {
         setSearchResults([]);
         return;
       }
+      // StrictMode 재마운트/이펙트 재실행 시 같은 요청은 스킵
+      const reqKey = `${trimmedKeyword}::${pageNum}::${append ? 'append' : 'replace'}`;
+      if (lastReqRef.current === reqKey) return;
+      lastReqRef.current = reqKey;
     },
     [],
   );

 

현재 StrictMode에서 이펙트/마운트가 의도적으로 2회 발생되고 있었는데, 

동일 요청을 중복으로 보내지 않도록 ref를 도입하여 키 단위로 차단하였다. 

 

개발모드에서 동일 렌더 사이클 내에서 같은 이펙트를 연속 2회 실행할 때, 훅에 전달되는 인자( debouncedKeyword, page, append) 는 그대로여서 동일한 Key가 생성된다.

 

useRef로 마지막 요청의 키를 저장해두고, 같은 키로 performSearch가 연속 호출되면 즉시 return 하도록 변경했다.

const reqKey = `${trimmedKeyword}::${pageNum}::${append ? 'append' : 'replace'}`;

 

• trimmedKeyword: 서버에 전달될 실질 검색어(공백 영향 제거)
• pageNum: 페이지네이션 요청 구분
• append/replace: 무한스크롤(append)과 최초검색/갱신(replace) 흐름을 구분

 

다만, StrictMode는 마운트 자체를 한번 완전히 해제(unmount)했다가 다시 마운트한다.

이때 useRef 역시 컴포넌트 인스턴스 기반이므로 재마운트 시 초기화된다.

즉, 첫 마운트의 연속 2회 호출은 ref로 잡을 수 있지만, 재마운트 후의 1회 호출은 새 인스턴스이므로 정상적으로 1회 더 발생한다.

다만, 이건 프로덕션 빌드에서는 발생하지 않으므로 이 정도 가드로 마무리하였다.

 

 

해결 3. AbortController를 추가하여 중간 요청을 취소한다.

디바운스를 적용해도 '서울시 강남구'를 타이핑하는 과정에서 멈춤이 있다면 중간에 요청이 한번 날라가게 된다. 그런데 이후 '서울시 강남구'를 다시 요청하면 이전 요청이 아직 끝나지 않은 상태(in-flight) 로 남고, 그 사이 새 요청이 다시 발사되는 문제가 남아있다.
요청이 길다면, 혹은 네트워크 속도가 느리다면, 오래된 응답이 나중에 도착하여 최신 결과를 덮어쓰는 레이스가 발생할 수 있다. 또한 불필요한 예전 네트워크 요청을 지속하므로 네트워크 낭비도 컸다.

 

이를 해결하기 위해:

• AbortController를 도입하여 요청을 키 단위가 아니라 '물리적으로' 취소하도록 변경하였다.
  • controllerRef로 현재 진행 중인 컨트롤러를 저장해두고,
  • 새 요청 전엔 반드시 abort()로 기존 요청을 중단한 뒤,
  • 새로운 AbortController를 발급하여 해당 signal를 fetch에 연결했다.
• 또한, 이팩트 클린업 시점에도 abort()를 호출하여 StrictMode 재실행/언마운트 구간에서 남아 있는 in-flight 요청을 정리하였다.

1. useSearchPlaces 훅 : 이펙트/재실행/언마운트 시 진행 중 요청 취소(cleanUp)

// NEW: 이전 요청 취소용 컨트롤러
const controllerRef = useRef<AbortController | null>(null);

const performSearch = useCallback(
  async (searchKeyword: string, pageNum: number = 1, append: boolean = false) => {
    // ... (중략)

    // NEW: 이전 요청 취소
    controllerRef.current?.abort();
    // NEW: 새 컨트롤러 생성
    const controller = new AbortController();
    controllerRef.current = controller;

    try {
      const params: SearchPlacesParams = {
        keyword: trimmedKeyword,
        page: pageNum,
        size: 15,
        // NEW: 진행 중 요청 취소를 위해 signal 전달
        signal: controller.signal,
      };
      const results = await searchPlaces(params);
      // ...
    } catch (error) {
      // NEW: AbortError는 정상 취소 → 조용히 무시
      if ((error as any)?.name !== 'AbortError') {
        console.error('검색 오류:', error);
        // ...
      }
    } finally {
      setIsLoading(false);
      setIsLoadingMore(false);
    }
  },
  [],
);

// NEW: debouncedKeyword 이펙트 클린업에서 진행 중 요청 취소
useEffect(() => {
  if (!debouncedKeyword) {
    setSearchResults([]);
    controllerRef.current?.abort();  // ← 여기
    return;
  }
  setPage(1);
  setHasNext(true);
  performSearch(debouncedKeyword, 1, false);

  return () => {
    controllerRef.current?.abort();  // ← 여기
  };
}, [debouncedKeyword, performSearch]);

 

 

2. searchPlaces 유틸 : fetch에 signal을 전달 + AbortError 는 그대로 위로 던지기

export interface SearchPlacesParams {
  keyword: string;
  page?: number;
  size?: number;
  signal?: AbortSignal;  // NEW
}

export const searchPlaces = async (params: SearchPlacesParams): Promise<PlaceSearchResult[]> => {
  const { keyword, page = 1, size = 15, signal } = params;  // NEW

  try {
    const response = await fetch(
      `https://dapi.kakao.com/v2/local/search/keyword.json?query=${encodeURIComponent(keyword)}&page=${page}&size=${size}`,
      {
        headers: { Authorization: `KakaoAK ${process.env.NEXT_PUBLIC_KAKAO_MAP_REST_API_KEY}` },
        signal,  // NEW: fetch 취소용 signal 연결
      },
    );
    // ...
  } catch (error: any) {
    if (error?.name === 'AbortError') {
      throw error;  // NEW: 취소는 정상 흐름 → 상위에서 조용히 무시
    }
    console.error('키워드 검색 오류:', error);
    throw error;    // 기존 에러는 상위에서 처리하도록 전파
  }
};

 

• 유틸 레벨에서는 signal을 fetch 옵션으로 전달해 실제 취소가 동작하도록 했고,
• 취소 시 발생하는 AbortError는 정상 취소로 간주해 그대로 전파하여 상위 훅에서 조용히 무시하도록 만들었다.
• 반대로 네트워크 실패/429는 에러로 전파해 의도된 에러 핸들링을 유지했다.’

 

---

 

적용 결과

 

 

 

네트워크 탭을 보니 keyword.json?... 이 1회만 호출되어 디바운스와 AbortController가 잘 적용된 것을 확인했다. 여러 요청이 나가던 문제도 사라졌고, 중간 요청도 잘 취소되었다.

 

브라우저가 입력에 대한 응답도 빨라져서 INP가 111ms에서 48ms로 개선되었다.

또한 총 수행 범위인 full range도 5995ms에서 2506ms로 절반이상이 감소하였다.

 

네트워크 문제는 해결했지만 노란색 막대가 여전히 자주 보인다. 즉, UI 렌더링이 자주 발생하고 있다. 그런데 내가 원하는 동작은 키워드가 포함되는 위치를 아래에 실시간으로 보여줘야 하는 동작이라 UI가 리렌더링이 발생하는 것이 맞다.