[Nextjs] 필터 UI → FastAPI 다중 필터 API 연결 가이드

서론

🔍 목표

프론트엔드에서 다음과 같은 필터 UI를 구성하고:

• 브랜드 선택 (복수 가능)
• 카테고리 선택
• 가격 범위 (최소/최대)
• 정렬 기준 (가격순, 최신순 등)
• 페이지 이동

선택된 필터에 따라 FastAPI 백엔드로 query string을 만들어 API 요청을 보내는 구조를 구현한다.

---

🔗 엮인글

[🚀 Dev/Python] - [FastAPI] Swagger UI에서 POST 요청 시 JSON 입력창으로 바뀌는 이유

[🚀 Dev/Python] - [FastAPI] DELETE 요청 시 JSON이 아닌 Path Param으로 값 전달하는 방법

[🚀 Dev/Python] - [FastAPI] DELETE 요청 시 path param 여러 개 받는 방법

[🚀 Dev/Python] - [FastAPI] 쿼리 파라미터 vs path 파라미터 설계 전략

[🚀 Dev/Python] - [FastAPI] 다중 필터 검색 API 설계 (예: /products?brand=..&category=..)

[🚀 Dev/Python] - [FastAPI] 페이징, 정렬, 리스트 파라미터까지 포함한 검색 API 확장 설계

본론

---

✅ 백엔드 API 예시

GET /products?brands=samsung&brands=lg&category=가전제품&price_min=100000&price_max=500000&sort_by=price&order=asc&page=1&size=12

---

1. 프론트엔드 구조 설계 (Next.js + Axios 기준)

1.1 상태 관리 (예: useState)

const [brands, setBrands] = useState<string[]>([]);
const [category, setCategory] = useState<string | null>(null);
const [priceRange, setPriceRange] = useState<[number, number]>([0, 1000000]);
const [sortBy, setSortBy] = useState("created_at");
const [order, setOrder] = useState<"asc" | "desc">("desc");
const [page, setPage] = useState(1);
const size = 12;

---

1.2 쿼리 문자열 만들기 (URLSearchParams)

const buildQuery = () => {
  const params = new URLSearchParams();

  brands.forEach((brand) => params.append("brands", brand));
  if (category) params.append("category", category);
  if (priceRange[0]) params.append("price_min", String(priceRange[0]));
  if (priceRange[1]) params.append("price_max", String(priceRange[1]));
  params.append("sort_by", sortBy);
  params.append("order", order);
  params.append("page", String(page));
  params.append("size", String(size));

  return params.toString();
};

---

1.3 Axios 요청 보내기

const fetchProducts = async () => {
  const query = buildQuery();
  const res = await axios.get(`/api/products?${query}`);
  setProductList(res.data);
};

/api/products는 next.config.js에서 FastAPI 백엔드로 프록시 연결된 경로라고 가정

---

✅ 필터 UI 구성 예시 (React 컴포넌트)

<CheckboxGroup
  options={["samsung", "lg", "apple"]}
  value={brands}
  onChange={setBrands}
/>

<Selectoptions={["가전제품", "생활용품", "패션"]}
  value={category}
  onChange={setCategory}
/>

<PriceSlidermin={0}
  max={1000000}
  value={priceRange}
  onChange={setPriceRange}
/>

<SortDropdownoptions={[
    { value: "price", label: "가격순" },
    { value: "created_at", label: "최신순" },
  ]}
  value={sortBy}
  order={order}
  onChangeSort={setSortBy}
  onChangeOrder={setOrder}
/>

---

✅ 프론트 → 백엔드 흐름 요약

1. 사용자 입력으로 필터 상태 변경
2. 상태 기반으로 쿼리 문자열 생성
3. Axios로 백엔드 API 호출
4. FastAPI가 필터 조건에 맞는 결과 반환
5. React가 UI에 리스트 렌더링

---

🎯 정리

항목	구현 방식
다중 브랜드 선택	brands[]=a&brands[]=b
선택적 필터	값 존재 여부로 쿼리 생성 여부 판단
정렬/페이징	sort_by, order, page, size
프론트 ↔ 백엔드 연결	axios.get("/products?...")

---

✅ 결론

• FastAPI 쿼리 파라미터 기반 검색 API는 프론트에서 쉽게 연동 가능
• URLSearchParams는 가독성 높고 직관적인 쿼리 생성 방식
• 정렬/페이징도 프론트에서 상태로 관리하면 깔끔하게 구현된다