Как работают параметры пути и запроса?

Question

Accepted Answer

FastAPI извлекает **параметры пути** (часть пути URL) и **параметры запроса** (после `?`) из аргументов функции, используя type hints для их автоматического преобразования и проверки.

## Параметры пути — часть URL

```python
@app.get("/items/{item_id}")        # {item_id} in the path
def get_item(item_id: int):          # matched by NAME; `int` converts & validates
    return {"item_id": item_id}
# GET /items/5 → item_id = 5 (int).  GET /items/abc → 422 error (not an int)
```

Параметр функции, имя которого совпадает с `{placeholder}` в пути, становится **параметром пути**. Type hint (`int`) автоматически преобразует строку из URL и возвращает четкую ошибку 422, если она не совпадает.

## Параметры запроса — все остальное

```python
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, q: str | None = None):
    # parameters NOT in the path become QUERY parameters
    # GET /items?skip=20&limit=5&q=phone → skip=20, limit=5, q="phone"
    return {"skip": skip, "limit": limit, "q": q}
```

Параметры функции **не** в пути становятся **параметрами запроса**. Значение по умолчанию делает их необязательными (`skip: int = 0`); `str | None = None` создает необязательный параметр запроса, допускающий null. Без значения по умолчанию они обязательны.

## Обязательный vs необязательный

```python
def search(q: str):              # REQUIRED query param (no default) → ?q=... must be present
def search(q: str = ""):          # optional, defaults to ""
def search(q: str | None = None): # optional, defaults to None
```

## Объединение обоих

```python
@app.get("/users/{user_id}/items")
def user_items(user_id: int, limit: int = 10):
    # user_id = path param, limit = query param — distinguished by the path
```

## Почему это важно

Параметры пути и запроса — это способ, которым конечные точки получают входные данные из URL — основной для почти каждого маршрута API (получение ресурса по id, фильтрация, разбиение на страницы, поиск).

Подход FastAPI элегантен и является ключевой причиной его производительности: простое объявление типизированных параметров функции дает вам автоматическое извлечение, **преобразование типа**, **валидацию** (с четкими ошибками 422 при неправильном вводе) и семантику обязательного-vs-необязательного (через значения по умолчанию) — все выведено из стандартных type hints Python, без ручного анализа.

Понимание различия (параметры пути поступают из `{placeholders}`, все остальное — параметр запроса) и того, как значения по умолчанию управляют необязательностью, — это необходимые повседневные знания для создания конечных точек FastAPI.