API sözleşmeniz CI içinde yer almalıdır

Bir Laravel API’si yayımladığınızda, OpenAPI belgelerinizi de yayınlarsınız. İkisi de lansman günü doğruydu.

Üç ay sonra ikisi de doğru değil.

Belki bir nullable yanıt alanına sızdı ve iOS istemcisi null pointer hatası almaya başladı. Belki bir alan v1.2 sürümünde yeniden adlandırıldı ve bir ortak entegrasyon sessizce iki hafta boyunca bozuldu. Belki tamamen yeni bir uç nokta eklendi ama belgelerde bir girdi yoktu ve bu, her yeni geliştirici için yanıltıcı oldu.

Belge yazıldığında yalan söylemedi. Sadece geçerliliğini yitirdi.

Bu durumu yakalamak, ne kadar geç yakaladığınıza bağlı olarak maliyetlidir: editörde ucuz, CI’da yönetilebilir, stagingde pahalı ve üretimde yıkıcıdır. Sözleşme ne kadar uzun süre doğrulanmamış kalırsa, ekibiniz o kadar güvenle bir hayali yapı üstünde çalışacaktır.

İyi haber şu ki, sözleşme sadece bir spesifikasyon dosyasıdır. Kontrol edilebilir. CI kontrol kapısı olarak kullanılabilir. Bu yazıda bahsedeceğim kontrol yöntemine pratik açıdan erişebildim.

“API sözleşmesi uyumu” aslında ne anlama geliyor

İki spesifik garanti:

1. Uygulama spesifikasyona uygun. Uygulamanın gerçekten sağladığı her rota, spesifikasyonda tanımlanmıştır. Ağa üstünden geçen her istek ve yanıt şekli spesifikasyondaki şemalara uymaktadır.
2. Özellik spesifikasyona uygun. Spesifikasyonda uygulamanın artık sağlamadığı rotaları tanımlayan hiçbir giriş yoktur. Spesifikasyondaki hiçbir şema uygulamanın artık üretmediği şekilleri tanımlamaz.
   Her iki yön de önemlidir. Eğer spesifikasyonunuz “/users DELETE destekler” diyorsa ve kod önceki sprintte DELETE’yi kaldırdıysa, istemciler DELETE çağrısı yapacak ve neden 405 hatası aldıklarını merak edecektir.

OpenAPI 3.0, bu sözleşmeyi yazmanın standart formatıdır. Yolları, işlemleri, parametreleri, istek gövdesini ve yanıt şekillerini tanımlayan bir YAML veya JSON belgesidir. Format o kadar olgun ki, bu yazıda açıklamaya geçmek istemiyorum. Eğer bir JSON HTTP API’si üzerinde çalışıyorsanız, daha önce OpenAPI’yi görmüşsünüzdür; görmediyseniz, spesifikasyon belgeleri kısa bir kaynaktır.

İlgilendirici soru “OpenAPI nedir” değil. İlgilendiren soru: spesifikasyonunuzu nasıl dürüst tutarsınız?

Üç tür kayma

Spesifikasyonunuz ile uygulamanız senkronize olmadığında, kayma üç ana kategoriye düşer.

Yapı kayması. Ekleme, kaldırma veya taşıma işlemleri. Spesifikasyon /v1/posts var der; kodunuzda yoktur. Veya kodunuz /v1/posts/{id}/restore var; spesifikasyonda yoktur.

Şekil kayması. İstek veya yanıt gövdesi artık şemayla eşleşmiyor. Spesifikasyon name‘nin zorunlu ve bir dize olduğunu belirtiyor; kodunuz artık bir dizi kabul ediyor ya da bu alanı tamamen kaldırdı.

Anlam kayması. Rota var ve şekil eşleşiyor fakat anlamı değişti. Aynı alan adı, farklı birim. Aynı durum kodu, onu döndürmek için farklı koşullar. Bu, programatik olarak yakalamak en zor olan sınıftır ve gerçekleştiğinde en masraflısıdır.

İlk iki sınıf mekanize edilebilir. Üçüncüsü genellikle gözden geçiren disiplinle ilgilidir. Aşağıda tarif edeceğim model, ilk iki sınıfı yeterince iyi yönettiğinden, geriye sadece üçüncü kalır.

Sözleşme uyumunun CI/CD kapısı olarak kullanımı

Bahsetmek istediğim model, sözleşme uyumunu bir derleme kapısı olarak ele almaktır. Ne yumuşak bir beklenti, ne de bir belgelenme görevi; keskin bir CI kontrolüdür ve ihlal edildiğinde sıfırdan farklı bir sonla sonuçlanır.

Bunun çalışma zamanında sadece doğrulama yapılmasından daha faydalı olmasının bir nedeni vardır: bir sözleşme ihlali üretime ulaştığında, maliyet zaten ortaya çıkmıştır. Sözleşmeyi ihlal eden kodun o dönemde birleştirilmesi mümkün değildir. Kayma gönderilmez.

Bir CI kapısı üç bileşenden oluşur:

1. Yetkili bir spesifikasyon dosyası (repo’ya bağlı, PR’lerde gözden geçirilmiş ve kod gibi muamele görmüştür).
2. Canlı istek ve yanıtları spesifikasyonla kontrol eden bir zamanlayıcı doğrulayıcı.
3. Uygulamanın gerçekten sunduğu rotaları, spesifikasyonun tanımladığı rotalara karşılaştıran ve uyuşmazlık durumunda inşaatı başarısız kılan bir kayma algılayıcı.
   Bunu kendiniz inşa edebilirsiniz. Ayrıca mevcut araçları da kullanabilirsiniz. Açıkçası, mevcut PHP seçeneklerini geliştirdim ve sürdürdüm çünkü ya her iki yönü de zorlayamadı, çok sayıda çerçeve desteklemiyordu ya da benimle birlikte kullanılması zor ve ağırdı.

Laravel’deki çalışan model

Bu araç zinciri accord olarak adlandırılmaktadır ve mevcut yollarınızdan bir OpenAPI spesifikasyonu düzenlemenize yardımcı olur:

• fissible/forge mevcut yollarınızdan bir OpenAPI taslağı oluşturur.
• fissible/accord çalışırken gerçek trafiği spesifikasyonla doğrular.
• fissible/drift yollar ve spesifikasyon arasında kaymayı algılar ve olay gerçekleştiğinde CI’yi başarısız kılar.
  Her bir parçanın bağımsız faydaları vardır ve CI/CD kapısında bir araya gelirler.

Adım 1: Boş bile olsa bir spesifikasyon alın

API’niz bir spesifikasyon olmadan çalışıyorsa, en ucuz ilk adım mevcut yollarınızdan birini oluşturmak olacaktır:

composer require --dev fissible/forge
php artisan accord:generate --title="Benim API"

forge kayıtlı yollarınızı gezinir, Laravel FormRequest sınıflarınızdan istek gövdesi şemalarını anlar ve her uç noktasını hesaba katarak resources/openapi/v1.yaml dosyasını yazar. Yanıt şemaları boş nesneler olarak düzenlenir ve bunlar, API’nizin gerçekten geri döndüğünü tanımlamak için doldurmanız gerekenlerdir.

FormRequest çıkarımı, forge’in vurgulamak istediğim tek parçasıdır. Laravel’in doğrulama kuralları zaten bir giriş sözleşmesinin açıklayıcı bir tarifidir, dolayısıyla bunları OpenAPI istek şemasına almak, çoğunlukla bir çeviri veya dönüşüm problemi değil, bir oluşturma problemidir. Eğer kod tabanınız FormRequest sınıflarını disiplinli bir şekilde kullanıyorsa, spesifikasyonun yarısı bedava geliyor.

Adım 2: Çalışma zamanı doğrulamasını kayıt modunda açın

accord’u kurun ve ara katmanları kaydedin:

composer require fissible/accord

// bootstrap/app.php (Laravel 11+)
use Fissible\Accord\Drivers\Laravel\Http\Middleware\ValidateApiContract;
->withMiddleware(function (Middleware $middleware) {
$middleware->appendToGroup('api', ValidateApiContract::class);
})

İlk olarak kayıt modunu yapılandırın:

ACCORD_FAILURE_MODE=log

Kayıt modu benimseme stratejisidir. Kayıt modundayken accord her isteği ve yanıtı doğrular ama ihlallerde atmak yerine PSR-3 uyarıları kaydeder ve isteği geçmesine izin verir. Uygulamanız çalışmaya devam eder, kayıtlarınız somut ihlallerle dolmaya başlar, ve açma kapanma moduna geçmeden önce spesifikasyonda veya kodda düzeltmeniz gereken bir listeye sahip olursunuz.

Bu mod olmadan, canlı bir API’de accord’u benimsemek “her şeyi durdur” projesidir. Bununla birlikte, benimseme “bir hafta çalıştır, karşılaştıklarını düzelt, sonra anahtarı açtır” olur.

Adım 3: CI kapısını ekleyin

Spesifikasyona güvendiğinizde, drift’in accord:validate komutunu CI’ye ekleyin:

- name: API sözleşmesini kontrol et (drift)
  run: php artisan accord:validate
- name: Uygulama kapsama alanını kontrol et
run: php artisan drift:coverage

accord:validate spesifikasyon ve uygulama arasında kayma varsa sıfırdan farklı bir sonuçla çıkar. drift:coverage ise, kod tabanında ancak hiçbir yere bağlı olmayan rotaları yakalayan isteğe bağlı bir ikinci kontroldür (iskele rotaları, gerçek üretim tehlikesi).

Bu kapı yerleştirildiğinde, rota değişikliği birleştirilmenin tek yolu, spesifikasyona eşleşecek şekilde güncellemektir. Spesifikasyon yalnızca bir belgelendirme nesnesi olmaktan çıkar ve diğer değişiklikler ile aynı gözden geçirme disiplini altında kod tabanının bir parçası olur.

Tekniğin altında ilginç olan nedir

accord’un çalışmasını sağlayan çoğu şey, gösterişli değildir: OpenAPI belgesini ayrıştırmak, bir rota araması oluşturmak, her isteği JSON şemaları hakkında bilgi sahibi bir doğrulayıcıdan geçirmek. Çekmek istediğim üç parça var.

PSR-7/15 temel çerçeve sürücüleri

Doğrulayıcı ve ara katman src/ içinde Laravel bağımlılığı yoktur, Slim bağımlılığı yoktur, Mezzio bağımlılığı yoktur. Çerçeve entegrasyonu tamamen src/Drivers/{Framework}/ içinde yaşar. Laravel sürücüsü ince bir hizmet sağlayıcı ve Laravel’in istek/yanıt nesnelerini PSR-7 mesajları haline dönüştüren bir ara katman içerir.

Sınır, mimari olarak zorlanır: src/Drivers/ dışındaki her şey çerçeveye özgü kodları içermeye izin verilmez. Yeni bir çerçeve sürücüsü eklemek, DriverInterface uygulamak ve bir yapıştırıcı ara katmanı yazmaktır. Bu sınırın temizliği, inşa edildiği gün önemli olmayabilir ama her gün sonrasında önemlidir.

FailureMode bir enum olarak, bir bayrak değil

Sözleşme ihlalleri için üç davranış istemiştim: atma, kaydetme veya bir kullanıcı tarafından sağlanan çağrılara geçirme. Naif yaklaşım, doğrulayıcı boyunca boole’ları ve özel ayar değerlerini geçirmektir. Dürüst bir yaklaşım, tek bir enum:

enum FailureMode: string
{
    case Exception = 'exception';
    case Log       = 'log';
    case Callable  = ;
}

Doğrulayıcı, değiştirilemez bir ValidationResult üretir:

final class ValidationResult
{
    private function __construct(
        public readonly bool $valid,
        public readonly string $version,
        public readonly array $errors = [],
    ) {}
<span class="k">public</span> <span class="k">static</span> <span class="k">function</span> <span class="n">valid</span><span class="p">(</span><span class="kt">string</span> <span class="nv">$version</span><span class="p">):</span> <span class="kt">self</span>    <span class="p">{</span> <span class="cm">/* ... */</span> <span class="p">}</span>
<span class="k">public</span> <span class="k">static</span> <span class="k">function</span> <span class="n">invalid</span><span class="p">(</span><span class="kt">array</span> <span class="nv">$errors</span><span class="p">,</span> <span class="kt">string</span> <span class="nv">$version</span><span class="p">):</span> <span class="kt">self</span> <span class="p">{</span> <span class="cm">/* ... */</span> <span class="p">}</span>
}
 

İhlal durumu, sonuçla ne yapılacağını belirler. Faydası, genişletmeye gittiğinizde ortaya çıkar: dördüncü bir davranış eklemek (örneğin, kuyruklu raporlama) yeni bir enum durumu ve yeni bir dal olsa gerektir, her yere yeni bir bayrak ve yeni bir koşul eklemek zorunda kalmazsınız.

Takılabilir spesifikasyon kaynakları

Bir spesifikasyon, yerel bir dosya olmak zorunda değildir. SpecSourceInterface soyutlaması, accord’un spesifikasyonları her yerden yüklemesine olanak tanır:

interface SpecSourceInterface
{
    public function load(string $version): ?OpenApi;
    public function exists(string $version): bool;
}

Varsayılan dosya kaynağı, diskteki YAML veya JSON’u yükler. URL kaynağı, isteğe bağlı PSR-16 önbellekleme ile uzaktan bir uç noktadan yükler, bu da birden fazla servis genel bir merkez spesifikasyonu doğrularken faydalıdır. Özel bir kaynak, bir veritabanından, bir kayıt defterinden veya çok kiracıli bir API’deki kiracıya özgü aramadan spesifikasyonları yüklemenizi sağlar. Arayüz isteyerek oldukça küçüktür: iki metod ve her yerden spesifikasyonlarla doğrulama yapabilirsiniz.

Bu, Fissible’ın daha geniş resminde nereye oturuyor

Bir Fissible adında bir şirket kurdum ve Station adında, kendime ait bir Laravel CMS ve workflow platformu üretiyorum. Station, modüllerin (CMS, Akış, Formlar, bir API modülü, daha fazlası yolda) yanaşmasına ve yetkilendirme, navigasyon, arama ve yönetim arayüzünü paylaşmasına olanak tanıyan bir Platform Çekirdeği ile birlikte gelir.

API modülü burada accord’un taşıyıcı olarak devreye girdiği yerdir. Station’ın API yüzeyi, baştan sona sözleşme ile doğrulanmıştır: forge, modüllerin sunduğu yollardan spesifikasyonu oluşturur, accord canlı trafiği doğrular, drift ise spesifikasyon ile uygulama arasında farklılaştığında CI’yi başarısız kılar. Sözleşmeyi kod olarak ele almak, Station’da bir ekibin politikası olarak kalmaz. Mekanik olarak uygulanır.

Bu modelin gerçek bir ürün üzerindeki end-to-end çalışmasını görmek istiyorsanız, Station iyi bir örnektir. Eğer kendi Laravel API’niz için yalnızca doğrulayıcı ve CI kapısını istiyorsanız, accord ve drift yüklemeniz gereken iki pakettir.

Kısa versiyonu

API sözleşmesi uyumu, bir belgelendirme probleminin çok daha ötesindedir. Bir kez sözleşme yazarsınız. Onu çalışma zamanında doğrularsınız. Kayma gerçekleştiğinde derlemeyi başarısız kılarsınız. Sonrasında, spesifikasyon dürüst hale gelir çünkü aksi takdirde derleme geçmez ve bir sözleşme ihlalinin maliyeti, “üretimde bulunması” sorunundan “onunla birlikte getirilen PR’de bulunmasına” düşer.

Bir ihlal ne kadar erken yakalanırsa, düzeltmesi de o kadar ucuz olur. Spesifikasyonu bir derleme kapısı olarak ele almak, yakalamayı varsayılan hale getirir.