[TECH-QA] TypeScript로 깔끔한 쿼리 문자열 만들기: Record<string, never> 활용법

Posted 9 days Updated 9 days

By 베짱이가 되고싶은 개미。

🚩 Record<string, never> 활용법

import { isNil, isArray, isEmpty } from 'lodash';
import qs from 'query-string';

const buildQueryString = <T = Record<string, never>>(params?: T): string => {
  // 유효하지 않은 값(null, undefined, 빈 문자열/배열) 제거
  const cleanedParams = omitBy(params || {}, (val) => {
    if (isNil(val)) return true;
    return isArray(val) && (val as string[]).every((v) => !v);
  });

  // 객체가 비어 있으면 빈 문자열 반환, 아니면 쿼리 문자열 생성
  return isEmpty(cleanedParams) ? '' : `?${qs.stringify(cleanedParams, { arrayFormat: 'comma', encode: false })}`;
};

// 사용 예제
console.log(buildQueryString()); // ''
console.log(buildQueryString({ name: 'John', age: '25', empty: '' })); // '?name=John,age=25'
console.log(buildQueryString({ items: [], invalid: null })); // ''
console.log(buildQueryString({ tags: ['red', 'blue'], empty: null })); // '?tags=red,blue'

buildQueryString 함수는 프론트엔드에서 API 요청을 위한 쿼리 문자열을 생성하는 유틸리티 함수입니다. 입력 객체에서 유효하지 않은 값(null, undefined, 빈 문자열, 빈 배열 또는 모든 요소가 빈 값인 배열)을 제거하고, 유효한 데이터만 포함한 쿼리 문자열을 반환합니다. 이는 API 요청을 간결하게 만들고, 서버의 처리 부담을 줄이며, 사용자 경험을 개선하는 데 기여합니다.

함수 구조

제네릭 타입

T는 입력 파라미터 params의 타입을 나타냅니다. 기본 타입 Record는 속성이 없는 빈 객체 {}를 의미합니다. params가 undefined이거나 전달되지 않을 경우, 빈 객체 {}로 처리되어 함수가 안전하게 동작합니다.

파라미터

params?: T

params는 선택적이며, 객체 형태로 전달됩니다.
params || {}를 통해 undefined일 경우 빈 객체로 대체됩니다.

로직

Lodash의 omitBy

Lodash의 omitBy를 사용해 null, undefined, 빈 문자열 또는 모든 요소가 빈 값인 배열을 제거.

{ name: "John", empty: null, items: [""] } → { name: "John" }.

Lodash의 isEmpty로 정리된 객체가 비어 있는지 확인.
비어 있으면 ' '를 반환.
그렇지 않으면 qs.stringify를 사용해 쿼리 문자열로 변환하고, ?를 접두사로 추가.
arrayFormat: 'comma'는 배열을 쉼표로 구분 (예: tags=red,blue).
encode: false는 URL 인코딩을 비활성화해 가독성을 높임.

📝 입력 없음

buildQueryString(); // 출력: ''

params가 undefined이므로 빈 객체 {}로 처리.
omitBy({}, ...)는 빈 객체를 반환, isEmpty가 true이므로 '' 반환.

📝 유효한 값 포함

buildQueryString({ name: 'John', age: '25', empty: '' }); // 출력: '?name=John,age=25'

empty: ''는 제거됨.
cleanedParams = { name: 'John', age: '25' }.
qs.stringify로 name=John,age=25를 생성하고, ?를 추가.

📝 유효하지 않은 값만 포함

buildQueryString({ items: [], invalid: null }); // 출력: ''

items: []와 invalid: null은 제거됨.
cleanedParams = {}, isEmpty가 true이므로 '' 반환.

📝 배열 포함

buildQueryString({ tags: ['red', 'blue'], empty: null }); // 출력: '?tags=red,blue'

empty: null은 제거됨.
cleanedParams = { tags: ['red', 'blue'] }.
qs.stringify로 tags=red,blue를 생성하고, ?를 추가.

배열 포함

효율적인 요청: 불필요한 파라미터를 제거해 네트워크 요청 크기를 줄이고, 서버의 처리 부담을 완화.
타입 안전성: Record를 기본 타입으로 사용해 입력이 없거나 빈 객체일 때도 안전하게 처리.
사용자 경험: 간결한 쿼리 문자열은 URL을 깔끔하게 유지하며, 브라우저 히스토리나 공유 링크의 가독성을 높임.
서버 부하 감소: 유효한 데이터만 서버로 전송되므로 서버의 검증 로직이 간소화됨.

트래픽 관리와의 연관성

프론트엔드에서 데이터를 정리하면 불필요한 데이터 전송이 줄어들어 네트워크 트래픽이 감소.
서버는 유효한 데이터만 처리하므로 CPU/메모리 사용량이 줄고, 캐싱 효율성이 향상.
이는 트래픽 스파이크를 간접적으로 방지하며, 전체 시스템 성능을 최적화.