FastAPI 매개변수 전달를 위해 사용되는 Path와 Query의 차이점

[주인장]

✅ Path와 Query의 차이점

- FastAPI에서는 클라이언트가 전달하는 값을 함수의 파라미터로 받을 때 Path와 Query를 사용하여 어디서 값을 받을지 명확하게 지정할 수 있습니다.
- 이 둘은 목적도 다르고 사용하는 위치도 다릅니다.

✅ 핵심 차이 요약

📍 위치	URL 경로 내부 (/items/{id})	URL 경로 뒤 ?key=value 형식
💡 용도	리소스 고유 식별자 (필수인 경우가 많음)	옵션, 필터, 검색 조건 (주로 선택사항)
📌 사용 예	/users/3 (→ id = 3)	/users?age=20 (→ age = 20)
🔧 선언 방식	Path()	Query()
🔐 기본값 없음 (필수)	✅ 필수	❌ 기본값 있으면 선택적
📄 문서화	Swagger에 매개변수 위치를 다르게 표시

✅ 예제로 비교

1. Path 사용

from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int = Path(..., gt=0)):
    return {"item_id": item_id}

- 호출: /items/10 → { "item_id": 10 }

- Path(...)는 필수이며, 정수이며 0보다 커야 한다는 조건까지 포함

2. Query 사용

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_item(name: str = Query("book", max_length=10)):
    return {"name": name}

- 호출: /items/?name=pen → { "name": "pen" }

- 호출: /items/ → { "name": "book" } (기본값)

- Query()는 선택적이며, 최대 길이 제한 등 검증 가능

3. 같이 쓰이는 경우 

@app.get("/users/{user_id}")
async def get_user(user_id: int = Path(...), detail: bool = Query(False)):
    return {"user_id": user_id, "detail": detail}

- 호출: /users/5?detail=true → { "user_id": 5, "detail": true }

✅ 정리

질문 / Path / Query

URL에 직접 포함되나요?	✅ 네 (/items/{id})	❌ 아니요 (/items/?key=value)
주로 언제 쓰나요?	고유 리소스를 식별할 때	조건, 필터, 옵션 전달 시
기본값이 가능한가요?	❌ 거의 불가능 (필수)	✅ 기본값 설정 가능
FastAPI 문서화에서 위치 구분되나요?	✅