08 wrz 2025·7 min
Czym jest FastAPI? Praktyczny przewodnik po tworzeniu API
FastAPI to nowoczesny framework Pythona do szybkiego tworzenia API, z obsługą typów, walidacją i automatyczną dokumentacją OpenAPI. Poznaj podstawy i zastosowania.
FastAPI to nowoczesny framework Pythona do szybkiego tworzenia API, z obsługą typów, walidacją i automatyczną dokumentacją OpenAPI. Poznaj podstawy i zastosowania.
FastAPI to framework Pythona do szybkiego budowania webowych API — z czytelnym kodem i automatyczną dokumentacją. Piszesz małe funkcje (zwane „endpointami”), które deklarują, jakie dane API przyjmuje i co zwraca, a FastAPI zajmuje się resztą — routingiem, walidacją i generowaniem odpowiedzi JSON.
API to zestaw URL-i, które pozwalają jednemu oprogramowaniu rozmawiać z drugim.
Na przykład aplikacja pogodowa na telefonie może wywołać GET /weather?city=Berlin. Serwer odpowiada ustrukturyzowanymi danymi (zwykle JSON), takimi jak temperatura i prognoza. Aplikacja nie potrzebuje bezpośredniego dostępu do bazy danych — pyta API i wyświetla wynik.
FastAPI pomaga ci tworzyć te URL-e i odpowiedzi w Pythonie.
Nie musisz być ekspertem od async, by zacząć; możesz pisać proste endpointy i stopniowo wprowadzać bardziej zaawansowane wzorce.
FastAPI szybko zyskało popularność, ponieważ usuwa wiele codziennych przeszkód, na które trafiają programiści tworzący API w Pythonie.
Tradycyjne projekty API często zaczynają się od powolnej konfiguracji i dużej ilości „instalacji”:
Główne cechy FastAPI celują w te problemy, dzięki czemu zespoły poświęcają więcej czasu na projektowanie endpointów, a mniej na walkę z boilerplate frameworku.
FastAPI mocno opiera się na wskazówkach typów w Pythonie. Gdy deklarujesz, że pole to int, opcjonalne lub lista czegoś, FastAPI używa tej informacji do walidacji wejścia i kształtowania wyjścia.
To redukuje błędy wynikające z „stringly-typed” podejścia (np. traktowanie ID jako tekstu w jednym miejscu, a liczby w innym) i zachęca do spójnego zachowania endpointów. To nadal Python, ale z jasnymi oczekiwaniami w sygnaturach funkcji.
Ponieważ schemat API jest wyprowadzany z kodu, FastAPI może automatycznie generować interaktywną dokumentację (OpenAPI + Swagger UI/ReDoc). To ma znaczenie przy współpracy: frontendowcy, QA i integratorzy mogą eksplorować endpointy, testować żądania i widzieć dokładne modele bez czekania na osobną dokumentację.
FastAPI nie naprawi źle zaprojektowanego API. Nadal potrzebujesz dobrego nazewnictwa, wersjonowania, obsługi błędów i decyzji dotyczących bezpieczeństwa. To, co oferuje, to czystsza ścieżka od „pomysłu” do „dobrze zdefiniowanego API” z mniejszą liczbą niespodzianek.
FastAPI wydaje się proste, gdy zrozumiesz kilka podstawowych idei, na których się opiera. Nie musisz pamiętać szczegółów wewnętrznych — wystarczy rozpoznać elementy, których będziesz używać na co dzień.
Framework to zestaw narzędzi i konwencji do budowania API bez zaczynania od zera. FastAPI dostarcza „instalacji” do typowych zadań API: definiowania endpointów, odczytu wejścia, zwracania wyjścia, obsługi błędów i organizacji kodu w czytelną strukturę.
Routing to sposób mapowania URL-a i metody HTTP na kawałek kodu Pythona.
Na przykład możesz zmapować GET /users na „lista użytkowników” i POST /users na „utwórz użytkownika”. W FastAPI zwykle definiujesz trasy za pomocą dekoratorów takich jak @app.get(...) i @app.post(...), co ułatwia szybkie zorientowanie się, co oferuje twoje API.
Każde wywołanie API to request (co klient wysyła) i response (co serwer zwraca).
FastAPI pomaga ci:
/users/{id}), query stringa (?page=2), nagłówków i ciała żądania200, 201, 404)FastAPI działa na ASGI, nowoczesnym standardzie dla serwerów webowych w Pythonie. W praktyce oznacza to, że FastAPI jest zaprojektowane do efektywnego obsługiwania wielu połączeń i może wspierać funkcje takie jak połączenia długotrwałe (np. WebSockets), gdy tego potrzebujesz — bez konieczności zarządzania niskopoziomową siecią.
Wskazówki typów Pythona (np. str, int, list[Item]) w FastAPI to nie tylko dokumentacja — są kluczowym wejściem. FastAPI używa ich, by zrozumieć, jakich danych oczekujesz, konwertować przychodzące wartości do odpowiednich typów i generować bardziej przewidywalne API.
Modele Pydantic pozwalają zdefiniować kształt danych (pola, typy, wartości opcjonalne) w jednym miejscu. FastAPI używa tych modeli do walidacji przychodzącego JSON-a, odrzucania nieprawidłowych danych z czytelnymi komunikatami o błędach oraz do serializacji wyjścia — dzięki temu API zachowuje spójność nawet gdy klienci wysyłają nieporządne dane.
Aplikacje FastAPI budują się wokół endpointów: ścieżka URL + metoda HTTP. Traktuj endpoint jako „o co klient pyta” i „jak pyta”. Na przykład klient może GET /users, by pobrać listę użytkowników, lub POST /users, by utworzyć użytkownika.
Ścieżka to trasa, a metoda to działanie:
GET /products → pobierz danePOST /products → wyślij dane, aby coś utworzyćPUT /products/123 → zastąp/aktualizuj cośDELETE /products/123 → usuń cośFastAPI rozdziela dane będące częścią ścieżki od danych będących opcjonalnymi „filtrami” zapytania.
GET /users/42 → 42 to ID użytkownika.? i zwykle opcjonalny.
GET /users?limit=10&active=true → limit i active kontrolują sposób zwracania wyników.Gdy klient wysyła ustrukturyzowane dane (zwykle JSON), trafiają one do ciała żądania, najczęściej przy POST lub PUT.
Przykład: POST /orders z JSON-em { "item_id": 3, "quantity": 2 }.
FastAPI może zwracać zwykłe obiekty Pythona (np. dict), ale najbardziej błyszczy, gdy definiujesz model odpowiedzi. Model działa jak kontrakt: pola są spójne, dodatkowe dane można odfiltrować, a typy są egzekwowane. Efekt to czyściejsze API — klienci wiedzą, czego oczekiwać, a ty unikasz niespodziewanych odpowiedzi łamiących integracje.
„Async” (asynchroniczne) to sposób, w jaki twoje API może efektywnie obsługiwać wiele żądań, gdy dużo czasu spędza na oczekiwaniu.
Wyobraź sobie baristę przyjmującego zamówienia. Jeśli musiałby stać i nic nie robić, gdy ekspres robi kawę, obsłużyłby mniej klientów. Lepsze podejście: uruchomić ekspres, a w tym czasie przyjąć następne zamówienie.
Async działa podobnie. Twoja aplikacja FastAPI może rozpocząć operację, która czeka na coś wolnego — na przykład na zapytanie sieciowe lub do bazy danych — i w tym czasie obsługiwać inne nadchodzące żądania.
Async przydaje się, gdy API wykonuje dużo operacji I/O (wejście/wyjście) — rzeczy, które spędzają czas na oczekiwaniu, a nie na przetwarzaniu. Typowe przykłady:
Jeśli endpointy często czekają na takie operacje, async może zwiększyć przepustowość i zmniejszyć ryzyko, że żądania zaczną się piętrzyć pod obciążeniem.
Async nie jest magicznym przyciskiem przyspieszającym wszystko. Jeśli endpoint jest głównie obciążony CPU — np. zmiana rozmiaru dużych obrazów, skomplikowane obliczenia data-science czy szyfrowanie dużych ładunków — async nie przyspieszy samego obliczenia. W takich przypadkach zwykle potrzebujesz innych rozwiązań (pracowników w tle, puli procesów lub skalowania poziomego).
Nie musisz przepisywać wszystkiego, by używać FastAPI. Możesz pisać zwykłe (synchronizacyjne) funkcje tras i FastAPI uruchomi je bez problemu. Wiele projektów miesza oba style: proste endpointy pozostają synchroniczne, a async def stosuje się tam, gdzie ma to sens (zwykle wokół zapytań do bazy lub zewnętrznych żądań HTTP).
Walidacja to punkt kontrolny między światem zewnętrznym a twoim kodem. Gdy API przyjmuje dane (ciało JSON, parametry query, parametry ścieżki), chcesz mieć pewność, że są kompletne, poprawnie typowane i mieszczą się w rozsądnych granicach — zanim zapiszesz je w bazie danych, wywołasz inną usługę lub uruchomisz logikę biznesową.
FastAPI opiera się na Pydantic. Opisujesz, jak wyglądają „dobre dane” raz, a FastAPI automatycznie:
Jeśli klient prześle dane w złym kształcie, FastAPI odpowie 422 Unprocessable Entity i zwróci ustrukturyzowany payload błędu wskazujący dokładne pole i powód. To ułatwia deweloperom po stronie klienta szybkie poprawienie żądań bez zgadywania.
Oto mały model pokazujący pola wymagane, typy, ograniczenia min/max i formaty:
from pydantic import BaseModel, EmailStr, Field
class UserCreate(BaseModel):
email: EmailStr
age: int = Field(ge=13, le=120)
username: str = Field(min_length=3, max_length=20)
email musi być obecny.age musi być liczbą całkowitą.age ograniczone do 13–120.EmailStr wymusza poprawny kształt adresu e-mail.Te same modele mogą kształtować wyjście, dzięki czemu odpowiedzi API nie przypadkowo nie ujawniają pól wewnętrznych. Zwracasz obiekty Pythona; FastAPI (przez Pydantic) przekształca je do JSON-a z odpowiednimi nazwami pól i typami.
Jedną z praktycznych cech FastAPI jest to, że generuje dokumentację API automatycznie — na podstawie kodu, który już napisałeś.
OpenAPI to standardowy sposób opisywania API w ustrukturyzowanym formacie (zwykle JSON). Traktuj to jako „kontrakt”, który określa:
GET /users/{id})Ponieważ jest maszynowo czytelny, narzędzia mogą go używać do generowania klientów, testowania i utrzymywania zgodności w zespole.
FastAPI serwuje automatycznie dwie przyjazne strony dokumentacji:
W typowym projekcie FastAPI znajdziesz je pod:
/docs (Swagger UI)/redoc (ReDoc)Gdy zmieniasz parametry ścieżek, modele żądań/odpowiedzi lub reguły walidacji, schemat OpenAPI (i strony dokumentacji) aktualizują się automatycznie. Nie ma oddzielnego kroku „utrzymania dokumentacji”.
Aplikacja FastAPI może być mała i wciąż wyglądać „poważnie”. Tworzysz obiekt Pythona app, dodajesz kilka tras i uruchamiasz lokalny serwer, aby przetestować w przeglądarce.
Najmniejszy użyteczny przykład:
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"message": "Hello, FastAPI"}
To wszystko: jedna trasa (GET /), która zwraca JSON.
Aby poczuć API, przechowajmy elementy w liście. To nie jest baza danych — dane resetują się po restarcie serwera — ale idealne do nauki.
from fastapi import FastAPI
app = FastAPI()
items = []
@app.post("/items")
def create_item(name: str):
item = {"id": len(items) + 1, "name": name}
items.append(item)
return item
@app.get("/items")
def list_items():
return items
Możesz teraz:
POST /items?name=Coffee, by dodać elementGET /items, by pobrać listęCzęsty starter to:
main.py (tworzy app i trasy)requirements.txt lub pyproject.toml (zależności)Zwykle:
uvicorn main:app --reload)http://127.0.0.1:8000 i wypróbuj endpointy„Dependencies” w FastAPI to współdzielone wejścia, których endpointy potrzebują — np. sesja bazy danych, bieżący zalogowany użytkownik, ustawienia aplikacji lub wspólne parametry query. Zamiast ręcznie tworzyć/parsować je w każdej trasie, definiujesz je raz, a FastAPI dostarcza je tam, gdzie są potrzebne.
Zależność to zwykle funkcja (lub klasa), która zwraca wartość, której użyje endpoint. FastAPI wywoła ją za ciebie, ustali, czego potrzebuje (na podstawie parametrów) i wstrzyknie wynik do funkcji operacji ścieżki.
Często nazywa się to dependency injection, ale możesz myśleć: „zadeklaruj, czego potrzebujesz, a FastAPI to połączy”.
Bez zależności mogłoby się zdarzyć, że:
Z zależnościami centralizujesz tę logikę. Jeśli później zmienisz sposób tworzenia sesji DB lub ładowania bieżącego użytkownika, aktualizujesz jedno miejsce — nie kilkadziesiąt endpointów.
page/limit.Wzorzec, który zobaczysz w wielu aplikacjach FastAPI:
from fastapi import Depends, FastAPI
app = FastAPI()
def get_settings():
return {"items_per_page": 20}
@app.get("/items")
def list_items(settings=Depends(get_settings)):
return {"limit": settings["items_per_page"]}
Deklarujesz zależność przez Depends(...), a FastAPI przekazuje jej wynik do parametru endpointu. Ten sam sposób działa dla bardziej złożonych elementów (np. get_db() lub get_current_user()), pomagając utrzymać porządek w miarę rozwoju API.
FastAPI nie „zabezpieczy” automatycznie twojego API — wybierasz schemat i włączasz go w endpointy. Dobra wiadomość jest taka, że FastAPI dostarcza narzędzi (szczególnie przez system zależności), które upraszczają wdrażanie typowych wzorców bezpieczeństwa.
Uwierzytelnianie odpowiada: „Kto to jest?” Autoryzacja odpowiada: „Co może zrobić?”
Przykład: użytkownik może być uwierzytelniony (ważne logowanie/token), ale nadal nie mieć uprawnień do trasy dostępnej tylko dla administratorów.
X-API-Key). Pamiętaj o rotacji i odwoływaniu kluczy.FastAPI wspiera te wzorce przez narzędzia typu fastapi.security i dokumentuje je w OpenAPI.
Jeśli przechowujesz hasła użytkowników, nigdy nie zapisuj ich w postaci jawnej. Przechowuj solony, wolny hash (np. bcrypt/argon2 przez zaufaną bibliotekę). Rozważ też ograniczenia prób logowania i blokadę konta.
Bezpieczeństwo to szczegóły: przechowywanie tokenów, ustawienia CORS, HTTPS, zarządzanie sekretami i poprawne sprawdzenia autoryzacji na każdym wrażliwym endpointzie. Traktuj wbudowane pomocniki jako punkt startowy i weryfikuj podejście przez przeglądy i testy przed użyciem w produkcji.
Testowanie to moment, w którym obietnica „działa na mojej maszynie” zamienia się w pewność, że można wdrożyć. Dobra wiadomość: FastAPI jest zbudowane na Starlette, więc dostajesz solidne narzędzia testowe bez dużej konfiguracji.
Testy jednostkowe skupiają się na małych kawałkach: funkcjach, zależnościach ładujących użytkownika, metodach serwisów (zwykle z mockami).
Testy integracyjne uruchamiają API end-to-end: wywołujesz endpoint i sprawdzasz pełną odpowiedź HTTP. To testy, które wykryją błędy routingu, problemy z zależnościami i walidacją.
Zdrowy zestaw testów ma zwykle więcej testów jednostkowych (szybkich) i mniej integracyjnych (wyższe zaufanie).
Aplikacje FastAPI można testować „jak klienta” używając TestClient ze Starlette — wysyła żądania do aplikacji w procesie, bez zewnętrznego serwera.
from fastapi.testclient import TestClient
from app.main import app
client = TestClient(app)
def test_healthcheck():
r = client.get("/health")
assert r.status_code == 200
Testuj rzeczy, na których polegają użytkownicy i inne systemy:
Używaj przewidywalnych danych, izoluj zewnętrzne usługi (mockuj lub używaj testowej bazy), i unikaj współdzielonego stanu między testami. Szybkie testy są uruchamiane; powolne są pomijane.
Uruchomienie aplikacji FastAPI w sieci to głównie wybór "runnera" i dodanie kilku elementów produkcyjnych.
Uruchamiając uvicorn main:app --reload lokalnie, korzystasz z ustawień developerskich: auto-reload, rozbudowane błędy i wygodne opcje. W produkcji zwykle uruchamiasz Uvicorn bez reload, często za menedżerem procesów (np. Gunicorn z workerami Uvicorn) lub za reverse proxy. Celem jest stabilność: kontrolowane restarty, przewidywalna wydajność i bezpieczniejsze domyślne ustawienia.
Częsty wzorzec:
To pozwala jednym kodem wdrażać go w różnych środowiskach bez edycji plików.
Zanim uznasz projekt za „gotowy do wysyłki”, upewnij się, że masz:
/health do monitorowania uptime i integracji z load balancerami.Jeśli przechodzisz z „działa lokalnie” do „gotowe do wdrożenia”, warto też ustandaryzować sposób generowania i zarządzania kontraktem API. Niektóre zespoły łączą OpenAPI z automatycznymi workflow — np. generowanie klientów, walidacja w CI i spójne wydania. Narzędzia takie jak Koder.ai mogą pomóc w tej fazie: opisujesz API w rozmowie, iterujesz endpointy i modele szybko, a następnie eksportujesz kod do normalnego procesu przeglądu/wdrożenia.
FastAPI to framework webowy Pythona do budowania API z minimalnym boilerplate. Piszesz funkcje endpointów (np. @app.get("/users")), a FastAPI zajmuje się routingiem, analizą żądań, walidacją i zwracaniem JSON-a.
Kluczową zaletą jest to, że wskazówki typów i modele Pydantic działają jako jawny kontrakt określający, co API przyjmuje i zwraca.
API to zbiór URL-i (endpointów), które inne oprogramowanie może wywoływać, aby wymieniać dane.
Na przykład klient może poprosić o dane pogodowe poleceniem GET /weather?city=Berlin, a serwer odpowiada ustrukturyzowanym JSON-em. Klient nie potrzebuje bezpośredniego dostępu do bazy danych — korzysta z odpowiedzi API.
Routing mapuje metodę HTTP + ścieżkę na funkcję Pythona.
W FastAPI zwykle używasz dekoratorów:
@app.get("/items") dla operacji odczytu@app.post("/items") dla tworzenia@app.put("/items/{id}") do aktualizacji/zastąpieniaParametry ścieżki są częścią struktury URL i zwykle identyfikują konkretny zasób (są wymagane).
GET /users/42 → 42 to parametr ścieżkiParametry zapytania (query) są dopisywane po ? i zwykle służą do filtrowania lub sterowania odpowiedzią (są opcjonalne).
Modele Pydantic definiują kształt i zasady danych (typy, pola wymagane, ograniczenia). FastAPI używa ich do:
Jeśli walidacja zawiedzie, FastAPI zwykle odpowiada 422 Unprocessable Entity i zwraca szczegóły, które pole jest niepoprawne.
FastAPI automatycznie generuje schemat OpenAPI z Twoich endpointów, wskazówek typów i modeli.
Dostajesz zazwyczaj interaktywne strony dokumentacji za darmo:
/docs/redocPonieważ schemat jest wyprowadzany z kodu, dokumentacja aktualizuje się wraz ze zmianami parametrów i modeli.
Używaj async def, gdy endpoint dużo czasu spędza na oczekiwaniu na I/O (zapytywania do bazy, zewnętrzne żądania HTTP, operacje na obiektach).
Używaj zwykłego def, gdy:
Mieszanie sync i async w tej samej aplikacji jest powszechne.
Dependencies to wielokrotnego użytku „klocki”, które FastAPI wstrzykuje do endpointów przez Depends().
Służą zwykle do:
To zmniejsza powtarzalność i centralizuje logikę przekrojową, więc zmiany wprowadzasz w jednym miejscu.
FastAPI nie zabezpiecza aplikacji automatycznie — wybierasz schemat i stosujesz go konsekwentnie.
Popularne wzorce:
X-API-Key)Pamiętaj też o podstawach:
Do testów możesz użyć TestClient z FastAPI/Starlette, aby wywoływać API w procesie (bez uruchamiania osobnego serwera).
Praktyczne rzeczy do sprawdzania:
Do wdrożenia używaj serwera ASGI (np. Uvicorn, często za Gunicorn lub za reverse proxy) i dodaj elementy produkcyjne: logowanie, health checki, timeouty i konfigurację przez zmienne środowiskowe.
@app.delete("/items/{id}")To sprawia, że powierzchnia API jest łatwa do przeglądania bezpośrednio z kodu.
GET /users?limit=10&active=true → limit, active to parametry query