03 경로 매개변수와 쿼리 매개변수 | ✅ 편저: 코담 운영자

3강: FastAPI 경로 매개변수와 쿼리 매개변수

🔗 소스

---

🔗 경로 매개변수 (Path Parameters)

경로 매개변수는 URL 경로의 일부로 동적인 값을 전달할 때 사용됩니다. 주로 특정 리소스(예: 사용자 ID, 상품 ID 등)를 조회할 때 활용됩니다.

📌 예제 1: 정수형 경로 매개변수

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
def read_user(user_id: int):
    return {"user_id": user_id}

• /users/1 요청 시 user_id = 1로 동작
• user_id는 정수로 타입 지정 (int)

📌 예제 2: 문자열 경로 매개변수

@app.get("/items/{item_name}")
def read_item(item_name: str):
    return {"item_name": item_name}

• /items/book 요청 시 item_name = "book"

---

❓ 쿼리 매개변수 (Query Parameters)

쿼리 매개변수는 URL의 ? 뒤에 붙는 키-값 쌍입니다. 필터, 검색, 정렬 등에 주로 사용됩니다.

📌 예제 3: 필수 쿼리 파라미터

@app.get("/users")
def get_user(user_id: int, name: str):
    return {"user_id": user_id, "name": name}

• /users?user_id=1&name=John 요청 시 파라미터 추출

📌 예제 4: 선택적 쿼리 파라미터

from typing import Optional

@app.get("/users")
def get_user(user_id: int, name: Optional[str] = None):
    response = {"user_id": user_id}
    if name:
        response["name"] = name
    return response

• name이 없는 경우에도 요청 가능: /users?user_id=1
• 있으면 포함, 없으면 생략

---

🔀 경로 매개변수 + 쿼리 매개변수 조합

둘을 조합하면 더욱 유연한 라우팅이 가능합니다.

📌 예제 5: path + query

@app.get("/users/{user_id}/details")
def user_details(user_id: int, include_email: bool = False):
    result = {"user_id": user_id}
    if include_email:
        result["email"] = "user@example.com"
    return result

• /users/1/details?include_email=true → 이메일 포함 응답
• /users/1/details → 기본값 false, 이메일 없음

---

🧪 문서 테스트 활용

• Swagger UI (/docs)에서 모든 경로 및 매개변수 테스트 가능
• 자동 입력창과 실행 결과 확인 가능

---

✅ 요약

• 경로 매개변수: URL의 일부 → 리소스 식별용
• 쿼리 매개변수: URL 뒤 ? 이후 → 옵션, 필터, 검색용
• 조합 사용으로 강력하고 유연한 API 설계 가능

다음 강의에서는 요청(Request)과 응답(Response) 본문을 다루며 FastAPI의 데이터 처리 능력을 더 깊이 살펴봅니다.

📌 참고: 본 강의는 FastAPI 학습 시리즈 기반으로 제작되었습니다.