Сообщить об ошибкеКороткий ответ
Path-параметр — обязательная часть самого URL, идентифицирующая конкретный ресурс (например, /users/42); query-параметр передаётся после ? и обычно используется для фильтрации, сортировки или пагинации.
Как это работает подробнее
В FastAPI path-параметр объявляется в шаблоне маршрута через {имя} и обязателен — без него маршрут просто не совпадёт. Query-параметр не входит в шаблон пути: любой параметр функции, не являющийся path-параметром или моделью тела, по умолчанию становится query-параметром.
Пример кода
example.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/orders/{order_id}")
def get_order(order_id: int, include_items: bool = False):
# order_id - path-параметр (обязателен, часть URL)
# include_items - query-параметр (необязателен)
return {"order_id": order_id, "include_items": include_items}
# GET /orders/5?include_items=true -> {"order_id": 5, "include_items": true}Что использовать на практике
- Практика. Path используют для идентификации сущности (
/orders/{order_id}), query — для необязательных модификаторов списка (/orders?status=paid&page=2). Это соответствует общепринятым REST-конвенциям и упрощает кэширование и логирование по пути.
Подводные камни
- Риск. Передают идентификатор ресурса как query-параметр (
/orders?order_id=5) вместо пути, что ломает REST-семантику и усложняет кэширование; делают обязательные фильтры query-параметрами без значения по умолчанию, из-за чего клиенту приходится их всегда указывать.