Bruno API Koleksiyonlarını Git'te Tutmak: Bedava Postman Değil, Bir İş Akışı Değişikliği

API koleksiyonunuz bir bulut sağlayıcıda ya da tek bir mühendisin laptopunda yaşarken, o uç noktalara hizmet veren kod git’te yaşıyor. Bir uç nokta zorunlu bir header eklediği veya bir alanı yeniden adlandırdığı anda ikisi birbirinden uzaklaşır: kod değişikliği bir pull request ile gider, ama kaydedilmiş istek geride kalır ve koleksiyonu sonradan açan kişi, artık gerçeğe uymayan bir isteği debug eder. Çözüm, istek koleksiyonunuzu kodun yanında düz metin dosyaları olarak commit etmektir; böylece API sözleşmesi, kullandığı handler ile aynı pull request, aynı inceleme ve aynı geçmişten geçer. Buradaki araç Bruno, ama asıl mesele onu hangi istemcinin gösterdiğinden çok sözleşmenin nerede yaşadığı; secret’lar etrafında net bir sınır ve bulut iş birliğinin hâlâ kazandığı birkaç durum var.

Bir istemciyi, denk geldiği için bedava olan bir başkasıyla değiştirmek yalnızca araç faturanızı değiştirir; koleksiyonu commit etmek ise iş akışını değiştirir.

Diff’teki Bru Dosyaları#

Bruno her isteği, repo’ya commit ettiğiniz bir koleksiyon klasörü içinde düz metin dosyası olarak saklar. Format “Bru” adında, düz metin dosyaları üzerine kurulu basit bir işaretleme dilidir; JSON yerine küçük bir DSL’dir ve diff’lerin bir pull request içinde temiz okunmasını sağlayan da budur. Asgari bir istek şöyle görünür:

meta {
  name: Get user
  type: http
  seq: 1
}

get {
  url: {{baseUrl}}/users/42
  body: none
  auth: bearer
}

headers {
  Accept: application/json
}

auth:bearer {
  token: {{authToken}}
}

assert {
  res.status: eq 200
  res.body.id: eq 42
}

/users/42 uç noktası yeni bir Accept değeri istemeye başladığında ya da yanıt, bir assertion’ın kontrol etmesi gereken bir alan kazandığında, bu dosyayı handler ile aynı commit içinde düzenlersiniz. İnceleyen kişi her iki diff’i yan yana görür: bir tarafta handler değişikliği, diğer tarafta istek değişikliği.

Bunu bulut tabanlı bir koleksiyonla kıyaslayın. Handler düzenlemesi git’te, istek düzenlemesi sağlayıcının uygulamasında yaşar. Bu iki sistem ve iki zaman çizelgesidir; drift varsayılan davranıştır. Bruno’nun kendi anlatımı da bununla birebir örtüşür: kendisini “Git-native API istemcisi” olarak, “kod olarak saklanan koleksiyonlar” ile konumlandırır ve “Yalnızca Yerel” olduğunu, bulut senkronizasyonu olmadığını açıkça söyler; yani veriniz repo’da kalır. İş birliği pull request’ler üzerinden olur, çünkü insan tarafından okunabilen dosya formatı değişikliği okunabilir kılar.

Araç hızla evrildiği için formatla ilgili bir not. Bruno .bru’yu hâlâ tam olarak destekliyor, ama yeni koleksiyonlar için artık kendi yazdığı açık bir spesifikasyon olan OpenCollection YAML’ı öneriyor. Argüman dosya uzantısına bağlı değil. Her iki format da düz metindir, ikisi de repo’da yaşar ve ikisi de bir pull request üzerinden incelenir. Mevcut koleksiyonlarınız .bru kullanıyorsa onunla devam edin; sıfırdan bir koleksiyonda OpenCollection YAML’a uzanın.

Secret Sınırı#

Aslında her şeyi commit etmezsiniz. İsteğin şekli git’e girer; secret değerler girmez. Bruno’nun dokümanları bu konuda açıktır: koleksiyonu git’e ister check-in edin ister export edin, “paylaşılmadan önce secret’ların koleksiyondan ayıklandığından emin olmak isteriz” der.

En temiz varsayılan, secret değişkenidir. Bir ortamda, bir değişkenin secret kutucuğunu işaretlersiniz. Bruno o zaman o değeri içeride yönetir ve ortam dosyasına asla yazmaz; dosyaya yalnızca değişkenin adı işlenir. Git’e düşen şey addan ibarettir:

vars:secret [
  baseUrl
]

Değer yerel makinenizde yaşar; mümkün olduğunda OS düzeyinde şifreleme ile, o yoksa AES256’ya düşerek şifrelenir. Bruno ayrıca bir koleksiyonu export ettiğinizde secret değişkenleri ayıklar.

İkinci yol, çoğu backend mühendisinin zaten bildiği yoldur: koleksiyon klasörünün kökünde bir .env dosyası, Bruno içinde process.env üzerinden okunur. Belgelenmiş klasör yapısı, .env’in yanında bir .gitignore ile gelir; yani desen tanıdık olandır. .env git’ten dışlanmış kalır, istek dosyaları ile bruno.json ise commit edilir. Uygulamanız secret’ları zaten bu şekilde yönetiyorsa, koleksiyon da aynı kurala uyar ve yeni bir takım arkadaşı tek bir yerel dosyayı doldurur. Kurumsal ölçek için Bruno’nun Ultimate katmanı HashiCorp Vault, AWS Secrets Manager ve Azure Key Vault ile entegre olur; böylece değerler diske dokunmadan bir vault’tan çözülür. Bu, varsayılan yolun dışındaki ücretli seçenektir ve çoğu takımın asla ihtiyacı olmaz.

Takımlar bu disiplini atladığında iki hata kalıbı ortaya çıkar. vars:secret yerine düz bir vars bloğuna yapıştırılan gerçek bir token herkese açık bir repo’ya push edilir; değer geçmişe düşer ve orada kalır. secret kutucuğunu işaretleyin ki değer dosyaya hiç ulaşmasın, ya da onu git’ten dışlanmış .env’e taşıyın. Daha sinsi olanı, koleksiyonu ara sıra yeniden ürettiğiniz bir export gibi görmek. Export edilip commit edilmiş bir JSON dökümü er geç drift demektir, çünkü kimse onu handler ile aynı PR içinde düzenlemez. İstek dosyası bir kaynak dosyasıdır ve kodla birlikte elle düzenlenir. Sınırı koleksiyonun README’sinde belgeleyin ki sonraki takım arkadaşı yerelde hangi dosyayı dolduracağını ve hangisine asla dokunmayacağını bilsin.

Bulut Çalışma Alanının Üstün Geldiği Durumlar#

Giriş bedeli git’e hakimiyettir. Teknik olmayan bir QA testçisine ya da tıkla-çalıştır türünde paylaşılan bir çalışma alanına ihtiyaç duyan bir paydaşa, bir bulut aracı gerçekten daha iyi hizmet eder; isteklerinizi çalıştıranların kayda değer bir kısmı git bilmiyorsa, düz metin modeli sürtünmeyi azaltmak yerine artırır. Ortak bir repo paylaşmayan takımlar arasındaki paylaşım da aynı yapıdadır. “Repo’muzu klonla” tek bir kod tabanı içinde gayet iyi bir onboarding adımıdır; ortak repo’nun olmadığı bir organizasyonda keşif mekanizması olarak dağılır ve orada organizasyon çapında aramaya sahip bir bulut çalışma alanı kazanır.

Diğer sınır yetenek tarafındadır. Yerel öncelikli bir düz metin istemcisi mock sunucu, monitor, zamanlanmış sağlık kontrolü, barındırılan dashboard ve performans veya yük testi sunmaz. Bruno açıkça yalnızca yereldir ve bulut senkronizasyonu yoktur; bunlar için bir bulut platformunda kalır ya da ayrı araçlar eklersiniz. Örneğin Postman, mock sunucuları, monitor’leri ve performans testini bulut özellikleri olarak sunar.

Postman hesap merkezli ve varsayılan olarak bulut-senkronludur: koleksiyonlar bir Postman hesabı ve çalışma alanında yaşar ve bilinçli olarak engellemediğiniz sürece buluta senkronize olur. Bruno’nun yerel öncelikli modeli ise onları kodun yanında, repo’nuzda tutar.

İlk Push’tan Önce#

İsteği çalıştıran kişilerin zaten git içinde yaşadığı bir mühendislik takımında düz metin koleksiyon varsayılandır; onu kod tabanının bir parçası gibi ele alın. Bu varsayım bozulduğunda yukarıdaki diyagram sizi bulut çalışma alanına geri gönderir. İş akışının talep ettiği tek disiplin parçası secret sınırıdır; ilk push’tan önce secret değişken kutucuğunu ya da git’ten dışlanmış bir .env’i kurun ve her takım arkadaşının yerelde hangi dosyayı dolduracağını belgeleyin.

Kaynaklar#

• Bru Markup Language - Bruno Docs (yeni sekmede açılır) - .bru’nun versiyon kontrollü koleksiyonlar için düz metin bir DSL olduğunu doğrular; OpenCollection YAML’ın artık yeni koleksiyonlar için önerilen format olduğunu belirtir.
• OpenCollection YAML - Bruno Docs (yeni sekmede açılır) - Bruno’nun artık yeni koleksiyonlar için önerdiği YAML spesifikasyonu; format değişikliği uyarısıyla ilgilidir.
• Secret Management overview - Bruno Docs (yeni sekmede açılır) - Secret’ların check-in veya export öncesi ayıklanması gerektiğini belirtir; üç secret yaklaşımını sıralar.
• Secret Variables - Bruno Docs (yeni sekmede açılır) - secret kutucuğu; değerler ortam dosyasına yazılmaz (vars:secret [...]), OS şifrelemesi veya AES256 ile saklanır. Commit etmesi güvenli varsayılan desen.
• DotEnv File - Bruno Docs (yeni sekmede açılır) - Koleksiyon kökünde bir .env artı .gitignore, process.env üzerinden erişilir; tanıdık backend deseni.
• Secret Managers overview - Bruno Docs (yeni sekmede açılır) - HashiCorp Vault, AWS Secrets Manager ve Azure Key Vault entegrasyonu, Bruno Ultimate’a kilitli.
• Bruno (GitHub deposu) (yeni sekmede açılır) - CI için @usebruno/cli ve bru run, ve ayrı bir “Bru” dili gösteren dil dağılımı.
• Bruno LICENSE (yeni sekmede açılır) - MIT Lisansı, Copyright (c) 2022 Anoop M D, Anusree P S and Contributors. Çekirdeğin MIT olduğunu, source-available veya ticari olmadığını doğrular.
• Bruno en son sürüm (GitHub) (yeni sekmede açılır) - En son yayınlanan sürüm etiketi ve değişiklik günlüğü.
• Bruno Fiyatlandırma (yeni sekmede açılır) - Kullanıcı başına aylık Open Source, Pro ve Ultimate katmanları, yıllık faturalandırılır. Git-içinde-repo iş akışı yalnızca ücretsiz çekirdeğe ihtiyaç duyar.
• Bruno ana sayfası (yeni sekmede açılır) - “Git-native API istemcisi,” “Yalnızca Yerel,” “Kod olarak saklanan koleksiyonlar.” Bruno’nun kendi konumlandırmasının birincil kaynağı.
• About Postman accounts - Postman Docs (yeni sekmede açılır) - Postman’in hesap merkezli, varsayılan bulut-senkronlu modeli; kontrast noktası.
• Install Postman - Postman Docs (yeni sekmede açılır) - Web’e karşı masaüstü özellik ayrımı; yalnızca-bulut özellikleri noktasını destekler (mock sunucular, monitor’ler, performans testi).