Python

Django w Pythonie — pierwsza aplikacja z bazą, formularzem i testami

Pierwsza aplikacja w Django krok po kroku: środowisko, model i migracja, formularz, widok, szablon, panel admina i trzy testy. Plus różnice z produkcją.

Zespół LearnIT

9 minutZaktualizowano:
Django w Pythonie — pierwsza aplikacja z bazą, formularzem i testami

Krótka odpowiedź

Django to framework Pythona do pełnych aplikacji webowych z wbudowanym ORM, szablonami, formularzami, panelem administracyjnym i narzędziami do testów. Pierwszą aplikację zbudujesz lokalnie w ośmiu krokach: wirtualne środowisko, projekt i aplikacja, model z migracją, formularz z widokiem i adresem, szablon, uruchomienie serwera, panel admina oraz trzy testy uruchamiane poleceniem manage.py test.

Spis treści · 7
  1. 01Jaki efekt powinna dać pierwsza aplikacja w Django?
  2. 02Jak przygotować środowisko i uruchomić projekt?
  3. 03Jak łączą się URL, widok, szablon i model?
  4. 04Jak dodać i sprawdzić pierwszy rekord?
  5. 05Jak przetestować aplikację i wyłapać typowe błędy?
  6. 06Czym projekt edukacyjny różni się od aplikacji produkcyjnej?
  7. 07Co dalej po pierwszej aplikacji?

Django to framework Pythona do budowy pełnych aplikacji webowych: ma wbudowany ORM do pracy z bazą danych, szablony HTML, formularze z walidacją, panel administracyjny i narzędzia do testów. Pierwszą aplikację zbudujesz lokalnie w kilku krokach: wirtualne środowisko, projekt i aplikacja, model z migracją, formularz z widokiem, szablon i trzy testy. Efektem jest działająca w przeglądarce lista lektur.

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

Jaki efekt powinna dać pierwsza aplikacja w Django?

Zanim zaczniesz, ustal, po czym poznasz, że skończyłeś. Bez tego łatwo utknąć w ciągłym „dokładaniu jeszcze jednej rzeczy”. Nasza aplikacja to prosta lista lektur do przeczytania. Projekt jest gotowy, gdy spełnia pięć warunków:

  • pod lokalnym adresem widać formularz i listę dodanych tytułów,
  • dodanie tytułu zapisuje rekord w bazie i przekierowuje z powrotem na listę,
  • pusty tytuł zostaje odrzucony z komunikatem błędu,
  • rekordy widać i można edytować w panelu administracyjnym,
  • polecenie uruchamiające testy kończy się wynikiem OK.

Czym to się różni od demonstracji API? API zwraca dane, zwykle w formacie JSON, innemu programowi — aplikacji mobilnej czy frontendowi. Taki przykład pokazujemy w tekście FastAPI od podstaw. Tutaj Django samo generuje stronę HTML po stronie serwera, obsługuje formularz i zapisuje dane w bazie, a użytkownik korzysta z aplikacji bezpośrednio w przeglądarce.

Celowo przechowujemy wyłącznie tytuły książek. Do nauki nie potrzebujesz imion, adresów e-mail ani innych danych osobowych, a ich przetwarzanie wymaga osobnych zabezpieczeń i podstawy prawnej.

Jak przygotować środowisko i uruchomić projekt?

Cała ścieżka składa się z ośmiu kroków. Komendy poniżej dotyczą systemów Linux i macOS; na Windowsie inaczej wygląda tylko aktywacja środowiska, którą znajdziesz w dokumentacji Pythona. Aktualne wymagania dotyczące wersji Pythona sprawdź w oficjalnej dokumentacji Django.

  1. Utwórz katalog projektu, wirtualne środowisko i zainstaluj Django.
  2. Utwórz projekt config i aplikację lektury, a następnie dopisz aplikację do INSTALLED_APPS.
  3. Zdefiniuj model Lektura, wygeneruj migrację i zastosuj ją w bazie.
  4. Dodaj formularz, widok i adres URL listy lektur.
  5. Utwórz szablon HTML z formularzem i listą.
  6. Uruchom serwer deweloperski i dodaj pierwszą lekturę w przeglądarce.
  7. Zarejestruj model w panelu administracyjnym i utwórz konto administratora.
  8. Napisz trzy testy i uruchom je poleceniem manage.py test.

Krok pierwszy i drugi w terminalu:

Terminal
mkdir lektury-django && cd lektury-django
python3 -m venv .venv
source .venv/bin/activate
pip install django
pip freeze > requirements.txt

django-admin startproject config .
python manage.py startapp lektury

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.

Kropka na końcu startproject sprawia, że plik manage.py trafia do bieżącego katalogu, a ustawienia — do podkatalogu config. Druga komenda tworzy aplikację lektury, czyli moduł z modelami, widokami i testami. Jeden projekt Django może mieć wiele takich aplikacji.

Django musi wiedzieć o nowej aplikacji. Otwórz config/settings.py i dopisz ją na końcu listy INSTALLED_APPS:

Python
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "lektury",
]

Jeśli teraz uruchomisz python manage.py runserver i otworzysz adres pokazany w terminalu, zobaczysz stronę powitalną Django. To znak, że środowisko działa. Domyślnie projekt korzysta z bazy SQLite zapisanej w jednym pliku, więc do nauki nie musisz instalować osobnego serwera bazy danych.

Jak łączą się URL, widok, szablon i model?

Każde żądanie z przeglądarki przechodzi w Django tę samą drogę. Najpierw plik z adresami decyduje, która funkcja ma je obsłużyć. Ta funkcja, czyli widok, w razie potrzeby pobiera lub zapisuje dane przez model, a na końcu przekazuje je do szablonu, który buduje stronę HTML. Zacznijmy od modelu w lektury/models.py:

Python
from django.db import models


class Lektura(models.Model):
    tytul = models.CharField(max_length=200)
    przeczytana = models.BooleanField(default=False)
    dodano = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.tytul

Model to klasa Pythona, z której Django tworzy tabelę w bazie. Żeby tabela powstała, wygeneruj i zastosuj migrację:

Terminal
python manage.py makemigrations lektury
python manage.py migrate

Pierwsza komenda zapisuje opis zmian w katalogu lektury/migrations, druga wykonuje go w bazie. Przy okazji powstają też tabele wbudowanych aplikacji, na przykład użytkowników i sesji. Teraz formularz w nowym pliku lektury/forms.py. ModelForm buduje pola na podstawie modelu, więc walidacja długości i wymagalności tytułu działa bez dodatkowego kodu:

Python
from django import forms

from .models import Lektura


class LekturaForm(forms.ModelForm):
    class Meta:
        model = Lektura
        fields = ["tytul", "przeczytana"]

Widok w lektury/views.py obsługuje dwa przypadki: zwykłe wyświetlenie strony (GET) i wysłanie formularza (POST):

Python
from django.shortcuts import redirect, render

from .forms import LekturaForm
from .models import Lektura


def lista(request):
    if request.method == "POST":
        form = LekturaForm(request.POST)
        if form.is_valid():
            form.save()
            return redirect("lista")
    else:
        form = LekturaForm()
    lektury = Lektura.objects.order_by("-dodano")
    return render(request, "lektury/lista.html", {"form": form, "lektury": lektury})

Po poprawnym zapisie widok przekierowuje na tę samą stronę. Dzięki temu odświeżenie przeglądarki nie wyśle formularza drugi raz i nie powstanie duplikat. Jeśli formularz jest błędny, widok nie przekierowuje, tylko ponownie wyświetla stronę razem z komunikatem błędu.

Adresy: w nowym pliku lektury/urls.py nadajemy widokowi nazwę, a w config/urls.py dołączamy adresy aplikacji do projektu:

Python
# lektury/urls.py
from django.urls import path

from . import views

urlpatterns = [
    path("", views.lista, name="lista"),
]


# config/urls.py
from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("admin/", admin.site.urls),
    path("", include("lektury.urls")),
]

Na koniec szablon. Django szuka go w katalogu templates wewnątrz aplikacji, dlatego plik zapisz jako lektury/templates/lektury/lista.html. Powtórzona nazwa aplikacji w ścieżce nie jest pomyłką — chroni przed konfliktem, gdy dwie aplikacje mają szablon o tej samej nazwie.

HTML
<h1>Lista lektur</h1>
<form method="post">
  {% csrf_token %}
  {{ form.as_p }}
  <button type="submit">Dodaj</button>
</form>
<ul>
  {% for lektura in lektury %}
    <li>{{ lektura.tytul }}{% if lektura.przeczytana %} (przeczytana){% endif %}</li>
  {% empty %}
    <li>Lista jest pusta.</li>
  {% endfor %}
</ul>

Znacznik {% csrf_token %} dodaje do formularza ukryty token, który chroni przed wysłaniem formularza z obcej strony. Bez niego Django odrzuci każde żądanie POST. Poniższa tabela zbiera wszystkie pliki projektu, ich rolę i najprostszy sposób, by sprawdzić, że działają.

PlikRolaJak sprawdzić
config/settings.pykonfiguracja projektu, lista aplikacji, baza danychpython manage.py check kończy się bez błędów
config/urls.pygłówna mapa adresów projektustrona główna nie zwraca błędu 404
lektury/models.pystruktura danych, z której powstaje tabelamakemigrations tworzy plik migracji
lektury/migrations/historia zmian schematu bazymigrate kończy się bez błędów
lektury/forms.pypola formularza i ich walidacjapusty tytuł daje komunikat błędu
lektury/views.pyobsługa żądań GET i POSTpo dodaniu lektury następuje przekierowanie na listę
lektury/urls.pyadresy aplikacji i ich nazwywidok jest dostępny pod nazwą lista
lektury/templates/lektury/lista.htmlHTML widoczny dla użytkownikastrona pokazuje formularz i listę
lektury/admin.pyrejestracja modelu w panelu administracyjnymlektury są widoczne pod adresem /admin/
lektury/tests.pytesty automatycznepython manage.py test zwraca OK

Wolisz uczyć się w ustalonej kolejności?

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

Zobacz program

Jak dodać i sprawdzić pierwszy rekord?

Uruchom serwer poleceniem python manage.py runserver, otwórz stronę główną i dodaj jeden tytuł. Po kliknięciu przycisku strona powinna się przeładować, a tytuł pojawić na liście. Spróbuj też wysłać pusty formularz — przeglądarka sama go zatrzyma, bo pole ma atrybut required. Walidację po stronie Django zobaczysz, gdy w polu tytułu wpiszesz same spacje: Django usunie je, uzna pole za puste i zamiast zapisu pokaże komunikat, że pole jest wymagane.

Wynik warto sprawdzić niezależnie od samej strony. Najwygodniejszy jest panel administracyjny. Zarejestruj model w lektury/admin.py:

Python
from django.contrib import admin

from .models import Lektura

admin.site.register(Lektura)

Następnie utwórz konto administratora poleceniem python manage.py createsuperuser i zaloguj się pod adresem /admin/. Zobaczysz tam wszystkie lektury i możesz je edytować lub usuwać. Drugi sposób to powłoka Django: po wpisaniu python manage.py shell polecenie Lektura.objects.count() (po zaimportowaniu modelu) pokaże, ile rekordów jest w bazie. Obie metody pomagają odróżnić błąd w szablonie od błędu zapisu.

Jak przetestować aplikację i wyłapać typowe błędy?

Ręczne klikanie wystarczy na początku, ale szybko staje się powtarzalne. Django ma wbudowany klient testowy, który wysyła żądania do aplikacji bez uruchamiania serwera. Testy działają na osobnej, tymczasowej bazie testowej, a zmiany wprowadzone przez każdy test są po nim wycofywane, więc nie dotykają Twoich danych. Zastąp zawartość lektury/tests.py:

Python
from django.test import TestCase
from django.urls import reverse

from .models import Lektura


class ListaLekturTests(TestCase):
    def test_strona_sie_otwiera(self):
        odpowiedz = self.client.get(reverse("lista"))
        self.assertEqual(odpowiedz.status_code, 200)

    def test_dodanie_lektury(self):
        odpowiedz = self.client.post(reverse("lista"), {"tytul": "Lalka"})
        self.assertRedirects(odpowiedz, reverse("lista"))
        self.assertEqual(Lektura.objects.count(), 1)

    def test_pusty_tytul_jest_odrzucony(self):
        odpowiedz = self.client.post(reverse("lista"), {"tytul": ""})
        self.assertEqual(odpowiedz.status_code, 200)
        self.assertEqual(Lektura.objects.count(), 0)

Uruchom je poleceniem python manage.py test. Jeśli wszystko działa, na końcu zobaczysz informację o trzech wykonanych testach i wynik OK. Trzy testy sprawdzają dokładnie te warunki, które zapisaliśmy na początku jako definicję „gotowe”: strona się otwiera, poprawne dane trafiają do bazy, błędne — nie.

Najczęstsze błędy początkujących i ich przyczyny:

  • „Model class … isn't in an application in INSTALLED_APPS” — aplikacja nie została dopisana do listy w settings.py.
  • „no such table” — model jest zdefiniowany, ale migracja nie została wygenerowana lub zastosowana.
  • TemplateDoesNotExist — szablon leży w złym katalogu; sprawdź ścieżkę templates/lektury/.
  • Błąd 403 przy wysyłaniu formularza — w szablonie brakuje {% csrf_token %}.
  • NoReverseMatch — nazwa w redirect lub reverse różni się od nazwy nadanej w urls.py.

Przed każdym commitem uruchom też python manage.py check. Polecenie sprawdza konfigurację projektu i wyłapuje część problemów, zanim pojawią się w przeglądarce.

Czym projekt edukacyjny różni się od aplikacji produkcyjnej?

Działająca lokalnie lista lektur to dobry projekt do nauki, ale nie jest gotowa do publikacji w internecie. Django samo to pokazuje: polecenie python manage.py check --deploy zwraca listę ostrzeżeń, między innymi o włączonym trybie debugowania i kluczu zapisanym w kodzie. Serwer uruchamiany przez runserver jest przeznaczony wyłącznie do pracy lokalnej.

ObszarProjekt edukacyjnyAplikacja produkcyjna
Tryb debugowaniawłączony, żeby widzieć szczegóły błędówwyłączony; błędy trafiają do logów
Klucz SECRET_KEYwygenerowany w settings.pyczytany ze zmiennej środowiskowej, poza repozytorium
Baza danychSQLite w jednym plikuzwykle osobny serwer bazy, np. PostgreSQL, z kopiami zapasowymi
Serwerrunserverserwer aplikacyjny za serwerem WWW, z HTTPS
Dozwolone domenytylko adres lokalnyjawnie ustawione ALLOWED_HOSTS
Użytkownicyjedno konto administratoralogowanie, uprawnienia i ochrona danych osobowych

Nie musisz od razu przechodzić całej prawej kolumny. Ważne, żeby w README uczciwie napisać, że projekt jest edukacyjny, i nie umieszczać w repozytorium haseł ani kluczy. Dobrym zwyczajem jest dodanie pliku .gitignore, który wyklucza katalog .venv i plik bazy SQLite.

Co dalej po pierwszej aplikacji?

Gdy lista lektur działa i ma testy, rozwijaj ją po jednym kroku, a każdy krok opisz w README:

  • dodaj edycję i usuwanie, żeby mieć pełny zestaw operacji CRUD,
  • wprowadź logowanie, aby każdy użytkownik widział tylko własne lektury,
  • przenieś bazę na PostgreSQL i sprawdź, czy migracje nadal działają,
  • dopisz testy dla każdej nowej funkcji, zanim uznasz ją za skończoną,
  • przygotuj konfigurację opartą na zmiennych środowiskowych i dopiero wtedy myśl o wdrożeniu.

Szerszy plan nauki backendu — HTTP, SQL, uprawnienia i testy — opisuje tekst Python backend — jak zacząć. Jeśli chcesz zobaczyć, jak ta sama wiedza przekłada się na API zwracające JSON, przejdź do artykułu FastAPI od podstaw. Pomysły na kolejne projekty znajdziesz w zestawieniu projekty Python do portfolio.

Chcesz budować aplikacje w Django z prowadzącym i informacją zwrotną do kodu? Sprawdź program kursu Python Developer — w module „Frameworki Flask i Django” pojawiają się szablony, routing, ORM, migracje i autoryzacja. 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 z bazą danych, formularzami, kontami użytkowników i panelem administracyjnym, na przykład serwisów, systemów wewnętrznych i paneli zarządzania treścią. Django generuje strony HTML po stronie serwera, ale można w nim też budować API.

W aktywnym wirtualnym środowisku zainstaluj Django, utwórz projekt poleceniem django-admin startproject config . (kropka na końcu tworzy go w bieżącym katalogu), zastosuj migracje poleceniem python manage.py migrate i uruchom serwer deweloperski poleceniem python manage.py runserver. Adres strony pokaże terminal.

Jeśli znasz podstawy Pythona, pierwszą działającą aplikację zbudujesz stosunkowo szybko, bo wiele elementów jest gotowych. Więcej czasu zajmuje zrozumienie, jak współpracują URL, widok, model i szablon, dlatego warto zacząć od jednego małego projektu.

Aplikacja w FastAPI zwykle zwraca dane w formacie JSON innym programom. Typowy projekt w Django generuje strony HTML, obsługuje formularze i bazę danych oraz ma panel administracyjny. Pierwsze API pokazujemy w tekście FastAPI od podstaw.

Migracje zapisują zmiany w modelach jako pliki, które Django wykonuje w bazie danych. Polecenie makemigrations tworzy opis zmiany, a migrate stosuje go w bazie. Dzięki temu schemat bazy jest wersjonowany razem z kodem.

Napisz klasy dziedziczące po TestCase w pliku tests.py i uruchom je poleceniem python manage.py test. Klient testowy wysyła żądania bez uruchamiania serwera, a testy działają na osobnej, tymczasowej bazie testowej, w której zmiany każdego testu są wycofywane.

Nie. Serwer runserver jest przeznaczony do pracy lokalnej. Przed publikacją trzeba m.in. wyłączyć tryb debugowania, przenieść klucz do zmiennej środowiskowej, ustawić ALLOWED_HOSTS i HTTPS. Listę ostrzeżeń pokaże polecenie python manage.py check --deploy.

Uzyskaj bezpłatną konsultację

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

Phone
form