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

FastAPI에서 다중 필터 검색 API 설계하기

🔍 문제 상황

제품 목록을 필터링하는 API를 만들고 싶다.

사용자는 아래와 같이 여러 조건을 조합해서 검색할 수 있어야 한다:

GET /products?brand=apple&category=전자기기&price_min=100000&price_max=300000

이처럼 복수의 쿼리 파라미터를 받아서 조건에 따라 동적으로 필터링할 수 있는 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 확장 설계

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

---

✅  FastAPI에서 다중 필터를 처리하는 방법

FastAPI에서는 query param을 함수 인자로 받아서 손쉽게 처리할 수 있다.

from fastapi import APIRouter, Query
from typing import Optional

router = APIRouter()

@router.get("/products")
def filter_products(
    brand: Optional[str] = None,
    category: Optional[str] = None,
    price_min: Optional[int] = Query(None, alias="price_min"),
    price_max: Optional[int] = Query(None, alias="price_max")
):
    ...

---

🧠 필터링 조건에 따라 동적 쿼리 구성 (SQLAlchemy 예시)

from sqlalchemy.orm import Session
from app.models import Product

def get_filtered_products(
    db: Session,
    brand: Optional[str],
    category: Optional[str],
    price_min: Optional[int],
    price_max: Optional[int]
):
    query = db.query(Product)

    if brand:
        query = query.filter(Product.brand == brand)
    if category:
        query = query.filter(Product.category == category)
    if price_min:
        query = query.filter(Product.price >= price_min)
    if price_max:
        query = query.filter(Product.price <= price_max)

    return query.all()

---

🔄 호출 예시

GET /products?brand=samsung&category=가전&price_min=50000

• 브랜드: samsung
• 카테고리: 가전
• 가격: 50,000 이상

✅ 어떤 파라미터든 생략 가능하게 유연하게 설계됨

---

✨ Query 옵션 활용 팁

from fastapi import Query

brand: Optional[str] = Query(None, description="브랜드명")
category: Optional[str] = Query(None, description="카테고리")

➡ Swagger UI에서 각 필드에 설명이 표시되어 사용자 친화적

---

🚀 고급 확장 아이디어

• List[str]로 여러 브랜드 선택→ /products?brands=samsung&brands=lg
• brands: Optional[List[str]] = Query(None)
• 정렬 기능 추가 (sort_by, order)
• 페이징 (limit, offset 또는 page, size)

---

✅ 결론

• 다중 필터 API는 대부분의 서비스에서 필수 기능이다
• FastAPI는 쿼리 파라미터를 타입 안전하게 받을 수 있어 생산성이 높다
• 필터 조건을 동적으로 조립하는 패턴(SQLAlchemy 등)을 익혀두면 확장도 쉬워진다