Protokol öncelikli tasarım

Protokol-ilk nedir

Protokol-ilk, bileşenler (hizmetler, müşteriler, dış ortaklar) arasındaki bir etkileşim sözleşmesinin uygulanmadan önce tasarlandığı ve sabitlendiği bir yaklaşımdır. Kod, depolama, altyapı ve dokümantasyon sözleşmeye tabidir ve ondan otomatik olarak üretilir ve bunun tersi de geçerli değildir.

API'nin yalnızca kodun bir yan ürünü olduğu code-first'in aksine, Protocol-first protokolü birincil bir eser yapar: alan kavramlarına, veri modellerine, durumlara, hatalara, idempotency semantiğine, SLO/SLI'ye ve hatta sürüm politikasına sahiptir.

Neden buna ihtiyacın var?

Organizasyon genelinde arayüzlerin tutarlılığı ve öngörülebilirliği.
Hızlı giriş (SDK/kararlı/istemci otomatik oluşturma, düzgün hatalar ve kodlar).
Güvenilir evrim (şemaların uyumluluğu, test sözleşmeleri, açık sürüm politikası).
Ürün Odağı: Kod yazmadan önce davranış, SLA ve UX entegrasyonunu tartışın.
Otomasyon: CI/CD, tek bir doğruluk kaynağından eserler (istemciler, sunucu koçanları, doğrulayıcılar) toplar.
Güvenlik ve uyumluluk: haklar, PII maskeleme, saklama politikaları sözleşmede yer almaktadır.

Çekirdek yaklaşım

1. Tek Doğruluk Kaynağı (SSOT) - makine tarafından okunabilir özellikler:

REST: OpenAPI/JSON Şeması.
Etkinlikler ve akış: AsyncAPI, Avro/JSON Schema.
RPC: Protobuf (gRPC), Thrift, Smithy.
GraphQL: SDL + direktifleri/politikaları.
2. Uygulama öncesi düzenlemeler: etki alanı sözlüğü, hata kodları, idempotency semantiği, son tarihler, geri ödemeler, veri tekilleştirme.
3. Otomatik oluşturma: istemciler/sunucu saplamaları, türleri, SDK'lar, test sözleşmeleri, moks, Postman koleksiyonları, Terraform/OpenAPI Ağ Geçidi yapılandırması.
4. Yönetişim: Dizginler/politikalar (adlandırma, sayfalama, filtreler, hatalar), API loncası aracılığıyla inceleme, ana sürümler için değişim danışmanlığı.
5. Uyumluluk: "Yalnızca katkı maddesi" dağıtımlarının kesin olarak doğrulanması, semantik sürümler, kanarya/tüketici odaklı testler.
6. Sözleşme düzeyinde gözlemlenebilirlik: Korelasyon kimlikleri, hata modelleri, gecikme bütçeleri protokolde belirtilmiştir.

Süreç nasıl görünüyor (iskelet)

1. Başlatma: ürün özeti - kullanıcı yolculukları - API/Protokol PRD (kaynaklar/yöntemler/olaylar, SLA/SLO, hatalar, sınırlar).
2. Modelleme: Taslak spesifikasyon (OpenAPI/AsyncAPI/Proto) + veri şemaları, terimler sözlüğü.
3. Sözleşmeler ve UX entegrasyonları: yük örnekleri, hata sözleşmeleri, durum haritaları, sürüm kuralları.
4. İnceleme ve yönetişim: linters/standartlar, alan değişmezlerinin tartışılması, kilitlenme MGC (minimum garanti sözleşmesi).
5. Otomatik eser oluşturma: SDK'lar, saplamalar, test düzeltmeleri, altyapı taslakları (Ağ geçitleri, IAM kapsamları).
6. Uygulama ve Sözleşme Testleri: Tedarikçi ve tüketiciler CI'da uyumluluk kontrollerine tabi tutulur.
7. Gözlemlenebilirlik ve SLO: Korelasyon-id izleme, hata kataloğu, yeniden ödeme/zaman aşımı bütçeleri.
8. Salımlar ve evrim: ilk katkı maddesi, reddetme politikası, kanarya, A/B yetenek bayrakları.

Etkileşim protokolleri ve stilleri

REST/HTTP

Standartlar: kaynak modeli, 'GET/POST/PATCH/DELETE', sayfalama (imleç), filtreler, sıralama.
Alanlar ve şemalar: JSON Şeması, biçimler ('tarih-saat', 'uuid'), değişmezler (regex/enum/min-max).
Hatalar: tek biçim ('type', 'code', 'title', 'detail', 'trace _ id'), HTTP yığınlarına eşleme.
Değiştirme kontrolü: ETag/If-Match, POST için idempotent anahtarlar, açık semantik 409/422.

gRPC/RPC

Protobuf: kararlı etiket numaralandırma, 'isteğe bağlı', silinen alanların yeniden kullanılmasına izin vermiyor.
Sözleşmedeki son tarihler ve öncelikler; Kararlı durumlar (Tamam, INVALID_ARGUMENT, FAILED_PRECONDITION, vb.).
Akış: mesaj siparişi spesifikasyonu, geri basınç, son fragmanlar.

Olay odaklı (Kafka/NATS/SNS/SQS)

AsyncAPI: temalar/kanallar, bölümleme anahtarları, veri tekilleştirme anahtar kuralları, retentions, tam olarak bir kez anlambilim "vs'en az bir kez"

Çekirdek olay ve zenginleştirme: ayrı minimum yük ve uzantıları; Sürüm 'event _ type'/' schema _ version'.
Idempotency: 'event _ id', 'producer _ id', retrays ve veri tekilleştirme politikası.

GraphQL

Bir sözleşme olarak SDL, kullanımdan kaldırma direktifleri, derinlik ve karmaşıklık sınırları, hata kodları/uzantıları sözleşmesi.

Mimari ilkelerle entegrasyon

Ters Piramit/Kritik Yol İlk: şartnamede, MGC'yi vurgulayın (zorunlu minimum), uzantılar - '? include ='/yetenekleri.
Asfalt Yollar: bir dizi hazır spesifikasyon şablonu (ödeme, KYC, denetim, arama, dosyalar) + linters.
API Ağ Geçitleri ve Servis Ağı: sözleşmeye dayalı politikalar (oran limitleri, otomatik kapsamlar, yeniden denemeler, devre kesiciler).

Sürüm Oluşturma ve Evrim

• Minör = yalnızca eklemeli alanlar/kanallar.
• Major = değişiklikleri kırma (silme, yeniden adlandırma, semantiği değiştirme).
• Reddetme Politikası: destek pencereleri, 'Sunset' başlıkları, bildirim olayları.
• Tüketici Odaklı Sözleşmeler (CDC): Mevcut API'nin belirli tüketicileri tatmin ettiğini doğrulamak.
• Schema dizini: Geçmiş ve uyumluluk kurallarına sahip Schema Registry/Artifact Registry (GERI/İLERI/TAM).

Güvenlik ve uyumluluk

Sözleşmenin bir parçası olarak kimlik doğrulama/yetkilendirme (OAuth2/OIDC kapsamları, mTLS, JWT iddiaları).
PII/PCI: maskeleme, tokenizasyon formatları, özel depolama modlarına sahip alanlar/TTL.
Denetim ilkeleri: gerekli nitelikler ('actor', 'subject','action ',' occured _ at ',' trace _ id ').
Limitler: oran limiti başlıkları, kotalar, mesaj boyutları, son tarihler.

Sözleşme Gözlemlenebilirliği

Korelasyon/İstek-ID: şartnamede gereklidir.
Hata Kataloğu - çözülecek kodların ve SLA'ların sabit listesi.
SLI/SLO: p50/p95 gecikme, başarılı yanıtların oranı, uyumlu olayların oranı, idempotent tekrarlarının oranı.

Test ve kalite

Sözleşme testleri (sağlayıcı ↔ tüketici), CI'da şema diff, sahte sunucuların oluşturulması.
Altın örnekler: istek/yanıt referans örnekleri, e2e için demirbaşlar.
Kaos/gecikme enjeksiyonu: zaman aşımı/yeniden ödeme kontrolü, MGC'yi kaydederken uzantıların bozulması.

Örnek Alan Adı Şablonları

Ödeme (REST + Etkinlikleri)

'POST/payments' - '201 Created' with 'payment _ id', 'status = authorized'.
Olay 'ödeme. yetkilendirildi. v1 '(ядро):' {payment_id, tutar, para birimi, yöntem, occurred_at} '.
Uzatma 'ödemesi. zenginleştirilmiş. v1 ': risk oranı, coğrafi konum, cihaz-parmak izi.
Hatalar: '422' (doğrulama), '402' (ödeme gerekli), '409' (yinelenen).
SLA: 800ms p95 ≤ yetkilendirme; 2c lag p95 ≤ çekirdek olayı.

KYC (gRPC + kuyrukları)

RPC 'StartVerification (user_id)' - 'operation _ id'.
Konu 'kyc ilerleme olaylar. durum. v1 '(' PENDING '-' APPROVED/REJECTED ').
Sözleşme, PII alanları, raf ömrü, maskeleme, nedensel arıza kodlarını öngörmektedir.

Denetim (Yalnızca Etkinlik)

'audit. kaydedildi. v1 '(ядро):' actor ',' subject ',' action ',' occured _ at ',' trace _ id '.
Zenginleştirme: IP, cihaz, coğrafi - ayrı bir olay/iş parçacığı, çekirdeği engellemez.

Araçlar ve otomasyon (yaklaşık yığın)

Спеки: OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL.
Линтеры: Spektral, OpenAPI Diff, Buf (protobuf), Confluent SR uyumluluk kontrolleri.
Генерация: OpenAPI Jeneratör, Buf/İ, GraphQL Codegen, AsyncAPI Jeneratör.
Ağ Geçidi: Kong/Apigee/Azure/GCP GW, Elçi.
Тесты: Pact/CDC, Dredd, Schemathesis, Hoverfly, MockServer.
Register: Git-directory of schemes + Schema Registry/Artifact Registry.
Belgeler: Yeniden odaklama/Stoplight/Swagger-UI/GraphiQL/Explorer.

Anti-desenler

Kazayla ilk kod: "Kontrolörlerde ilk MVP", gerçek sonrası şartname, dokümantasyon ve davranış arasındaki tutarsızlık.
Swagger-wash: Gerçek kuralları olmayan resmi bir OpenAPI (hatalar, limitler, SLA'lar, sürümler).
Uyumluluk sonu: büyük sürüm olmadan kaldırılan alan/değiştirilen tür; Protobuf etiketlerini yeniden kullanma.
Sayfalama/filtreler olmadan "kalın" yanıt; idempotency eksikliği.
Sözleşme dışı güvenlik: Auth/Scopes wiki'de açıklanmıştır, ancak spesifikasyonda açıklanmamıştır.

Organizasyon süreci ile ilişkisi

API Guild: standartlar mütevelli, değişiklik incelemeleri, eğitim.
Tasarım Dokümanları: Her API için - PRD, ADR (çözümler), SLA, risk matrisi.
Değişim Yönetimi: RFC süreci, sürüm notları, geçiş kılavuzları, sapma-zaman çizelgesi.
Asfalt Yol ve Şablonlar: Spesifikasyondan servis çerçevesi jeneratörleri (işleyici iskeleti, doğrulama, günlük kaydı).

Kontrol listeleri

Başlamadan önce

• Bir PRD ve bir domain sözlüğü vardır.
• Seçilen stil (REST/gRPC/Event/GraphQL) ve şema biçimi.
• MGC'ler, hatalar, SLA/SLO'lar, idempotency kuralları tanımlanmıştır.

Geliştirme aşamasında

• Spesifikasyon, linterleri ve incelemeyi geçer.
• SDK/Kararlı/Fikstür otomatik üretimi yapılandırılmıştır.
• Sözleşme testleri (CDC) CI'ye dahildir; schema-diff blokları uyumsuz değişiklikler.

Yayınlanmadan Önce

• Örnekler ve hata kodları ile entegratör belgeleri.
• Sözleşmeli olarak gözlemlenebilir: Korelasyon-id, hata kataloğu, SLI panoları.
• Sürüm politikası ve kullanımdan kaldırma ilan edilir.

SSS

Protocol-first ile API-first arasındaki fark nedir?
Genellikle terimler birbirinin yerine kullanılır. Protokol-first altındaki bu makalede, sözleşmenin titizliğini ve SLA, güvenlik ve gözlemlenebilirlik dahil olmak üzere tüm stillerin (REST/RPC/Events/GraphQL) kapsamını vurguluyoruz.

Bu gelişme yavaşlar mı?
Başlangıç biraz daha uzun olabilir, ancak o zaman entegrasyonlar, istikrar ve paralel geliştirme hızları (otomatik nesil, kararlı SDK'lar) kazanırız.

Hızlı deneylerle ne yapmalı?
Şemaların "taslak" sürümlerini (taslak), özellik bayraklarını ve sanal alanları kullanın, ancak satırları ve temel uyumluluk kurallarını atlamayın.

Toplam

Protokol öncelikli tasarım, sözleşmeyi mimarlığın merkezi yapar: davranışı koordine eder, şemaları düzeltir, üretimi ve testleri otomatikleştirir, ek olarak gelişir. Sonuç olarak, öngörülebilir entegrasyonlar, yüksek gelişme hızı ve sistemlerin ölçek ve komuta değişikliklerine karşı direnci elde ediyoruz.