🧭 Query Parameters

FastAPI에서 Query Parameter는 URL의 ? 뒤에 붙는 값으로, 요청의 조건·옵션·범위를 지정하기 위해 사용된다.

---

📚 1. 어원으로 시작하기

• Query : 질문하다, 조회하다
• Parameter : 조건, 범위를 정하는 값

즉 Query Parameter란,

---

🌐 URL 구조로 한 번에 이해하기

http://127.0.0.1:8000/items/?skip=0&limit=10

구성 요소	의미
/items/	Path (리소스 위치)
?	Query 시작 지점
skip=0	Query Parameter
limit=10	Query Parameter

Query Parameter는 항상 key=value 형태이며, 여러 개일 경우 &로 연결된다.

---

🧠 핵심 개념 한눈에 정리

구분	Path Parameter	Query Parameter
위치	URL 경로	? 뒤
역할	리소스 식별	조건 / 옵션
필수 여부	대부분 필수	대부분 선택
예시	/users/1	?page=1

---

🧪 2. 기본 Query Parameter

FastAPI는 함수 매개변수가 Path에 없으면 자동으로 Query Parameter로 인식한다.

📄 예제

from fastapi import FastAPI

app = FastAPI()

# 가짜 데이터
fake_items_db = [
    {"item_name": "Foo"},
    {"item_name": "Bar"},
    {"item_name": "Baz"},
]

@app.get("/items/")
async def read_items(skip: int = 0, limit: int = 10):
    return fake_items_db[skip : skip + limit]

• skip : 건너뛸 항목 수 (기본값: 0)
• limit : 가져올 항목 수 (기본값: 10)

---

🌐 실행 후 테스트

http://127.0.0.1:8000/items/ → 기본값 사용 (skip=0, limit=10)

http://127.0.0.1:8000/items/?skip=0&limit=10→ 위와 동일

{"item_name": "Foo"},
{"item_name": "Bar"},
{"item_name": "Baz"}

http://127.0.0.1:8000/items/?skip=1&limit=1 → 두 번째 항목 1개

{"item_name": "Bar"}

👉 Query Parameter는 전달되지 않으면 기본값이 사용된다

---

✅ Optional Parameters (선택적 매개변수)

@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None):
    # q는 선택적 매개변수
    # 제공되면 사용하고, 없으면 None
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

q의 의미
• 쿼리(Query) 파라미터
• URL 뒤에 ?key=value 형태로 전달
• 선택 사항이다.

예를 들어..

#q=fastapi → q
/items/abc?q=fastapi

결과:

{"item_id":"abc","q":"fastapi"}

---

✅ 필수 Query Parameters

기본값 없이 선언하기

@app.get("/items/{item_id}")
async def read_user_item(item_id: str, needy: str):
    # needy는 필수 query parameter
    # 기본값이 없으므로 반드시 제공되어야 함
    item = {"item_id": item_id, "needy": needy}
    return item

만약 필수 매개변수를 제공하지 않으면,

❌ 잘못된 요청: http://127.0.0.1:8000/items/foo-item

응답:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "needy"],
      "msg": "Field required",
      "input": null
    }
  ]
}

✅ 올바른 요청: http://127.0.0.1:8000/items/foo-item?needy=essential!

응답:

{
  "item_id": "foo-item",
  "needy": "essential!"
}

---

🧠 3. 타입 선언과 자동 변환

Query Parameter는 URL에서 넘어올 때 무조건 문자열(str)이다.

하지만 FastAPI에서는 타입 힌트를 쓰는 순간,

• 자동 타입 변환
• 자동 데이터 검증

이 동시에 이루어진다.

📄 타입 변환 예제 (Boolean)

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(
    item_id: str,
    q: str | None = None,
    short: bool = False  # bool 타입 선언
):
    item = {"item_id": item_id}
    
    if q:
        item.update({"q": q})
    
    # short가 False면 긴 설명 추가
    if not short:
        item.update({
            "description": "This is an amazing item that has a long description"
        })
    
    return item

/items/{item_id}로 요청이 오면
item_id는 필수로 받고,
q와 short는 선택적으로 받아서
응답 JSON의 내용과 길이를 조건에 따라 바꾼다.

이 구조는 API 응답 최적화의 기본이다.
예시:
• 모바일 → short=true
• 웹 상세 페이지 → short=false
• 검색 API → q 사용

즉, 같은 API를 상황에 맞게 다르게 쓰는 방식이다.

✅ 자동 변환 예시

• ?short=true → True
• ?short=True → True
• ?short=on → True
• ?short=1 → True
• ?short=yes → True
• 그 외 → False

🔍 내부 동작 흐름

요청 URL
   ↓
Query 문자열 (?skip=1&limit=2)
   ↓
FastAPI 파싱
   ↓
타입 힌트 기반 변환 (str → int, bool)
   ↓
유효성 검사
   ↓
함수 실행

---

📌 기억해야 할 포인트

• 기본값이 있으면 선택 Query
• 기본값이 없으면 필수 Query
• 타입 힌트 = 변환 + 검증 + 문서
• /docs 에서 바로 테스트 가능

---

🧭 Query Parameters (심화)

🔗 여러 개의 Path + Query Parameters 함께 사용하기

FastAPI에서는 Path Parameter와 Query Parameter를 동시에 사용할 수 있다.
그리고 중요한 사실 하나:

✅ 선언 순서는 전혀 중요하지 않다
👉 이름과 위치(Path에 있느냐 없느냐)로 자동 구분된다

---

📄 예제: 사용자 + 아이템 조회 API

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(
    user_id: int,              # Path Parameter (필수)
    item_id: str,              # Path Parameter (필수)
    q: str | None = None,      # Query Parameter (선택)
    short: bool = False        # Query Parameter (기본값)
):
    item = {
        "item_id": item_id,
        "owner_id": user_id
    }

    if q:
        item["q"] = q

    if not short:
        item["description"] = "This is an amazing item with a long description"

    return item

🌐 요청 예시

/users/1/items/abc
/users/1/items/abc?q=search
/users/1/items/abc?q=search&short=true

---

🧠 FastAPI의 자동 판단 기준

기준	분류
URL 경로에 {}로 포함됨	Path Parameter
함수 매개변수지만 Path에 없음	Query Parameter
기본값 없음	필수
기본값 있음	선택

---

📚 Path vs Query — 절대 헷갈리면 안 되는 기준

기준	Path Parameter	Query Parameter
역할	리소스 식별	조건 / 옵션
위치	URL 경로	? 뒤
필수성	거의 항상 필수	대부분 선택
의미	무엇을 볼지	어떻게 볼지

🎯 리소스를 특정하면 Path, 조건을 바꾸면 Query

---

🛠 핵심 체크리스트

• ✅ Pagination → Query (page, limit)

• ✅ Search / Filter → Query

• ✅ 리소스 ID → Path

• ✅ 기본값 없는 Query = 필수

• ✅ 타입 힌트 하나로

  • 변환
  • 검증
  • 문서 자동 완성

---

📘 FastAPI가 대신 해주는 것

기능	설명
타입 변환	"1" → 1, "true" → True
검증	잘못된 값 자동 에러
문서화	/docs 자동 생성
테스트	브라우저에서 즉시 가능

---

🔚 요약

• Query Parameter는 ? 뒤에 오는 조건 값
• Query Parameter는 조건·옵션·범위
• Path Parameter는 리소스 식별
• FastAPI는 이름과 위치로 자동 구분
• 타입 힌트 하나로 API 품질이 완성됨