Python

Flask w Pythonie — pierwsza aplikacja z walidacją i testami

Pierwsza aplikacja we Flasku: lokalny serwer, trasy GET i POST, walidacja JSON, bezpieczne błędy i pięć testów w pytest. Plus kiedy wybrać Django lub FastAPI.

Zespół LearnIT

9 minutZaktualizowano:
Flask w Pythonie — pierwsza aplikacja z walidacją i testami

Krótka odpowiedź

Flask to lekki framework Pythona do aplikacji webowych i prostych API, działający po stronie serwera. Pierwszą aplikację zbudujesz lokalnie w sześciu krokach: wirtualne środowisko z Flask i pytest, plik app.py z fabryką aplikacji, uruchomienie serwera deweloperskiego, sprawdzenie tras GET i POST, pięć testów klientem testowym oraz przegląd typowych błędów.

Spis treści · 8
  1. 01Do czego służy Flask i jaką aplikację warto zbudować na początek?
  2. 02Jak przygotować środowisko i uruchomić serwer lokalnie?
  3. 03Jak działa trasa, żądanie i odpowiedź we Flasku?
  4. 04Jak sprawdzić dane wejściowe i bezpiecznie obsłużyć błędy?
  5. 05Jakimi testami udowodnić, że trasy działają?
  6. 06Jakie błędy najczęściej zatrzymują pierwszą aplikację?
  7. 07Kiedy wybrać Django lub FastAPI zamiast Flaska?
  8. 08Co dalej po pierwszej aplikacji we Flasku?

Flask to lekki framework Pythona do budowy aplikacji webowych i prostych API. Daje routing, obsługę żądań i odpowiedzi, serwer deweloperski oraz klienta testowego, a resztę dobierasz sam. Pierwszą aplikację zbudujesz w jednym pliku: dwa adresy, walidacja danych JSON, czytelne komunikaty błędów i pięć testów w pytest — wszystko uruchomione lokalnie, bez publicznego dostępu.

Zakładamy, że znasz podstawy Pythona: funkcje, słowniki, moduły i pracę w terminalu. Ten tekst nie jest porównaniem frameworków — jeśli dopiero wybierasz, zajrzyj do artykułu Django, Flask czy FastAPI. Tutaj budujemy jeden mały, domknięty projekt, który możesz uruchomić, sprawdzić testami i rozbudować.

Do czego służy Flask i jaką aplikację warto zbudować na początek?

Flask działa po stronie serwera. Przyjmuje żądanie HTTP od przeglądarki lub innego programu, wykonuje Twój kod w Pythonie i odsyła odpowiedź: stronę HTML, dane w formacie JSON albo komunikat błędu. To, co dzieje się w przeglądarce (kliknięcia, animacje), należy do frontendu. Flask nie ma wbudowanego ORM, systemu kont ani panelu administracyjnego — te elementy dodajesz rozszerzeniami, gdy są potrzebne. Dlatego dobrze nadaje się do małych serwisów, prototypów, narzędzi wewnętrznych i nauki tego, jak naprawdę działa HTTP.

Czy Flask jest nadal używany? Tak — projekt jest rozwijany, ma aktualną dokumentację i spotyka się go w ogłoszeniach obok Django i FastAPI. Aktualną wersję i wymagania sprawdzaj w oficjalnej dokumentacji Flask, a nie w starszych tutorialach, bo część z nich pokazuje przestarzały sposób uruchamiania aplikacji.

Na pierwszy projekt wybierz zadanie, które da się sprawdzić w kilka minut. Proponujemy mini-serwis notatek:

  • adres /zdrowie odpowiada, że aplikacja działa,
  • GET /notatki zwraca listę notatek w formacie JSON,
  • POST /notatki przyjmuje nową notatkę i ją zapisuje,
  • pusty lub zbyt długi tekst zostaje odrzucony z czytelnym komunikatem,
  • nieznany adres zwraca błąd 404 w formacie JSON, a nie stronę z opisem wyjątku.

Notatki trzymamy w pamięci procesu, więc znikną po restarcie. To świadoma decyzja: bez bazy danych widać samą mechanikę frameworka. Nie przechowujemy też żadnych danych osobowych — do nauki wystarczą zwykłe teksty.

Jak przygotować środowisko i uruchomić serwer lokalnie?

Cała ścieżka ma sześć kroków. Komendy dotyczą systemów Linux i macOS; na Windowsie inaczej wygląda tylko aktywacja wirtualnego środowiska, opisana w dokumentacji Pythona.

  1. Utwórz katalog projektu i wirtualne środowisko, a następnie zainstaluj Flask i pytest.
  2. Zapisz aplikację w pliku app.py z funkcją create_app.
  3. Uruchom serwer deweloperski poleceniem flask run i sprawdź adres /zdrowie.
  4. Wyślij poprawną i błędną notatkę metodą POST i porównaj odpowiedzi.
  5. Napisz testy w pliku test_app.py i uruchom je poleceniem pytest.
  6. Przejdź przez listę kontrolną błędów, zanim uznasz projekt za gotowy.

Krok pierwszy w terminalu:

Terminal
mkdir notatki-flask && cd notatki-flask
python3 -m venv .venv
source .venv/bin/activate
pip install flask pytest
pip freeze > requirements.txt

Na macOS i w wielu dystrybucjach Linuksa interpreter nazywa się python3, a polecenie python działa dopiero po aktywacji wirtualnego środowiska. Na Windowsie środowisko utworzysz poleceniem py -m venv .venv i aktywujesz przez .venv\Scripts\activate.

Plik requirements.txt zapisuje wersje, które faktycznie zainstalowałeś. Nie przepisuj numerów wersji z artykułów — ten plik jest jedynym wiarygodnym źródłem informacji o tym, na czym działa Twój projekt.

Gdy plik app.py z następnej sekcji będzie gotowy, serwer uruchomisz tak:

Terminal
flask --app app run --debug

Domyślnie serwer nasłuchuje tylko na adresie lokalnym 127.0.0.1, więc aplikacja jest dostępna wyłącznie z Twojego komputera. Tak ma zostać. Tryb --debug pokazuje szczegóły błędów i włącza interaktywny debugger, który pozwala wykonywać kod na serwerze — dlatego nigdy nie łącz go z udostępnieniem aplikacji w sieci (opcja --host). Serwer deweloperski Flask służy do pracy lokalnej, nie do publikacji.

Jak działa trasa, żądanie i odpowiedź we Flasku?

Trasa (route) to powiązanie adresu i metody HTTP z funkcją w Pythonie. Gdy przychodzi żądanie, Flask sprawdza adres i metodę, wywołuje pasującą funkcję, a to, co ona zwróci, zamienia w odpowiedź HTTP. Zwrócony słownik staje się odpowiedzią JSON. Para „słownik, liczba” ustawia dodatkowo kod statusu, na przykład 201 dla utworzonego zasobu albo 400 dla błędnych danych. Cała aplikacja mieści się w pliku app.py:

Python
from flask import Flask, jsonify, request


def create_app():
    app = Flask(__name__)
    notatki = []

    @app.get("/zdrowie")
    def zdrowie():
        return {"status": "ok"}

    @app.get("/notatki")
    def lista_notatek():
        return {"notatki": notatki}

    @app.post("/notatki")
    def dodaj_notatke():
        dane = request.get_json(silent=True)
        if not isinstance(dane, dict):
            return {"blad": "Oczekiwano obiektu JSON."}, 400
        tekst = dane.get("tekst")
        if not isinstance(tekst, str) or not tekst.strip():
            return {"blad": "Pole 'tekst' jest wymagane."}, 400
        if len(tekst) > 200:
            return {"blad": "Pole 'tekst' może mieć najwyżej 200 znaków."}, 400
        notatka = {"id": len(notatki) + 1, "tekst": tekst.strip()}
        notatki.append(notatka)
        return notatka, 201

    @app.errorhandler(404)
    def nie_znaleziono(error):
        return jsonify(blad="Nie ma takiego adresu."), 404

    return app


app = create_app()

Kilka rzeczy wartych uwagi. Dekoratory @app.get i @app.post to skrócony zapis trasy z jedną metodą HTTP. Obiekt request daje dostęp do danych bieżącego żądania: nagłówków, parametrów i treści. Funkcja create_app, tzw. fabryka aplikacji, tworzy nową, czystą instancję przy każdym wywołaniu. Dzięki temu każdy test dostanie własną, pustą listę notatek i testy nie będą sobie przeszkadzać.

Po uruchomieniu serwera sprawdź działanie z drugiego terminala:

Terminal
curl http://127.0.0.1:5000/zdrowie
curl -X POST -H "Content-Type: application/json"      -d '{"tekst": "Przeczytać dokumentację Flask"}'      http://127.0.0.1:5000/notatki
curl http://127.0.0.1:5000/notatki

Port 5000 jest domyślny; jeśli terminal z serwerem pokazuje inny adres, użyj tego z terminala.

Jak sprawdzić dane wejściowe i bezpiecznie obsłużyć błędy?

Zasada jest prosta: każde dane, które przychodzą z zewnątrz, traktuj jako niezaufane, dopóki ich nie sprawdzisz. W funkcji dodaj_notatke walidacja ma trzy poziomy. Najpierw sprawdzamy, czy treść żądania w ogóle jest obiektem JSON — parametr silent=True sprawia, że przy błędnym formacie dostajemy None zamiast wyjątku. Potem, czy pole tekst istnieje, jest napisem i nie składa się z samych spacji. Na koniec ograniczamy długość, żeby nikt nie zapisał w pamięci serwera dowolnie dużego tekstu.

Równie ważne jest to, co aplikacja mówi, gdy coś pójdzie nie tak. Komunikat dla klienta ma wyjaśnić, co poprawić („pole jest wymagane”), ale nie powinien zdradzać szczegółów wnętrza aplikacji: ścieżek plików, treści wyjątków ani konfiguracji. Własna obsługa błędu 404 zwraca krótki JSON, zamiast domyślnej strony HTML, co ułatwia pracę programom korzystającym z API.

Gdy aplikacja zacznie zwracać strony HTML, pamiętaj o jeszcze jednej regule: tekst od użytkownika wstawiaj do stron przez szablony Flaska (Jinja) z rozszerzeniem .html — w nich Flask domyślnie zamienia znaki specjalne HTML na bezpieczne odpowiedniki. Ręczne sklejanie HTML z danych wejściowych to prosta droga do błędu bezpieczeństwa. Szerszy kontekst zabezpieczeń aplikacji webowych opisujemy w tekście bezpieczeństwo aplikacji webowych — jak zacząć.

Wolisz uczyć się w ustalonej kolejności?

Sprawdź kurs Python Developer w LearnIT — program, projekty i feedback do kodu.

Zobacz program

Jakimi testami udowodnić, że trasy działają?

Flask ma wbudowanego klienta testowego, który wysyła żądania do aplikacji bez uruchamiania serwera. W połączeniu z pytest daje szybkie, powtarzalne sprawdzenie wszystkich warunków z listy na początku artykułu. Zapisz plik test_app.py obok app.py:

Python
import pytest

from app import create_app


@pytest.fixture
def client():
    app = create_app()
    app.config["TESTING"] = True
    return app.test_client()


def test_zdrowie(client):
    odpowiedz = client.get("/zdrowie")
    assert odpowiedz.status_code == 200
    assert odpowiedz.get_json() == {"status": "ok"}


def test_dodanie_notatki(client):
    odpowiedz = client.post("/notatki", json={"tekst": "Kupić mleko"})
    assert odpowiedz.status_code == 201
    assert client.get("/notatki").get_json()["notatki"][0]["tekst"] == "Kupić mleko"


def test_pusty_tekst_jest_odrzucony(client):
    odpowiedz = client.post("/notatki", json={"tekst": "   "})
    assert odpowiedz.status_code == 400
    assert client.get("/notatki").get_json()["notatki"] == []


def test_brak_json(client):
    odpowiedz = client.post("/notatki", data="to nie jest JSON")
    assert odpowiedz.status_code == 400


def test_nieznany_adres(client):
    odpowiedz = client.get("/nie-ma")
    assert odpowiedz.status_code == 404
    assert "blad" in odpowiedz.get_json()

Uruchom je poleceniem pytest w katalogu projektu. Wynik powinien pokazać pięć zaliczonych testów. Ustawienie TESTING sprawia, że wyjątki w aplikacji pojawiają się w wyniku testu, zamiast ginąć w odpowiedzi 500. Poniższa tabela łączy każde żądanie z oczekiwaną odpowiedzią i testem, który ją sprawdza.

ŻądanieOczekiwana odpowiedźTest
GET /zdrowie200 i {"status": "ok"}test_zdrowie
POST /notatki z poprawnym tekstem201 i zapisana notatka z numeremtest_dodanie_notatki
POST /notatki z samymi spacjami400 i komunikat; lista bez zmiantest_pusty_tekst_jest_odrzucony
POST /notatki bez JSON400 i komunikat o formacietest_brak_json
GET nieistniejącego adresu404 w formacie JSONtest_nieznany_adres

Dobrym ćwiczeniem jest dopisanie szóstego testu samodzielnie: sprawdź, czy tekst dłuższy niż 200 znaków dostaje odpowiedź 400. Jeśli najpierw napiszesz test, a dopiero potem zmienisz limit w kodzie, zobaczysz, jak test chroni przed przypadkową zmianą zachowania.

Jakie błędy najczęściej zatrzymują pierwszą aplikację?

  • „Could not locate a Flask application” — polecenie flask run nie wie, gdzie jest aplikacja; podaj ją opcją --app app i uruchamiaj z katalogu z plikiem app.py.
  • ModuleNotFoundError: flask — wirtualne środowisko nie jest aktywne albo Flask zainstalowano w innym interpreterze.
  • 405 Method Not Allowed — adres istnieje, ale nie dla tej metody, np. formularz wysyła POST na trasę obsługującą tylko GET.
  • Błąd 400 mimo poprawnej treści — klient nie wysłał nagłówka Content-Type: application/json, więc Flask nie traktuje treści jako JSON.
  • Port zajęty — inny proces korzysta już z portu; zatrzymaj go albo uruchom serwer z opcją --port, np. flask --app app run --debug --port 5001. Na macOS port 5000 często zajmuje AirPlay Receiver — wtedy zmień port albo wyłącz tę funkcję w ustawieniach systemu.
  • Testy wpływają na siebie nawzajem — aplikacja jest tworzona raz na poziomie modułu i współdzielona; w fixture używaj fabryki create_app().

Kiedy wybrać Django lub FastAPI zamiast Flaska?

Flask daje swobodę, ale ta swoboda ma cenę: każdą większą funkcję wybierasz i konfigurujesz sam. Dopóki projekt jest mały, to zaleta. Gdy rośnie, warto zadać sobie kilka pytań.

  • Potrzebujesz bazy danych, kont użytkowników i panelu administracyjnego od pierwszego dnia? Django ma te elementy wbudowane. Przykład takiego projektu pokazujemy w tekście Django w Pythonie — pierwsza aplikacja.
  • Budujesz głównie API dla innych programów i chcesz automatycznej walidacji oraz dokumentacji na podstawie typów? Tę drogę pokazuje artykuł FastAPI od podstaw — pierwsze API.
  • Chcesz zrozumieć HTTP krok po kroku albo potrzebujesz małego serwisu z kilkoma trasami? Flask wystarczy i nie narzuca struktury.

Żaden wybór nie jest ostateczny. Pojęcia, które poznałeś tutaj — trasa, metoda HTTP, kod statusu, walidacja, klient testowy — działają tak samo w każdym z tych frameworków. Szerszy plan nauki backendu, z SQL, uprawnieniami i testami, opisuje tekst Python backend — jak zacząć.

Co dalej po pierwszej aplikacji we Flasku?

Rozwijaj projekt po jednym kroku i każdy krok zamykaj testem:

  • dodaj usuwanie notatki pod adresem z numerem, np. DELETE /notatki/1, z odpowiedzią 404 dla nieistniejącego numeru — i zamień len(notatki) + 1 na osobny licznik, bo po usunięciu notatki numery zaczęłyby się powtarzać,
  • zastąp listę w pamięci bazą SQLite i sprawdź, czy testy dalej przechodzą,
  • dodaj stronę HTML z szablonem Jinja, która wyświetla notatki,
  • przenieś ustawienia do zmiennych środowiskowych i nie zapisuj kluczy w repozytorium,
  • opisz w README, jak uruchomić projekt i testy oraz że jest to projekt edukacyjny.

Chcesz uczyć się Pythona z prowadzącym, kolejnymi projektami i informacją zwrotną do kodu? Sprawdź program kursu Python Developer i zobacz, jakie tematy obejmuje. O zasadach ewentualnego wsparcia kosztów przeczytasz w opisie dofinansowania kursów IT — to informacja o zasadach, nie obietnica przyznania środków.

Chcesz nauczyć się programowania w Pythonie?

Przejdź od teorii do praktyki pod okiem mentorów. Sprawdź kurs Python Developer w LearnIT.

Zobacz kurs Python Developer

Najczęstsze pytania

Do budowy aplikacji webowych i API: Flask przyjmuje żądania HTTP, uruchamia Twój kod w Pythonie i odsyła odpowiedź, np. stronę HTML lub dane JSON. Sprawdza się w małych serwisach, prototypach, narzędziach wewnętrznych i nauce podstaw HTTP.

Po stronie serwera. Kod Flask wykonuje się na serwerze i zwraca odpowiedź przeglądarce lub innemu programowi. To, co dzieje się w przeglądarce, np. obsługa kliknięć, należy do frontendu.

Tak. Projekt jest rozwijany, ma aktualną dokumentację i występuje w ogłoszeniach obok Django i FastAPI. Aktualną wersję i wymagania sprawdzaj w oficjalnej dokumentacji, bo starsze tutoriale bywają nieaktualne.

W aktywnym wirtualnym środowisku zainstaluj Flask, zapisz aplikację w pliku app.py i uruchom polecenie flask --app app run --debug. Serwer domyślnie nasłuchuje tylko na adresie 127.0.0.1, więc aplikacja jest dostępna wyłącznie z Twojego komputera.

Użyj wbudowanego klienta testowego razem z pytest. Fixture tworzy aplikację przez create_app(), a testy wysyłają żądania GET i POST bez uruchamiania serwera i sprawdzają kod statusu oraz treść odpowiedzi.

Flask, jeśli chcesz zrozumieć HTTP krok po kroku i zbudować mały serwis. Django, jeśli od początku potrzebujesz bazy danych, kont użytkowników i panelu administracyjnego. Porównanie trzech frameworków znajdziesz w tekście Django, Flask czy FastAPI.

Nie. Służy do pracy lokalnej, a tryb debugowania udostępnia interaktywny debugger, który pozwala wykonywać kod na serwerze. Nie łącz go z udostępnieniem aplikacji w sieci.

Uzyskaj bezpłatną konsultację

Wypełnij formularz i otrzymaj kilka rozdziałów naszego podręcznika w prezencie!

Phone
form