경로 매개변수와 쿼리 매개변수는 어떻게 동작합니까?

Question

Accepted Answer

FastAPI는 함수 인자로부터 **경로 매개변수**(URL 경로의 일부)와 **쿼리 매개변수**(`?` 이후)를 추출하며, 타입 힌트를 사용해 이를 자동으로 변환하고 검증합니다.

## 경로 매개변수 — URL 경로의 일부

```python
@app.get("/items/{item_id}")        # 경로 안의 {item_id}
def get_item(item_id: int):          # 이름으로 매칭됨; `int`가 변환 및 검증합니다
    return {"item_id": item_id}
# GET /items/5 → item_id = 5 (int).  GET /items/abc → 422 오류 (int가 아님)
```

경로의 `{placeholder}`와 이름이 일치하는 함수 매개변수는 **경로 매개변수**가 됩니다. 타입 힌트(`int`)는 URL의 문자열을 자동 변환하고, 일치하지 않으면 명확한 422 오류를 반환합니다.

## 쿼리 매개변수 — 그 외 모든 것

```python
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, q: str | None = None):
    # 경로에 없는 매개변수는 쿼리 매개변수가 됩니다
    # GET /items?skip=20&limit=5&q=phone → skip=20, limit=5, q="phone"
    return {"skip": skip, "limit": limit, "q": q}
```

경로에 **없는** 함수 매개변수는 **쿼리 매개변수**가 됩니다. 기본값을 지정하면 선택적(optional)이 되고(`skip: int = 0`), `str | None = None`은 nullable 선택적 쿼리 매개변수를 만듭니다. 기본값이 없으면 필수가 됩니다.

## 필수 vs 선택

```python
def search(q: str):              # 필수 쿼리 매개변수 (기본값 없음) → ?q=...가 반드시 있어야 함
def search(q: str = ""):          # 선택적, 기본값 ""
def search(q: str | None = None): # 선택적, 기본값 None
```

## 둘을 결합하기

```python
@app.get("/users/{user_id}/items")
def user_items(user_id: int, limit: int = 10):
    # user_id = 경로 매개변수, limit = 쿼리 매개변수 — 경로로 구분됨
```

## 왜 중요한가

경로 및 쿼리 매개변수는 엔드포인트가 URL로부터 입력을 받는 방식으로, 거의 모든 API 라우트(id로 리소스 조회, 필터링, 페이지네이션, 검색)에 근본적입니다.

FastAPI의 접근 방식은 우아하며 생산성의 핵심 이유입니다. 타입이 지정된 함수 매개변수를 선언하기만 하면 자동 추출, **타입 변환**, **validation**(잘못된 입력 시 명확한 422 오류), 그리고 필수-vs-선택 의미론(기본값을 통해)을 제공합니다. 이 모두가 표준 Python 타입 힌트로부터 파생되며 수동 파싱이 필요 없습니다.

구분(경로 매개변수는 `{placeholder}`에서 오고, 나머지는 모두 쿼리 매개변수)과 기본값이 선택 여부를 어떻게 제어하는지 이해하는 것은 FastAPI 엔드포인트를 구축하기 위한 필수적인 일상 지식입니다.