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

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
- 01Jaki efekt powinna dać pierwsza aplikacja w Django?
- 02Jak przygotować środowisko i uruchomić projekt?
- 03Jak łączą się URL, widok, szablon i model?
- 04Jak dodać i sprawdzić pierwszy rekord?
- 05Jak przetestować aplikację i wyłapać typowe błędy?
- 06Czym projekt edukacyjny różni się od aplikacji produkcyjnej?
- 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.
- Utwórz katalog projektu, wirtualne środowisko i zainstaluj Django.
- Utwórz projekt config i aplikację lektury, a następnie dopisz aplikację do INSTALLED_APPS.
- Zdefiniuj model Lektura, wygeneruj migrację i zastosuj ją w bazie.
- Dodaj formularz, widok i adres URL listy lektur.
- Utwórz szablon HTML z formularzem i listą.
- Uruchom serwer deweloperski i dodaj pierwszą lekturę w przeglądarce.
- Zarejestruj model w panelu administracyjnym i utwórz konto administratora.
- Napisz trzy testy i uruchom je poleceniem manage.py test.
Krok pierwszy i drugi w terminalu:
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 lekturyNa 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:
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:
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.tytulModel to klasa Pythona, z której Django tworzy tabelę w bazie. Żeby tabela powstała, wygeneruj i zastosuj migrację:
python manage.py makemigrations lektury
python manage.py migratePierwsza 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:
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):
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:
# 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.
<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ą.
| Plik | Rola | Jak sprawdzić |
|---|---|---|
config/settings.py | konfiguracja projektu, lista aplikacji, baza danych | python manage.py check kończy się bez błędów |
config/urls.py | główna mapa adresów projektu | strona główna nie zwraca błędu 404 |
lektury/models.py | struktura danych, z której powstaje tabela | makemigrations tworzy plik migracji |
lektury/migrations/ | historia zmian schematu bazy | migrate kończy się bez błędów |
lektury/forms.py | pola formularza i ich walidacja | pusty tytuł daje komunikat błędu |
lektury/views.py | obsługa żądań GET i POST | po dodaniu lektury następuje przekierowanie na listę |
lektury/urls.py | adresy aplikacji i ich nazwy | widok jest dostępny pod nazwą lista |
lektury/templates/lektury/lista.html | HTML widoczny dla użytkownika | strona pokazuje formularz i listę |
lektury/admin.py | rejestracja modelu w panelu administracyjnym | lektury są widoczne pod adresem /admin/ |
lektury/tests.py | testy automatyczne | python 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 programJak 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:
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:
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 wredirectlubreverseróżni się od nazwy nadanej wurls.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.
| Obszar | Projekt edukacyjny | Aplikacja produkcyjna |
|---|---|---|
| Tryb debugowania | włączony, żeby widzieć szczegóły błędów | wyłączony; błędy trafiają do logów |
Klucz SECRET_KEY | wygenerowany w settings.py | czytany ze zmiennej środowiskowej, poza repozytorium |
| Baza danych | SQLite w jednym pliku | zwykle osobny serwer bazy, np. PostgreSQL, z kopiami zapasowymi |
| Serwer | runserver | serwer aplikacyjny za serwerem WWW, z HTTPS |
| Dozwolone domeny | tylko adres lokalny | jawnie ustawione ALLOWED_HOSTS |
| Użytkownicy | jedno konto administratora | logowanie, 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


