Налаштування проєкту та структура застосунку FastAPI

Уяви, що ти будуєш дім. Якщо у тебе буде кривий фундамент і безлад у розміщенні кімнат, то жити там буде некомфортно, а ремонт обійдеться значно дорожче. У програмуванні так само: одноразове налаштування проєкту з чіткою структурою робить розробку простішою, а масштабування застосунку — менш болючим. Колеги приємно віддячать (і, можливо, ще додадуть тобі "👍" у Slack).

FastAPI дає гнучкість у організації проєкту, але з цією свободою приходить і велика відповідальність. Сьогодні розберемося, як організувати файли і модулі так, щоб у тебе вийшов чистий і зрозумілий код.

---

Мінімальна структура FastAPI-проєкту

На цьому етапі нам знадобиться лише кілька базових елементів:

project/
└── app/
    ├── main.py
    └── __init__.py

• main.py — це точка входу. У ньому ми будемо реєструвати ендпоіни та запускати наш застосунок.
• __init__.py — пустий файл, який позначає, що папка app є Python-пакетом.

Давай створимо цю структуру в робочій директорії.

---

Початкове налаштування файлу main.py

main.py — це серце нашого застосунку. У ньому ми створюємо об'єкт застосунку FastAPI і описуємо ендпоіни. Зараз зробимо базове налаштування:

# app/main.py

from fastapi import FastAPI

# Створюємо екземпляр застосунку
app = FastAPI()

# Привітання для перевірки працездатності
@app.get("/")
async def root():
    return {"message": "Привіт, FastAPI!"}

Зберіг файл? Супер! А як запустити це диво?

---

Запуск застосунку

Для цього нам потрібен Uvicorn — сервер, який підтримує FastAPI. У терміналі виконай команду:

uvicorn app.main:app --reload

Розберемо її:

• app.main — це шлях до твого модуля (папка app, файл main.py).
• app — це об'єкт застосунку, який ми створили в main.py.
• --reload — активує автоматичне перезавантаження сервера при зміні коду. Зручно під час розробки.

Тепер відкрий у браузері http://127.0.0.1:8000. Якщо ти побачив повідомлення {"message": "Привіт, FastAPI!"}, вітаю — ти молодець!

О, і не забудь перевірити вбудовану документацію API за адресою http://127.0.0.1:8000/docs. Так, FastAPI створює її автоматично!

---

Розвиток структури: модулі, маршрути і налаштування

Звісно, у реальних проєктах код не вміщується в одному файлі. Додаємо трохи структури і логіки.

Розширюємо структуру проєкту

На цьому етапі вона виглядатиме так:

project/
└── app/
    ├── main.py
    ├── __init__.py
    ├── routes/
    │   ├── __init__.py
    │   └── example_routes.py
    └── config.py

• routes/ — сюди кладемо маршрути (ендпоіни). Наприклад, обробка запитів для користувачів, товарів тощо.
• config.py — файл для зберігання налаштувань, таких як параметри підключення до бази даних або конфігурація логування.

Виносимо маршрути в окремий модуль

Створимо файл example_routes.py у папці routes:

# app/routes/example_routes.py

from fastapi import APIRouter

router = APIRouter()

@router.get("/greet")
async def greet_user(name: str = "Гість"):
    return {"message": f"Привіт, {name}!"}

Зверни увагу на об'єкт APIRouter. Це зручний спосіб групувати маршрути і підключати їх до основного застосунку.

Тепер підключимо цей роутер у main.py:

# app/main.py

from fastapi import FastAPI
from app.routes import example_routes

app = FastAPI()

# Підключаємо маршрути з example_routes
app.include_router(example_routes.router)

@app.get("/")
async def root():
    return {"message": "Привіт, FastAPI!"}

Перезапусти сервер. Тепер, якщо перейдеш за адресою http://127.0.0.1:8000/greet?name=Пітон, API з радістю привітає тебе: {"message": "Привіт, Пітон!"}.

Виносимо налаштування в config.py

Файл config.py дозволяє зручно працювати з environment-перемінними та налаштуваннями. Приклад:

# app/config.py

from pydantic import BaseSettings

class Settings(BaseSettings):
    app_name: str = "Мій FastAPI-додаток"
    debug: bool = True

    class Config:
        env_file = ".env"

settings = Settings()

Тепер ти можеш використати цей файл будь-де в застосунку. Наприклад, виведемо назву застосунку в main.py:

# app/main.py

from fastapi import FastAPI
from app.config import settings
from app.routes import example_routes

app = FastAPI(title=settings.app_name)

app.include_router(example_routes.router)

@app.get("/")
async def root():
    return {"message": f"Ласкаво просимо в {settings.app_name}!"}

Не забудь створити файл .env на рівні проєкту і покласти в нього свої environment-перемінні:

APP_NAME=Мій супер-додаток
DEBUG=True

Для великих проєктів pydantic і змінні оточення допоможуть додавати нові налаштування без правок основного коду.

---

Практичні поради з організації FastAPI-проєкту

1. Групуй маршрути за функціоналом. Наприклад, всі маршрути для користувачів можна покласти в user_routes.py, а для замовлень — в order_routes.py.
2. Використовуй модульні тести. Переконайся, що кожен файл можна протестувати окремо. Це стане в пригоді, коли проєкт виросте.
3. Слідкуй за читабельністю. Якщо файл стає довгим, розбивай його на кілька модулів.
4. Пиши документацію. Особливо важливо для маршрутів зі нестандартною поведінкою.

---

На цьому налаштування й базова структура завершені. Ми вже створили фундамент для більш складного застосунку. В наступних лекціях ми вивчимо більше про маршрутизацію, роботу з запитами і даними. Готуйся до нових викликів і цікавих фіч FastAPI! 🚀