Fastapi.FastAPI: примеры (PYTHON)

Простые примеры использования

Минимальное приложение:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Hello World"}

Запуск через Uvicorn: uvicorn main:app --reload. Результат обращения к GET /:

{"message": "Hello World"}

Создание приложения с кастомными настройками:

from fastapi import FastAPI

app = FastAPI(
    title="My API",
    description="Это мое тестовое API.",
    version="1.0.0",
    docs_url="/api/docs",
    redoc_url=None
)

Документация станет доступна по адресу /api/docs, а ReDoc будет отключен.

Похожие фреймворки и функции на Python

В экосистеме Python существуют альтернативные инструменты для создания веб-API.

• Flask (Flask(__name__)): Микрофреймворк, более низкоуровневый. FastAPI построен на Starlette и предоставляет автоматическую валидацию, сериализацию и документацию "из коробки", чего у Flask нет. Flask предпочтителен для очень простых приложений или когда нужен полный контроль над компонентами.
• Django (django.core.wsgi.get_wsgi_application()): Монолитный фреймворк "батарейки включены". Создание API требует дополнительных библиотек (Django REST framework). Выбор падает на Django, если нужна полноценная веб-платформа с ORM, админ-панелью и многими встроенными компонентами. FastAPI легче и быстрее для задач, где требуется только высокопроизводительное API.
• Starlette (starlette.applications.Starlette): Асинхронный фреймворк низкого уровня, на котором построен FastAPI. Непосредственное использование Starlette требует ручной реализации многих функций (валидация, документация), но дает максимальную гибкость.

Аналоги в других языках программирования

• JavaScript/Node.js: Express.js

  const express = require('express');
  const app = express();
  app.get('/', (req, res) => res.json({ message: 'Hello' }));
  app.listen(3000);

  Аналог создания экземпляра приложения. Express не предоставляет встроенной валидации или автоматической документации, эти функции добавляются middleware.
• Java: Spring Boot (аннотация @SpringBootApplication)

  @SpringBootApplication
  @RestController
  public class DemoApplication {
      public static void main(String[] args) {
          SpringApplication.run(DemoApplication.class, args);
      }
      @GetMapping("/")
      public String hello() { return "Hello"; }
  }

  Spring Boot более комплексный и требует компиляции, но предоставляет мощный IoC-контейнер и множество интеграций.
• PHP: Laravel (Laravel Lumen)

  $app = new Laravel\Lumen\Application(
      dirname(__DIR__)
  );
  $app->router->get('/', function () {
      return 'Hello';
  });

  Lumen - микрофреймворк на основе Laravel, предлагает элегантный синтаксис и множество функций, но работает в синхронном блокирующем режиме по умолчанию.
• Golang: net/http или Gin

  // Gin
  r := gin.Default()
  r.GET("/", func(c *gin.Context) {
      c.JSON(200, gin.H{"message": "hello"})
  })
  r.Run()

  Gin предоставляет высокую производительность, близкую к FastAPI, но без автоматической генерации схемы OpenAPI по умолчанию.

Типичные ошибки

• Неправильный порядок middleware или обработчиков событий (lifespan). Обработчики событий должны быть определены до создания экземпляра приложения, если используется контекстный менеджер.

  # Неправильно
  app = FastAPI()
  @app.on_event("startup") # Устаревший способ
  async def startup_event():
      print("Starting up")

  # Правильно (для FastAPI 3.0+ с lifespan)
  from contextlib import asynccontextmanager
  from fastapi import FastAPI
  
  @asynccontextmanager
  async def lifespan(app: FastAPI):
      print("Startup")
      yield
      print("Shutdown")
  
  app = FastAPI(lifespan=lifespan) # Аргумент передается при создании

• Конфликтующие пути для документации. Установка docs_url или openapi_url в значение, которое уже используется другим маршрутом, приводит к перезаписи.

  app = FastAPI(docs_url="/api")
  
  @app.get("/api") # Этот маршрут перезапишет документацию!
  async def my_endpoint():
      return {"data": "something"}

  При обращении к GET /api будет вызвана функция my_endpoint, а документация станет недоступна по этому адресу.

Изменения в последних версиях

В FastAPI 0.100.0 и выше устарел декоратор @app.on_event("startup"/"shutdown") в пользу использования параметра lifespan при создании экземпляра приложения. Новый подход более гибкий и соответствует стандарту ASGI.

Интеграция с Pydantic v2, начиная с FastAPI 0.100.0, принесла значительное повышение производительности валидации и сериализации.

Аргумент root_path_in_servers был упразднен, логика автоматического определения root_path из запросов улучшена.

Расширенные примеры

Использование кастомной схемы OpenAPI с тегами и серверами:

from fastapi import FastAPI

app = FastAPI(
    title="Advanced API",
    openapi_tags=[
        {
            "name": "items",
            "description": "Операции с предметами",
        },
        {
            "name": "users",
            "description": "Управление пользователями",
        },
    ],
    servers=[
        {"url": "https://api.example.com", "description": "Production"},
        {"url": "http://localhost:8000", "description": "Development"},
    ],
    terms_of_service="http://example.com/terms/",
    contact={
        "name": "Support Team",
        "email": "support@example.com",
    },
    license_info={
        "name": "MIT",
        "url": "https://opensource.org/licenses/MIT",
    },
)

@app.get("/items/", tags=["items"])
async def read_items():
    return [{"name": "Item 1"}]

@app.post("/users/", tags=["users"])
async def create_user():
    return {"status": "created"}

Полное отключение документации и схемы OpenAPI:

app = FastAPI(
    openapi_url=None,
    docs_url=None,
    redoc_url=None
)
# Приложение будет обслуживать только пользовательские маршруты.

Использование lifespan для управления состоянием приложения (кэш, подключения к БД):

from contextlib import asynccontextmanager
from fastapi import FastAPI
from typing import Dict

# Глобальное состояние (например, кэш в памяти)
app_state: Dict[str, any] = {}

@asynccontextmanager
async def lifespan(app: FastAPI):
    # При запуске
    app_state["cache"] = {}
    app_state["database_ready"] = True
    print("Приложение запущено")
    yield
    # При остановке
    app_state.clear()
    print("Приложение остановлено")

app = FastAPI(lifespan=lifespan)

@app.get("/state")
async def get_state():
    return {"state": app_state}

Настройка приложения для работы за прокси (например, Traefik) с использованием root_path:

# Приложение доступно по https://example.com/api/v1
app = FastAPI(root_path="/api/v1")

@app.get("/app")
async def read_main():
    return {"message": "Hello World", "root_path": app.root_path}
# Фактический путь к эндпоинту будет /api/v1/app
# В документации пути будут скорректированы.