FastAPI. Часть 2. Path и Query параметры, обработка запросов

В предыдущем уроке мы создали первый API на FastAPI и научились обрабатывать простые запросы. Мы создавали маршруты, возвращали JSON-ответы, использовали параметры из тела запроса. Но в реальных приложениях клиенты передают данные разными способами: через параметры в самом URL (например, /users/5 — это ID пользователя), через параметры после знака вопроса (например, /users?age=25&city=Москва — это фильтры), через тело запроса в формате JSON (при создании или обновлении данных), через HTML-формы (при отправке данных с веб-страницы) и через загрузку файлов (изображения, документы). FastAPI предоставляет удобные инструменты для работы с каждым из этих типов данных, и понимание этих инструментов — ключ к созданию профессиональных API.

В этом уроке (втором из двух по основам FastAPI) мы подробно изучим все способы получения данных от клиента. Вы узнаете, что такое Path параметры — переменные части URL, которые позволяют извлекать значения, такие как ID пользователя или название товара. Например, в URL /users/5 число 5 — это Path параметр. FastAPI автоматически извлекает его из URL и передаёт в вашу функцию. Научимся указывать тип данных для Path параметров (строка, число, UUID), задавать значения по умолчанию и валидировать их.

Познакомимся с Query параметрами — это параметры, которые передаются после знака вопроса в URL. Например, в запросе /users?limit=10&offset=20 параметры limit и offset являются Query параметрами. Они часто используются для фильтрации (показать только пользователей из Москвы), сортировки (сортировать по имени или возрасту) и пагинации (показывать по 10 записей на странице). Вы научитесь объявлять Query параметры в FastAPI, задавать значения по умолчанию, делать их опциональными и валидировать (например, проверять, что limit не больше 100).

Изучим Body параметры — данные, которые передаются в теле HTTP-запроса в формате JSON. Это основной способ передачи сложных данных при создании и обновлении ресурсов. Например, при создании нового пользователя клиент отправляет JSON с полями name, email, age. Вы научитесь использовать Pydantic-схемы для описания структуры тела запроса и автоматической валидации (проверка типов, обязательных полей, формата email).

Освоим Form параметры — данные из HTML-форм, которые кодируются в формате application/x-www-form-urlencoded (как при отправке обычной формы на веб-странице) или multipart/form-data (для форм с файлами). Например, когда пользователь заполняет форму регистрации на сайте и нажимает «Отправить», данные приходят именно как Form параметры. Научимся получать данные из форм с помощью Form().

Научимся загружать файлы на сервер с помощью File() и UploadFile. Разберём, как получать метаинформацию о файле (имя, тип, размер) и сохранять файлы на диск. Изучим разницу между bytes и UploadFile: bytes загружает весь файл в память (хорошо для маленьких файлов, например, аватарок), UploadFile работает как поток, читая файл по частям (хорошо для больших файлов, например, видео).

Все примеры будут максимально практичными: создадим API для интернет-магазина с фильтрацией товаров по цене и категории, пагинацией, созданием заказов через JSON-тело, обработкой форм для подписки на рассылку и загрузкой изображений товаров. К концу урока вы будете уверенно работать с любыми типами данных в FastAPI.