Первое приложение FastAPI
В этом разделе на полном примере показано, как с нуля создать приложение FastAPI и понять, что означает каждая строка кода.
Минимальное приложение
Создайте один файл с именемmain.pyи добавьте следующий код:
Пример
# Шаг 1: Импортируйте класс FastAPI
# Шаг 2: Создайте экземпляр приложения
app = FastAPI()
# Шаг 3: Определите декоратор операции пути
# Шаг 4: Определите функцию операции пути
@app.get("/")
async def root():
# Шаг 5: Верните содержимое ответа
return {"message": "Hello World"}
Запустите приложение:
$ uvicorn main:app --reload
Перейдите по адресуhttp://127.0.0.1:8000, возвращает:
{"message": "Hello World"}
Разбор кода
1. Импорт FastAPI
from fastapi import FastAPI
FastAPIЭто Python-класс, который предоставляет все основные функциональные возможности для вашего API. Он напрямую наследуется от Starlette, поэтому вы также можете использовать все возможности Starlette.
2. Создание экземпляра приложения
app = FastAPI()
Создайте экземпляр FastAPI, обычно с именем переменнойapp. Этот экземпляр — основной объект взаимодействия для создания всех API. В отличие от Flask, FastAPI не требует передавать__name__параметры.
3. Определите декоратор операции пути
@app.get("/")
Эта строка кода сообщает FastAPI: когда пользователь осуществляет доступ черезGETметод к корневому пути/, выполняется функция ниже.
Здесь задействованы два понятия:
| Концепции | Описание | Пример |
|---|---|---|
| Путь | от первого ... в URL/вторая часть пути, также известная как "конечная точка" или "маршрут" | /items/foo |
| Действие | Методы HTTP соответствуют разной операционной семантике | GET、POST、PUT、DELETE |
FastAPI поддерживает декораторы для всех методов HTTP:
| декоратор | Методы HTTP | Типичные применения |
|---|---|---|
@app.get() | GET | Получение/чтение данных |
@app.post() | POST | Создание новых данных |
@app.put() | PUT | Полное обновление данных |
@app.patch() | PATCH | Частичное обновление данных |
@app.delete() | DELETE | Удаление данных |
4. Определите функцию операции пути
async def root():
Это функция операции пути; всякий раз, когда FastAPI получаетGET /запрос, он вызовет её. Вы можете назвать функцию как угодно, но рекомендуется выбрать осмысленное имя.
Вы можете использоватьasync defили обычнуюdefдля определения функции. FastAPI автоматически обрабатывает разницу между ними. Если вы не знакомы с асинхронным программированием, используйте обычнуюdefи это нормально; в следующих главах асинхронность будет подробно рассмотрена.
5. Верните содержимое ответа
return {"message": "Hello World"}
Функция возвращает словарь, и FastAPI автоматически преобразует его в JSON-ответ. Вы можете вернутьdict、list、str、intтакие типы, и FastAPI автоматически выполнит преобразование в JSON.
Добавить больше маршрутов
Далее давайте добавим параметры пути и параметры запроса, чтобы расширить функциональность приложения:
Пример
app = FastAPI()
@app.get("/")
async def root():
"""Корневой путь, возвращает приветственное сообщение"""
return {"message": "Hello World"}
@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str | None = None):
"""Получить элемент по ID с необязательным параметром запроса q"""
return {"item_id": item_id, "q": q}
Описание параметров для недавно добавленного маршрута:
| Параметр | Type | Source | Описание |
|---|---|---|---|
item_id | int | Параметр пути | получается из пути URL; FastAPI автоматически преобразует строку в целое число |
q | str | None | Параметр запроса | Из URL-адреса?q=xxxизвлекается из части, со значением по умолчаниюNone, то есть необязательный |
Проверка доступа:
# 访问根路径
GET http://127.0.0.1:8000/
响应: {"message": "Hello World"}
# 访问带路径参数的路由
GET http://127.0.0.1:8000/items/5
响应: {"item_id": 5, "q": null}
# 同时传递路径参数和查询参数
GET http://127.0.0.1:8000/items/5?q=example
响应: {"item_id": 5, "q": "example"}
Примечаниеitem_idЗначение является целым числом5Вместо строки"5"это функция преобразования данных FastAPI, основанная на объявлениях типов. Если передано нецелое число (например,/items/foo), FastAPI возвращает понятное сообщение об ошибке валидации.
Добавьте POST-запрос
Ниже мы добавляем POST-маршрут, который использует тело запроса:
Пример
from pydantic import BaseModel
app = FastAPI()
# Определите модель данных тела запроса
class Item(BaseModel):
name: str # Обязательно: название продукта
description: str | None = None # Необязательно: описание продукта
price: float # Обязательно: цена продукта
tax: float | None = None # Необязательно: налог
@app.post("/items/")
async def create_item(item: Item):
"""Создать новый продукт, принимает тело JSON-запроса."""
return item
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
"""Обновить указанный продукт, используя как параметры пути, так и тело запроса"""
return {"item_id": item_id, "item_name": item.name}
Здесь мы используем PydanticBaseModelчтобы определить структуру тела запроса. FastAPI автоматически:
- преобразует данные JSON из запроса в
ItemObject - Проверяет типы данных и обязательные поля
- отображать структуру тела запроса в документации API
Pydantic — ключевая зависимость FastAPI, используется для валидации и сериализации данных. В последующих главах его использование будет подробно рассмотрено.
Правила распознавания параметров FastAPI
FastAPI автоматически определяет источники параметров по следующим правилам:
| Источник параметра | Условие распознавания | Пример |
|---|---|---|
| Параметр пути | Имя параметра присутствует в пути маршрута{}Средняя | item_idВ/items/{item_id}Средняя |
| Параметр запроса | Параметр имеет один тип (int、str、boolи т.д.) | q: str | None = None |
| тело запроса | Тип параметра — модель Pydantic | item: Item |
Вы можете смешивать эти три типа параметров в одной функции, и FastAPI автоматически получит данные из нужного места.
Итог
Основные шаги создания приложения FastAPI:
- Импорт
FastAPI - Создайте экземпляр приложения
app = FastAPI() - Использование декораторов (таких как
@app.get()) для определения операций пути - Определите функции операций пути и объявите параметры с помощью аннотаций типов.
- Использование
uvicorn main:app --reloadЗапустите сервер разработки