Axios GET Request에서 Params를 전달하는 방법 (2026)

Axios GET 요청에서 파라미터(Params)를 전달하는 방법 (2026)

Axios는 브라우저와 Node.js 환경 모두에서 사용되는 가장 인기 있는 JavaScript용 HTTP 클라이언트입니다. REST API로 작업할 때 가장 흔한 작업 중 하나는 GET 요청과 함께 쿼리 파라미터를 전송하는 것입니다.

이 가이드에서는 기본 사용법부터 배열 직렬화, 커스텀 직렬화 및 인터셉터와 같은 고급 패턴에 이르기까지 Axios GET 요청에서 파라미터를 전달하는 모든 방법을 설명합니다.

`params` 객체를 사용한 기본 파라미터 전달

쿼리 파라미터를 전달하는 가장 깔끔한 방법은 params 설정 옵션을 사용하는 것입니다.

import axios from 'axios';

const response = await axios.get('https://api.example.com/users', {
  params: {
    page: 1,
    limit: 20,
    sort: 'created_at'
  }
});

// 결과 URL: https://api.example.com/users?page=1&limit=20&sort=created_at

Axios는 params 객체를 쿼리 문자열로 자동 직렬화하여 URL 뒤에 추가합니다. URL을 수동으로 작성할 필요가 없습니다.

방법 비교

Axios GET 요청에서 파라미터를 전달하는 모든 방법은 다음과 같습니다.

방법	예시	용도
params 객체	axios.get(url, { params: {...} })	대부분의 경우에 권장
URL 문자열	axios.get(url + '?key=value')	단순하고 정적인 파라미터
템플릿 리터럴	axios.get(`${url}?key=${value}`)	빠른 일회성 요청
URLSearchParams	axios.get(url, { params: new URLSearchParams(...) })	Form-encoded 데이터
paramsSerializer	커스텀 함수	복잡한 직렬화가 필요한 경우

다양한 데이터 타입 전달하기

문자열과 숫자

단순한 값들은 직접 직렬화됩니다.

const response = await axios.get('/api/products', {
  params: {
    category: 'electronics',
    minPrice: 100,
    maxPrice: 500,
    inStock: true
  }
});

// URL: /api/products?category=electronics&minPrice=100&maxPrice=500&inStock=true

배열 (Arrays)

기본적으로 Axios는 대괄호 표기법을 사용하여 배열을 직렬화합니다.

const response = await axios.get('/api/products', {
  params: {
    ids: [1, 2, 3, 4, 5]
  }
});

// 기본 URL: /api/products?ids[]=1&ids[]=2&ids[]=3&ids[]=4&ids[]=5

API마다 기대하는 배열 형식이 다를 수 있습니다. 이를 커스텀하려면 paramsSerializer를 사용하세요.

import qs from 'qs';

// 쉼표 구분: ?ids=1,2,3,4,5
const response = await axios.get('/api/products', {
  params: { ids: [1, 2, 3, 4, 5] },
  paramsSerializer: (params) => {
    return qs.stringify(params, { arrayFormat: 'comma' });
  }
});

// 키 반복: ?ids=1&ids=2&ids=3&ids=4&ids=5
const response2 = await axios.get('/api/products', {
  params: { ids: [1, 2, 3, 4, 5] },
  paramsSerializer: (params) => {
    return qs.stringify(params, { arrayFormat: 'repeat' });
  }
});

// 인덱스 포함 대괄호: ?ids[0]=1&ids[1]=2&ids[2]=3
const response3 = await axios.get('/api/products', {
  params: { ids: [1, 2, 3, 4, 5] },
  paramsSerializer: (params) => {
    return qs.stringify(params, { arrayFormat: 'indices' });
  }
});

중첩된 객체 (Nested Objects)

중첩된 파라미터를 허용하는 API의 경우 다음과 같이 처리합니다.

import qs from 'qs';

const response = await axios.get('/api/search', {
  params: {
    filter: {
      status: 'active',
      role: 'admin'
    },
    pagination: {
      page: 1,
      perPage: 25
    }
  },
  paramsSerializer: (params) => {
    return qs.stringify(params, { encode: false });
  }
});

// URL: /api/search?filter[status]=active&filter[role]=admin&pagination[page]=1&pagination[perPage]=25

Null 및 Undefined 값

기본적으로 Axios는 undefined 값은 제외하지만 null 값은 포함합니다.

const response = await axios.get('/api/users', {
  params: {
    name: 'John',
    email: undefined,  // URL에서 제외됨
    phone: null         // ?phone= 으로 포함됨
  }
});

// URL: /api/users?name=John&phone=

null과 undefined를 모두 남기지 않으려면 다음과 같이 처리합니다.

const cleanParams = (params) => {
  return Object.fromEntries(
    Object.entries(params).filter(([_, v]) => v != null)
  );
};

const response = await axios.get('/api/users', {
  params: cleanParams({
    name: 'John',
    email: undefined,
    phone: null
  })
});

// URL: /api/users?name=John

URLSearchParams 사용하기

기본 URLSearchParams API는 Axios와 직접 호환됩니다.

const params = new URLSearchParams();
params.append('search', 'laptop');
params.append('category', 'electronics');
params.append('category', 'computers'); // 중복 키 지원

const response = await axios.get('/api/products', { params });

// URL: /api/products?search=laptop&category=electronics&category=computers

이는 동적으로 파라미터를 추가해야 할 때 유용합니다.

const params = new URLSearchParams();

// 조건부 파라미터 생성
if (searchTerm) params.append('q', searchTerm);
if (category) params.append('category', category);
if (minPrice) params.append('min_price', minPrice);
if (maxPrice) params.append('max_price', maxPrice);

const response = await axios.get('/api/search', { params });

인터셉터를 이용한 기본 파라미터 설정

모든 요청에 포함되어야 하는 파라미터(예: API 키 또는 로케일)의 경우 요청 인터셉터를 사용하십시오.

const apiClient = axios.create({
  baseURL: 'https://api.example.com'
});

apiClient.interceptors.request.use((config) => {
  config.params = {
    api_key: process.env.API_KEY,
    locale: 'en',
    ...config.params  // 요청별 파라미터와 병합
  };
  return config;
});

// 이제 모든 요청에 api_key와 locale이 포함됩니다.
const response = await apiClient.get('/users', {
  params: { page: 1 }
});

// URL: https://api.example.com/users?api_key=xxx&locale=en&page=1

인스턴스에 기본 파라미터 설정

Axios 인스턴스를 생성할 때 기본 파라미터를 설정할 수도 있습니다.

const apiClient = axios.create({
  baseURL: 'https://api.example.com',
  params: {
    api_key: process.env.API_KEY,
    format: 'json'
  }
});

// 이러한 기본값은 요청 시 파라미터와 병합됩니다.
const response = await apiClient.get('/data', {
  params: { page: 2 }
});

// URL: https://api.example.com/data?api_key=xxx&format=json&page=2

TypeScript: 타입이 지정된 파라미터

TypeScript 프로젝트에서는 파라미터에 대한 인터페이스를 정의하십시오.

interface UserSearchParams {
  q?: string;
  page: number;
  limit: number;
  role?: 'admin' | 'user' | 'moderator';
  active?: boolean;
}

async function searchUsers(params: UserSearchParams) {
  const response = await axios.get<{ users: User[]; total: number }>(
    '/api/users',
    { params }
  );
  return response.data;
}

// 타입 세이프한 파라미터 전달
const result = await searchUsers({
  q: 'john',
  page: 1,
  limit: 20,
  role: 'admin'
});

특수 문자 인코딩

Axios는 파라미터를 자동으로 인코딩하지만, 일부 API는 특정 방식의 인코딩을 요구할 수 있습니다.

// Axios는 인코딩을 자동으로 처리합니다.
const response = await axios.get('/api/search', {
  params: {
    q: 'hello world & goodbye',  // hello%20world%20%26%20goodbye로 인코딩됨
    tag: 'c++'                     // c%2B%2B로 인코딩됨
  }
});

// 이미 인코딩된 파라미터가 이중 인코딩되는 것을 방지하려면:
const response2 = await axios.get('/api/search', {
  params: { q: 'pre-encoded%20value' },
  paramsSerializer: (params) => {
    return qs.stringify(params, { encode: false });
  }
});

실전 예제: 페이지네이션 API 클라이언트

여러 기술을 결합한 완전한 예제입니다.

import axios from 'axios';
import qs from 'qs';

const api = axios.create({
  baseURL: 'https://api.example.com/v2',
  timeout: 10000,
  paramsSerializer: (params) => {
    return qs.stringify(params, {
      arrayFormat: 'comma',
      skipNulls: true
    });
  }
});

// 모든 요청에 인증 토큰 추가
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('auth_token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// 필터가 포함된 페이지네이션 fetch
async function fetchProducts(filters = {}) {
  const { data } = await api.get('/products', {
    params: {
      page: filters.page || 1,
      per_page: filters.perPage || 20,
      sort_by: filters.sortBy || 'created_at',
      order: filters.order || 'desc',
      categories: filters.categories,   // 배열: 쉼표로 구분되어 직렬화됨
      min_price: filters.minPrice,
      max_price: filters.maxPrice,
      search: filters.search
    }
  });

  return data;
}

// 사용 예시
const products = await fetchProducts({
  page: 2,
  categories: ['electronics', 'gadgets'],
  minPrice: 50,
  sortBy: 'price'
});

// URL: /products?page=2&per_page=20&sort_by=price&order=desc&categories=electronics,gadgets&min_price=50

피해야 할 일반적인 실수

실수	문제점	해결 방법
data 필드에 파라미터 넣기	GET 요청은 data 필드를 무시함	data 대신 params 사용
URL 수동 작성	특수 문자 처리 시 오류 발생 가능	params 객체 사용
paramsSerializer 누락	기본 배열 형식이 API와 맞지 않을 수 있음	인스턴스별 직렬화 도구 설정
빈 값 처리 미흡	?key= 또는 ?key=undefined가 전송됨	Nullish 값을 필터링
이중 인코딩	%20 대신 %2520으로 인코딩됨	이미 인코딩된 경우 encode: false 사용

마무리

Axios의 params 객체는 GET 요청 파라미터 요구 사항의 대부분을 처리합니다. 배열, 중첩 객체 또는 커스텀 직렬화가 필요한 복잡한 시나리오에서는 params를 qs 라이브러리 및 paramsSerializer와 결합하십시오. 모든 요청에 동일한 파라미터가 동반되어야 할 때는 인터셉터와 인스턴스 기본값을 사용하여 코드를 중복 없이(DRY) 유지하십시오.

이미지 생성, 비디오 제작 또는 음성 합성을 위한 AI API를 호출하는 애플리케이션을 구축 중이라면, Hypereal AI를 무료로 체험해 보세요. 신용카드 없이 35크레딧을 제공합니다.. 당사의 REST API는 이 가이드에서 다룬 것과 동일한 규칙을 따르므로 Axios나 다른 HTTP 클라이언트를 사용하여 간편하게 통합할 수 있습니다.