Göztepeli.com

Göztepeli.com, Python ve FastAPI ile web geliştirmeyi öğrenmek isteyenler için hazırladığım Türkçe bir eğitim projesi. Depoyu 2025 yılının başında goztepeli.com alan adı için açmıştım; 2026'nın Nisan ayında baştan yazarak bir eğitim projesine dönüştürdüm. Proje küçük bir örnek kodla yetinmiyor. Uygulama kodunun yanında testleri ve uygulamayı gerçek bir sunucuda yayına alan kurulum betiğini de içeriyor.

Amaç

Web geliştirmeye yeni başlayanların en çok zorlandığı konulardan biri, bir isteğin tarayıcıdan sunucuya nasıl gittiğini ve sunucunun hangi durumda hangi yanıtı döndürmesi gerektiğini kavramak. Türkçe kaynakların çoğu ya yalnızca bir "merhaba dünya" örneği gösteriyor ya da konuyu yayına alma aşamasına gelmeden bırakıyor. Ben, okuyanın kodu kendi bilgisayarında çalıştırabileceği, tek tek deneyebileceği ve sonunda bir sunucuda yayına alabileceği bir kaynak hazırlamak istedim. Kodun her bölümünü Türkçe açıklamalarla yazdım; böylece dosyayı okumak tek başına bir ders gibi ilerliyor.

Nasıl çalışır

Uygulamanın tamamı main.py dosyasında ve toplam 21 uç nokta içeriyor. Dördü temel işler için: Jinja2 şablonuyla üretilen ana sayfa, sağlık kontrolü yapan /ping, DuckDB ile örnek bir SQL sorgusu çalıştıran /api/test ve bütün durum kodlarını listeleyen /api/durum-kodlari. Kalan 17 uç nokta, 200'den 503'e kadar birer HTTP durum kodunu örnekliyor. Bunların arasında 201 Created, 204 No Content, 301 ve 302 yönlendirmeleri, 304 Not Modified, 401, 403, 404, 409, 422 ve 429 gibi en sık karşılaşılan kodlar var.

Her uç noktanın açıklamasında o kodun ne zaman kullanıldığı, istemcinin ne yapması gerektiği ve gerçek hayattan bir örnek yazıyor. Örneğin 429 açıklamasında Retry-After başlığı ile sabit pencere, kayan pencere ve token bucket gibi hız sınırlama yöntemleri anlatılıyor. Bütün durum kodu uç noktaları kod, durum adı, Türkçe açıklama ve örnekten oluşan aynı JSON yapısını döndürüyor. FastAPI'nin ürettiği Swagger UI ve ReDoc sayfalarında uç noktalar 2xx, 3xx, 4xx ve 5xx olarak gruplanıyor.

Ana sayfadaki JavaScript dosyası fetch ve async/await kullanımını gösteriyor. Sayfa açıldığında sunucuya kendiliğinden bir ping gönderiliyor, aynı işi bir düğmeyle elle de yapmak mümkün. Dosyada ayrıca bir durum kodu uç noktasını doğru HTTP yöntemiyle çağırıp yanıtını işleyen örnek bir fonksiyon bulunuyor. Stil dosyası Göztepe'nin kırmızı ve sarı renkleriyle hazırlandı ve her kuralın neden yazıldığını anlatan notlar içeriyor.

Test ve yayına alma

• tests/test_endpoints.py, httpx ile bütün uç noktaları sırayla çağırıyor ve beklenen durum kodlarını kontrol ediyor. Dosya hem tek başına bir betik olarak hem de pytest ile çalıştırılabiliyor.
• install/nginx_fastapi.sh, Ubuntu sunucuya kurulumu 12 adımda yapıyor: sistem güncellemesi, Python 3.12, Nginx, Certbot, sanal ortam, paketler, uygulama dosyaları, systemd servisi, Nginx yapılandırması, Let's Encrypt sertifikası, servislerin başlatılması ve son doğrulama.
• Nginx yapılandırması HTTP'den HTTPS'e yönlendirme yapıyor ve HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy gibi güvenlik başlıklarını ekliyor.

Teknik altyapı

Uygulama Python 3.12 ve FastAPI ile yazıldı. Geliştirmede Uvicorn, canlı ortamda dört işçili Gunicorn ve UvicornWorker kullanılıyor. Veritabanı olarak ayrı bir sunucu gerektirmeyen DuckDB'yi seçtim. Redis kurulum betiğinde ve bağımlılıklarda yer alıyor, ancak uygulama kodu şimdilik onu kullanmıyor.