Laravel API Sürümleme Stratejileri: Gelecekteki Değişikliklere Hazırlık

Starter kitler, ilk 30 günü kolay hissettirmekte etkilidir. Kullanıcı doğrulama, kaynaklar, testler ve yönlendirmeleri düzenleyerek bir Laravel API’sinin geliştirilmesine olanak tanır. Fakat altıncı ayda, gerçek zorluklar ortaya çıkar.

Bir mobil uygulama, aslında farklı adlarla adlandırılmış yanıt alanlarına bağımlı hale gelir. Bir entegrasyon ortağınız içeride olduğunu düşündüğünüz enum değerlerini önbelleğe alır. Bir zamanlar zararsız olan bir uç nokta, faturalama, kontrol panelleri, dışa aktarımlar ve webhook iş akışları için kritik hale gelir. Birisi radikal bir temizleme önermekle kalmaz, herkes bunun teknik olarak doğru olduğunu kabul eder, fakat kimse sonuçlarından sorumluluk almak istemez.

Bu, starter kitlerin gizlediği zorluklardan biridir.

Starter kitler, bir API’yi başlatmanıza yardımcı olurlar. Fakat gelecekteki kırıcı değişiklikleri yönetililebilir kılmazlar. Eğer başlangıç projeniz sürümleme disiplinini, göç yollarını ve geçersiz hale getirme davranışını baştan zorlamıyorsa, bir temel inşa etmiyorsunuz. Sadece yarının politik sorununu yapılandırıyorsunuz.

Starter Kitlerin Yalnızca İlk Yayın İçin Optimize Olması

Çoğu API başlangıç projesi hızlı bir şekilde verimlilik sağlamaya odaklanır. Bu makul bir hedefdir. Fakat hangi alanlarda optimize ettikleri önemlidir.

• hızlı kullanıcı doğrulama ayarları
• örnek sınıflar ve sayfalama
• temiz istek doğrulaması
• basit kontrolör kalıpları
• kolay yerel testler

Tüm bunlar faydalıdır. Ancak zor soru şudur: bu API daha sonra isteyerek kırılması gereken durumlarla nasıl başa çıkacak? Bu nokta, başarılı olmanın doğal bir sonucu olarak ortaya çıkan kırıcı değişikliklerin bir kenara atılması demektir.

Tanıdık Göç Hikayesi

Küçük bir iç API, ortak bir API haline gelir. Bir web istemcisi, web artı mobil artı otomasyon haline dönüşür. “Geçici” bir alan, başka birinin raporlama mantığının parçası haline gelir. Starter kitinizdeki bir kısayol, gerçek dünyada bir sözleşmeye dönüşür.

Bu aşamada, ekip, uygulama kodu olarak gördükleri şeyin aslında kamu altyapısı olduğunu keşfeder.

Starter Kitlerin Gelecekteki Acıların Hızla Oluşması

Birçok starter kurulumu, kasıtlı olarak kötü uzun vadeli davranışları teşvik ediyor:

• resource’lar aracılığıyla Eloquent yapısını doğrudan döndürmek
• alan adlarını mevcut tablo anlamsal yapısına bağlamak
• “İleride değiştirebiliriz” diyerek sözleşme sahipliğini atlamak
• doğrulama kurallarını API sözleşmesini tamamen tanımlıyormuş gibi ele almak
• geçersiz hale getirme planı olmadan her şey için bir rota düzeni pişirmek

Bunlar ilk günde ölümcül değildir. Bir araya geldiklerinde ise 300. günde durumu sıkıntılı hale getirir.

Yaşanabilir Bir API Starter Kit, Göçün Kaçınılmaz Olduğunu Varsayar

Doğru bakış açısı açıktır: API’niz başarılı olursa kırıcı değişikliklere ihtiyaç duyacaksınız.

Alan adlarını yeniden adlandıracak, uç noktaları ayıracak, doğrulamayı sıkılaştıracak, sızdıran soyutlamaları kaldıracak veya farklı alan sınırlarını açığa çıkaracaksınız. Bu, normaldir. Tekrar eden sürümleme stratejileri oluşturmak için baskı altında kalmak bir hata olacaktır.

Daha iyi bir başlangıç kitinin göçü, ilk günden itibaren birinci sınıf bir endişe olarak ele alması gerekir.

Taşıma Sözleşmesini Ürün Yüzeyi Olarak Tasarlayın

Eloquent modelleriniz API’niz değildir. İç hizmet adlarınız API’niz değildir. Mevcut veritabanı düzeniniz kesinlikle API’niz değildir.

Yaşanabilir bir başlangıç projesi, iç kod ile dış sözleşme arasında bir mesafe sağlar.

Bu genellikle şunları içerir:

• belirgin API kaynakları veya dönüştürücüler
• istikrarlı alan adlandırma kararları
• öngörülebilir hata yapıları
• belirgin sayfalama meta verileri
• kod yapı dışındaki alan terimleri

Kaynak katmanınız, bugünkü şemanın ince bir yansımasıysa, zamanı kiralayacaksınız.

“Temiz” Dahili Yapıların Sözleşme Şeklini Sızdırmasından Kaçının

Ekipler, şu anda uygun olan alanları açığa çıkarma eğilimindedir, daha sonra bundan pişman olurlar.

Örneğin, ham iş akışı durumlarını döndürmek sizi hızla kapana kısılmaya zorlayabilir:

return [
    'id' => $invoice->id,
    'status' => $invoice->status,
    'sent_at' => $invoice->sent_at,
    'paid_at' => $invoice->paid_at,
];

Bu, zararsız görünür ancak status basit bir enumdan daha ayrıntılı bir durum modeline dönüştüğünde veya sent_at doğru iş işareti olmaktan çıktığında, bu sorun haline gelir.

Daha iyi bir sözleşme genellikle daha düşünceli bir şekilde olur:

return [
    'id' => $invoice->public_id,
    'state' => $invoice->apiState(),
    'timeline' => [
        'issued_at' => $invoice->issued_at ?->toIso8601String(),
        'settled_at' => $invoice->settled_at ?->toIso8601String(),
    ],
    'links' => [
        'self' => route('api.v1.invoices.show', $invoice),
    ],
];

Burası, temiz görünmekten çok, iç temizliğin dışarıya yanlışlıkla kırıcı hale gelme ihtimalini azaltmakla ilgilidir.

Sürümleme Stratejisi, Rota Ön Eklentilerinden Daha Fazlasıdır

Bir /v1 ön eki iyi bir başlangıçtır. Çoğu zaman pratik bir seçimdir. Ancak takımlar bunun neyi çözdüğünü abartma eğilimindedir.

Bir rota ön eklentisi, değişiklikler için bir ad alanı sağlar. Ancak size bir göç politikası, bir geçersiz hale getirme zamanlaması veya bir dağıtım planı sunmaz.

Tek sürümleme fikriniz “ileride /v2 yaparız” ise, gerçekten bir sürümleme stratejiniz yok. Gelecekteki bir kaçış kapısı var fakat arkasında bir işletim modeli yok.

Gerçek Göç Acısı Üç Yerde Ortaya Çıkar

Laravel API’leri değişmesi zor hale geldiğinde, direnç genellikle üç kaynaktan gelir: müşteri genişlemesi, belirsiz geçersiz hale getirme veya eksik uyumluluk sınırlamaları.

Müşteri Genişlemesi “Küçük” Değişiklikleri Politik Hale Getirir

Bir uç nokta nadiren tek bir temiz tüketiciye bağlı kalır.

Mobil uygulama uç noktası, şunlara kullanım alanı bulur:

• web ön yüzü
• eskiden gelen mobil istemciler
• yönetim araçları
• ortağı entegre eden yazılımlar
• Zapier tarzı otomasyonlar
• belgelendirilmemiş iç komut dosyaları

Bu noktada, bir alanı kaldırmak veya bir doğrulama kuralını değiştirmek, yalnızca bir kod kararı haline gelmiyor. Koordinasyon sorunu haline geliyor.

Bu yüzden starter kitler, bilinmeyen tüketicilerin ortaya çıkacağını varsaymalıdır. Eğer bugün kontrol ettiğiniz müşteri için yalnızca tasarlıyorsanız, kendi başarınızı yanlış değerlendiriyorsunuz demektir.

Belirsiz Geçersiz Hale Getirme, Yanlış Stabilite Yaratır

Pek çok takım, kırıcı değişikliklerden kaçınarak güvende olduklarını düşünürken, aslında sözleşmenin kötüleşmesini ertelemektedirler.

Aşama sürekli olarak belirsiz kalmaktadır. Eski filtreler desteklenmeye devam eder ancak belgelendirilmez. İki yanıt şekli resmi olarak bir arada bulunur. Hangi davranışın standart olduğunu kimse bilmez.

Bu, stabilite değildir. Bu, geriye dönük uyumluluk korkusunun örtünmesidir.

Eksik Uyumluluk Sınırlamaları, Her Şeyin Yeniden Yazılmasını Zorlar

Kontrolör mantığı, doğrulama, kaynak dönüştürme ve alan yönlendirmeleri sıkı bir şekilde bağlı olduğunda, her kırıcı değişiklik tam bir yeniden yazım gibi hissedilir.

Takımın “Bu uç noktayı sürümleyemeyiz.” gibi şeyler söylemesine neden olur.

Genellikle gerçek problem, sürümlendirmenin kendisi değil; kod tabanı eski ve yeni sözleşme davranışlarının temiz bir şekilde bir arada durmasını sağlayacak dikişler oluşturmadığıdır.

İyi Bir Starter Kit, Sözleşme Bağlantılarını Uygun Fiyatlı Hale Getirir

Eğer gelecekte kırıcı değişikliklerin yönetilebilir olmasını istersek, starter projeniz, sözleşme evrimini sözleşme değişimine göre daha kolay hale getirmelidir.

Bu, gerekli olan doğru yerlerde dikişler inşa etmek anlamına gelir.

Mümkünse Alan Eylemlerini Sürümden Bağımsız Tutun

Temel iş mantığınız, çağrının v1 veya v2 olup olmadığını umursamamalıdır. Sürümleme baskısı esasen sözleşme sınırında bulunmalıdır.

İyi bir yapı aşağıdaki gibi görünür:

• istek sınıfları taşıma girişini doğrular
• kontrolörler istek verilerini uygulama eylemlerine haritalar
• hareketler/hizmetler alan çalışmasını gerçekleştirir
• kaynaklar/dönüştürücüler çıkışı sözleşme sürümüne göre şekillendirir

Bu, API sözleşmesini geliştirmeyi sağlar ve uygulama katmanını tekrar etmeye gerek kalmadan yürütür.

Önce Kaynakları Sürümleyin, Her Şeyi Sürümlemeyin

Pek çok Laravel API’sinde ilk temiz dikiş kaynak katmanıdır.

Örneğin:

Route::prefix('v1')->name('api.v1.')->group(function () {
    Route::get('/users/{user}', [V1UserController::class, 'show'])->name('users.show');
});

Route::prefix('v2')->name('api.v2.')->group(function () {
    Route::get('/users/{user}', [V2UserController::class, 'show'])->name('users.show');
});

Burası bir tekrarlama gibi görünebilir, ama derin bir tekrarlama olmasına gerek yoktur.

final class V1UserController {
    public function show(User $user, ShowUserAction $action): V1UserResource {
        return new V1UserResource($action->execute($user));
    }
}

final class V2UserController {
    public function show(User $user, ShowUserAction $action): V2UserResource {
        return new V2UserResource($action->execute($user));
    }
}

Aynı alan eylemi. Farklı sözleşme şekli.

Bu, yönetilebilir bir göç yolu sağlar. Tüm yığınları bölmekten veya eski yanıtın sonsuza kadar sürmesi gerektiğini düşünmekten çok daha iyidir.

Doğrulama Değişikliklerini, Tüketicilerin Hissettiği Zaman Sürüm Değişiklikleri Olarak Ele Alın

Laravel doğrulamayı kolaylaştırır; bu harika bir özellikdir. Aynı zamanda ekiplerin, doğrulama davranışlarının sözleşmenin bir parçası olduğunu unutmalarına neden olur.

Örneğin, phone v1 içinde isteğe bağlıysa ve v2 içinde zorunlu hale gelmişse, bu yalnızca bir form kuralı değişikliği değil, büyük bir kırıcı API değişikliğidir.

Başlangıç kitleri, herkesin gizlice değiştiği tek bir standart doğrulayıcı yerine sürüm bilinçli istek sınıflarına teşvik etmelidir.

Hata Biçimi Stabilitesi, Ekiplerin Düşündüğünden Daha Önemlidir

Pek çok müşteri acısı, mutlu yol yanıtlarından değil, tutarsız hata davranışlarından gelir.

Eğer başlangıç projeniz başka bir şey yapmıyorsa, şu noktaları standart hale getirin:

• hata zarfı yapısı
• doğrulama hata yapısı
• gerekli olduğunda makine tarafından okunabilir hata kodları
• eski davranışların ortadan kaldırılmasına dair geçersiz hale getirme başlıkları veya uyarılar

Takımlar genellikle kaynak alanlarına takılırken, hata sözleşmesi kaymasına aldırış etmezler. Bu, özellikle ortak veya mobil tüketiciler için büyük bir hatadır.

Geçersiz Hale Getirme Politikası, Çoğu Ekibin Atladığı ve Sonradan Pişman Olduğu Kısımdır

Bu parça, sürümlemeyi kod organizasyonundan operasyon sal olgunluğa dönüştüren kısımdır.

Bir geçersiz hale getirme politikası olmadan, her kırıcı değişiklik bir müzakere haline gelir.

Bu, yıldırıcıdır.

Gerçek Bir Geçersiz Hale Getirme Politikası Ne Cevaplamalı?

En azından, ekibinizin şu soruları geniş bir kapsama yayılan bir API sunmadan önce yanıtlayabilmesi gerekir:

• Tüketiciler nasıl bir alan veya uç noktanın geçersiz hale getirildiğini bilecek?
• Geçersiz hale getirilen davranış ne kadar süre desteklenecek?
• Göç kılavuzu nerede bulunacak?
• Eski sürüm kullanımında hangi telemetriye sahibiz?
• Kaldırılmasına ne zaman izin verileceğine kim karar verir?

Eğer bunların çoğuna “bunu daha sonra çözmeye çalışırız” cevabını veriyorsanız, o zaman ilerideki dönem karmaşık olacaktır.

Bunu Gerçekleştirmek için Pratik Laravel Yöntemi

Bir standartlar komitesine ihtiyacınız yok. Birkaç işler hale getirilebilir alışkanlığa ihtiyacınız var.

Örneğin:

• sürüm alan adlarını açıkça dışa aktarın
• isteğe bağlı ya da jeton kullanarak sürüm kullanımında gün loglayın
• belgelerde ve olası başlıklarda geçersiz hale getirme verileri yayınlayın
• her kırıcı sürüm için göç notları yazın
• kaldırılmadan önce bir destek süresi tanımlayın

Basit geçersiz hale getirme işaretleri bile büyük bir fark yaratabilir.

return response()
    ->json((new V1UserResource($user))->resolve())
    ->header('X-API-Deprecation', 'User full_name will be removed on 2026-09-01')
    ->header('X-API-Sunset', '2026-12-01');

Bunu aşırı mühendis hale getirmeye gerek yok; fakat sözleşme kaldırmanın yönetilen bir süreç olduğunu normalleştirmek önemlidir, sürpriz bir işlem değildir.

Göç Notları Operasyonel Belgeler Gibi Yazılmalıdır

Kötü göç notları şunları belirtir:

• full_name adlandırması name olarak değiştirildi
• sayfalama formatı güncellendi
• doğrulama kuralları güncellendi

Faydalı göç notları ise şunları belirtir:

• hangi istemcilerin etkilendiği
• eski ve yeni istek/yanıt şekillerinin nasıl göründüğü
• eski ve yeni sürümlerin geçici olarak bir arada durup duramayacağı
• öngörülen geri dönüş davranışının neler olduğu
• hangi son tarihin önemli olduğu ve neden

Burada amaç belirsizliği azaltmaktır, sadece değişimi duyurmak değil.

En İyi Göç Hikayeleri İkinci Sürüm Varken Başlar

İyi bir göç hikayesi /v2 yaratıldığında başlamaz. /v1 öyle tasarlanmalıdır ki /v2 çıkarılınca hiçbir gerilim yaşanmasın.

Bu, starter kitinizin yalnızca uç noktaları oluşturmakla kalmayıp, bir dünya görüşünü kodlaması gerektiği anlamına gelir.

O Dünya Görüşünün İçermesi Gerekenler

Kırıcı değişikliklere ciddi yaklaşan bir başlangıç kiti, takımları şunlara yönlendirmelidir:

• belirgin sözleşme kaynakları
• kararlılık hata zarfları
• sözleşme düzeyinde testler
• sürüm bilinçli belgelerin yapısı
• belirli rota adlandırma ve ad alanı sınırları
• sözleşme sürümlerinden bağımsız olarak süren eylem/hizmet katmanları
• tüketici davranışına dair telemetri

Bu, iyi bir demo gerçekleştiren bir starter kit ile başarının keyfini süren bir kit arasındaki farktır.

Sözleşme Testleri Bu Noktada Göz Ardı Edilmektedir

Eğer yalnızca alan davranışını test ediyorsanız, sürüm kayması, serileştirme ve doğrulama değişiklikleri üzerinden içeri sızabilir.

Sözleşme temelli testler ekleyerek yanıt şeklinizi kasıtlı bir şekilde kilitleyebilirsiniz.

it('returns the v1 user contract', function () {
    $user = User::factory()->create();

    $this->getJson("/api/v1/users/{$user->id}")
        ->assertOk()
        ->assertJsonStructure([
            'data' => [
                'id',
                'full_name',
                'email',
            ],
        ]);
});

Ardından, hem v2 için aynı testi yapın; her iki sürümün de aynı şekilde serileştirilmesi gerektiğini düşünmekten kaçının.

Bu testler değişimi durdurmaz. Değişimi dikkatlice planlamayı zorlar.

“Sonsuza Kadar Tek Sürüm” Yanılsamasasından Kaçının

Pek çok ekip, “tek bir sürümü” istemekle, temiz ve modern bir API isteyen bir yaklaşımın peşindedir. Ancak bu, istemcilerin garantiler talep etmesi gerektiğinde sorun yaratır.

Eğer her tüketici yeterince kontrol altındaysa, belki bir süre için yerinde evrim gerçekleştirebilirler. Fakat çoğu takım uzun süre her tüketiciyi kontrol altında tutamaz.

Bir kez dış veya yarı dış tüketiciler olduğunda, sessiz evrimin daha kolay olduğunu düşünmek genellikle herkes için karmaşayı artırır.

Hiçbir şey, sürümlemeyen ve iyileştirilmesi imkânsızlaşmış bir API kadar güzel değildir.

Gelecek Hayatta Kalma İçin Pratik Bir Starter Kit Kontrol Listesi

Eğer bugün bir Laravel API başlangıç projesi tasarlıyorsanız veya seçiyorsanız, ne kadar hızlı doğrulama kurduğuna değil, daha sonraki göçleri ne kadar kolay hale getireceğine göre değerlendirin.

Güçlü bir başlangıç projesinin, şu noktalarda kolaylık sağlaması gerekir:

• belirgin sözleşme kaynakları tanımlamak
• rota veya sözleşme isim alanlarını temiz bir şekilde sürümlemek
• sürüm başına istek doğrulamasını değiştirip değiştirmek
• alan eylemlerini sürümler arasında paylaşmak
• hata zarflarını standart hale getirmek
• geçersiz hale getirme verileri ve belgeleri eklemek
• yanıt sözleşmelerini alan mantığından ayrı test etmek
• istemcilerin hangi sürümleri kullandığını izlemek

Bunun yanında size bunları yapma olanağı sunmıyorsa, sadece kolay yarısı çözülmektedir.

Bu, başlangıç kitinin işe yaramaz olduğu anlamına gelmez. Bu sadece, onun tamamlanmış bir mimari olduğunu söylemeyi bırakmanız gerektiği anlamına gelir.

Aslında API acısı genellikle ilk uç noktaların oluşturulmasından gelmez. Diğer insanların bu uç noktalara bağımlı hale gelmesinden sonra onları geliştirmeye ihtiyacınız olduğunda gelir.

Bu nedenle en iyi Laravel API sürümleme stratejisi, URL sürümleme, başlık sürümleme veya medya türü müzakere etme arasında akılda kalan bir seçim yapmak değil, daha somut bir kuraldır:

Gelecekteki kırıcı değişiklikleri izolasyona, gözlemlenebilirliğe ve yönetilebilirliğe odaklanarak starter projenizi optimize edin.

Tek bir pratik çıkarım istiyorsanız, kullanın:

/v1 sürümünü, /v2 sürümünün kaçınılmaz olduğu varsayılarak oluşturun, umuyorum ki gelmez.

Çünkü eğer API’niz başarılı olursa, değişiklik gelecektir. Bunu hayata geçirebilen takımlar, sadece en güzel başlayıcı kitlere sahip olanlar değildir. Geçişi tasarım kaygısı haline getirenlerdir.

Tam makalenin üzerinden geçin: https://qcode.in/laravel-api-starter-kits-hide-the-hard-part-breaking-changes-later/