GitHub Copilot CLI ile FastAPI Geliştirme Rehberi

GitHub Copilot CLI, copilot komutuyla FastAPI projenizde terminalden çalışan bir kodlama ajanıdır; proje kökündeki .github/copilot-instructions.md veya AGENTS.md dosyasındaki kuralları okuyarak endpoint, Pydantic modeli, dependency injection ve async testleri sizin istediğiniz biçimde üretir. Daha ayrıntılı kurulum için GitHub Copilot CLI sayfasına bakabilirsiniz. Bu rehber, FastAPI’ye özel çalışma düzenini pratik örneklerle anlatır.

FastAPI işlerinde GitHub Copilot CLI’nin güçlü yanları

FastAPI, tip ipuçlarına dayalı deklaratif bir yapı sunar; path operation imzaları, Pydantic şemaları ve Depends bağımlılıkları neredeyse her dosyada aynı kalıpları izler. GitHub Copilot CLI bu kalıpları proje genelinde tutarlı biçimde üretebilir; örneğin yeni bir kaynak eklerken router, schema ve test üçlüsünü tek komutla oluşturur. Ayrıca async/sync ayrımını açıkça görebildiği için I/O yoğun endpoint’lerde async def, CPU yoğun işlerde senkron fonksiyon önerebilir. Talimat dosyasına test komutlarını yazdığınızda ajan her değişiklikten sonra pytest çalıştırıp hatayı düzeltebilir; bu, TestClient ile hızlı doğrulama yapılan FastAPI projelerinde döngüyü kısaltır. Ayrıca tip ipuçları sayesinde ajanın ürettiği kod, çalışma zamanı hatalarını azaltır; örneğin bir Pydantic modelindeki alan adını yanlış yazdığında static analiz yakalar. FastAPI’nin açık dokümantasyonu ve yaygın kullanımı, ajanın eğitim verisinde bol örnek bulunmasını sağlar; bu da önerilerin projeye uyumunu artırır.

Proje kurulumu ve ajan talimatları

Ajanın FastAPI kurallarınızı bilmesi için kök dizine .github/copilot-instructions.md veya AGENTS.md koyun. Dosya yazımıyla ilgili adım adım anlatım için GitHub Copilot CLI nasıl kullanılır? Adım adım rehber sayfasına göz atabilirsiniz. Aşağıdaki örnek, FastAPI projesine özel komutları, klasör yapısını ve kuralları içerir:

# FastAPI proje talimatları
## Komutlar
- Kurulum: `pip install -e ".[dev]"`
- Test: `pytest -q`
- Lint: `ruff check .`
- Format: `black .`

## Klasör yapısı
- `app/main.py`: FastAPI örneği ve router kayıtları.
- `app/routers/`: her kaynak için bir dosya, `APIRouter` kullanın.
- `app/schemas/`: istek ve yanıt için Pydantic modelleri.
- `app/services/`: iş mantığı; path operation fonksiyonlarını ince tutun.

## Kurallar
- Tüm istek ve yanıt gövdeleri `app/schemas` içindeki Pydantic modellerini kullanır.
- Veritabanı oturumu ve mevcut kullanıcı için `Depends` ile dependency injection uygulayın.
- I/O yoğun endpoint'ler `async def` olmalı; event loop'u bloklamayın.
- Yeni bir endpoint, `tests/` altında `TestClient` kullanan bir test ile gelmelidir.
- `app/main.py` değişikliği yalnızca ilgili test güncellendiyse yapılır.

Bu dosya sayesinde ajan, FastAPI’ye özgü response_model, Depends ve APIRouter kullanımını varsayılan olarak uygular; ayrıca test komutunu bildiği için her turda doğrulama yapabilir. Kurulum sırasında pip install -e ".[dev]" komutu, geliştirme bağımlılıklarını da yükler; pytest, ruff ve black komutlarının PATH’te olduğundan emin olun. Ajan, talimat dosyasını her çalıştırmada yeniden okur; bu yüzden kuralları değiştirdikten sonra yeni bir oturum başlatmak veya copilot komutunu yeniden çalıştırmak gerekir. Klasör yapısını netleştirmek, ajanın yeni dosyaları doğru yere koymasını sağlar; özellikle schema ve router ayrımı, import hatalarını azaltır. Ayrıca response_model kullanımını zorunlu kılmak, Pydantic modelinin yanıt olarak döndürülmesini garanti eder; ajan bu kuralı ihlal ederse testler yakalar.

Çalışma döngüsü: planla, küçük adımlar, test et, diff’i incele

copilot komutunu proje klasöründe çalıştırdıktan sonra şu döngüyü izleyin: önce ajanın mevcut dosyaları ve talimatları okuduğundan emin olun; görevi tek seferde büyük bir özellik olarak değil, endpoint + model + test gibi küçük adımlara bölün; her adımdan sonra pytest -q çalıştırıp testleri doğrulayın; ardından git diff ile değişiklikleri inceleyin. Daha büyük özelliklerde spec odaklı ilerlemek için Yapay zekâ ajanlarıyla spec odaklı geliştirme rehberi yaklaşımını kullanabilirsiniz.

Ajan, verilen görevi tamamladığında genellikle kendi kendine testleri çalıştırır; ama siz yine de terminalde pytest -q ile doğrulayın. Eğer test başarısız olursa hata mesajını ajanın bir sonraki turuna yapıştırın; ajan genellikle düzeltmeyi kendisi yapar. Başarılı bir adımdan sonra git diff ile değişiklikleri inceleyin; özellikle Pydantic model değişikliklerinde alan tipleri, Field kısıtlamaları ve response_model güncellemelerini kontrol edin. Küçük adımlar, bir hatanın geri alınmasını kolaylaştırır; git checkout -- . veya git revert ile son değişikliği geri alabilirsiniz.

FastAPI görevleri için örnek promptlar:

• app/routers/items.py içinde GET /items/{item_id} endpoint’ini oluştur; app/schemas/item.py içinde ItemResponse Pydantic modelini kullan, yanıtı TestClient ile test et.
• Mevcut create_user endpoint’ine email doğrulaması ekle; Pydantic EmailStr kullan ve bağımlılık olarak get_db’yi koru. Testi güncelle.
• GET /users endpoint’ini async hale getir, veritabanı çağrısını async sürüme taşı ve pytest ile doğrula.
• Pydantic modelindeki price: float alanına gt=0 doğrulaması ekle, sonra ilgili testi yaz.
• Proje kökündeki tests/test_health.py dosyasını çalıştır; başarısız olursa hatayı düzelt.
• app/routers/orders.py içinde POST /orders endpoint’ini oluştur; istek gövdesi OrderCreate şemasını kullansın, oluşturulan kaydı OrderResponse ile döndür, bağımlılık olarak get_db ve current_user kullan.
• tests/test_items.py içindeki tüm testleri gözden geçir; eksik olan doğrulamaları ekle, örneğin 404 durum kodu ve hata mesajı kontrolü.

Bu döngüde ajanın yaptığı değişiklikleri küçük tutmak, Pydantic şema değişikliği veya dependency override hatasını hızla yakalamanızı sağlar.

Neyi iyi yapar, nerede dikkat gerekir?

GitHub Copilot CLI, FastAPI projelerinde şunları iyi üretir: Pydantic şemaları (BaseModel, Field, EmailStr), path operation imzaları (status_code, response_model), Depends bağımlılıkları, APIRouter dosyaları ve TestClient tabanlı testler. Ayrıca import düzenleme ve router kayıtlarını güncelleme işlerinde tutarlıdır. Ajan, mevcut kodun stilini taklit eder; bu yüzden projenizde örnek bir router ve test dosyası bulundurmak, üretilen kodun kalitesini artırır.

Buna karşın FastAPI’ye özgü bazı noktalarda ajanı yakından izlemek gerekir:

Özellikle Pydantic v2 geçişi, dependency override (app.dependency_overrides) ve async/sync karışımı konularında ajanın önerdiği kodu doğrudan kabul etmeyin; git diff sonrası bu satırları inceleyin. Ajan bazen response_model içinde yanlış tip belirtebilir veya List[ItemResponse] yerine ItemResponse döndürebilir; testler bu durumu yakalamalıdır. Ayrıca APIRouter kullanırken prefix ve tags değerlerini doğru ayarlamaya dikkat edin; ajan bu değerleri atlayabilir.

Test ve doğrulama

FastAPI projesinde ajanla çalışırken doğrulama iki aşamalıdır: ajanın kendi çalıştırdığı testler ve sizin manuel incelemeniz. Her değişiklikten sonra pytest -q --disable-warnings komutunu çalıştırın; başarısız test varsa hatayı ajanın bir sonraki turuna yapıştırın. TestClient kullanan testlerde bağımlılıkları app.dependency_overrides[get_db] = override_get_db gibi geçersiz kılmayı unutmayın; ajan bu satırı genellikle ekler ama fixture’ların temizlendiğinden emin olun. Pytest fixture’ları kullanarak her test için ayrı bir test veritabanı veya geçici dosya oluşturabilirsiniz; örneğin tmp_path fixture’ı ile SQLite veritabanı kullanmak yaygındır. Ajan bu kalıbı öğrendiğinde, yeni testlerde fixture’ı otomatik kullanır.

Async endpoint’ler için TestClient senkron olarak çalışır; test fonksiyonlarını normal def olarak yazın. Eğer doğrudan async fonksiyonları test etmek isterseniz pytest-asyncio eklentisi gerekir; bunu talimat dosyasına ekleyin. Ajan bazen async testleri yanlış yazar; bu yüzden TestClient tercih edin. Ayrıca ruff check . ve black --check . ile stil tutarlılığını doğrulayın. Son olarak git diff üzerinde endpoint imzalarını, response_model alanlarını ve Pydantic schema değişikliklerini gözden geçirin; bu adım, yanlışlıkla kaldırılmış bir doğrulamayı yakalamanın en hızlı yoludur. Örneğin, ajan bir Field kısıtlamasını kaldırdıysa bunu diff’te fark edersiniz.

Birden çok ajanı AgentVera ile paralel çalıştırma

FastAPI projelerinde birden fazla özelliği paralel yürütmek için AgentVera masaüstü uygulaması GitHub Copilot CLI gibi ajanları aynı pencerede, her biri kendi gerçek terminal panelinde çalıştırır. Her ajan ayrı bir git worktree’de çalışabildiği için endpoint, şema veya test dosyaları birbirinin üzerine yazmaz. Bir ajanın turu bitince ikinci model otomatik kod incelemesi yapar ve bulguları file:line olarak gösterir; FastAPI’de Pydantic modeli veya dependency hatalarını hızla yakalarsınız. Ayrıca her turun checkpoint’i geri alınabilir, böylece yanlış bir refactor’ü tek tıkla eski haline döndürürsünüz.

Özet

GitHub Copilot CLI, FastAPI projelerinde talimat dosyasıyla yönlendirildiğinde endpoint, Pydantic modeli, dependency injection ve test üretimini hızlandırır. Başarılı sonuç için görevleri küçük tutun, her adımda pytest çalıştırın ve git diff ile FastAPI’ye özgü noktaları denetleyin; paralel çalışma gerektiğinde AgentVera’yı işin içine katabilirsiniz. Unutmayın ki ajan bir araçtır; FastAPI’nin inceliklerini bilen siz, onun çıktısını doğrulayarak kaliteyi garanti edersiniz.