Tarayıcıdan bir gRPC hizmetini çağırmayı denediyseniz, zorluklarını zaten biliyorsunuzdur. Tarayıcılar, HTTP kuyruklarını kontrol edemedikleri için ham gRPC ile konuşamazlar, bu nedenle trafiği çevirmek için Envoy gibi bir proxy eklemek zorunda kalırsınız. ConnectRPC bu adımı ortadan kaldırır. Tarayıcının doğrudan çağırabileceği, düz bir curl komutuna yanıt veren ve daha geniş gRPC ekosistemiyle hala birlikte çalışabilen Protobuf tabanlı API'ler oluşturmanızı sağlar.
Bu kılavuz, ConnectRPC'nin ne olduğunu, Connect protokolünün çözdüğü sorunu, Connect'in gRPC, gRPC-Web ve REST ile nasıl karşılaştırıldığını ve bir Connect isteğinin HTTP üzerinden nasıl göründüğünü açıklar. Ayrıca Connect ve gRPC uç noktalarını standart bir API istemcisiyle nasıl test edeceğinizi ve hata ayıklayacağınızı da göreceksiniz.
ConnectRPC Nedir
ConnectRPC, Protocol Buffers'tan tarayıcı uyumlu ve gRPC uyumlu HTTP API'leri oluşturmaya yönelik bir kütüphane ailesidir. Hizmetinizi bir .proto dosyasında tanımlar, kod üretir ve işleyicilerinizi uygularsınız. Connect, yönlendirme, serileştirme, sıkıştırma ve istemci oluşturma işlerini üstlenir.
Proje, Protobuf için buf derleme araçlarının arkasındaki şirket olan Buf tarafından oluşturuldu ve şu anda bir Cloud Native Computing Foundation (CNCF) sandbox projesidir. Bu miras önemlidir: Connect, ekiplerin buf ve Protobuf ile zaten kullandığı şema-öncelikli iş akışına uyacak şekilde tasarlanmıştır.
Bir ConnectRPC sunucusu aynı anda üç protokolü destekler:
- gRPC: akış ve kuyruklar dahil tam uyumluluk.
- gRPC-Web: ayrı bir proxy'ye gerek kalmadan doğrudan destek.
- Connect: web için ayarlanmış kendi HTTP tabanlı protokolü.
Tek bir sunucu üçünü de konuştuğu için, bir gRPC istemcisi bir Connect sunucusunu çağırabilir ve bir Connect istemcisi herhangi bir gRPC sunucusunu çağırabilir. Protokolü istemci başına seçersiniz, genellikle tek bir yapılandırma değişikliğiyle ve kod yeniden yazmaya gerek kalmadan.
Connect'in Çözdüğü Sorun
gRPC hızlı ve güçlü bir şekilde tipolojiktir, ancak web'in kabul etmediği varsayımlar yapar. Durum bilgilerini taşımak için HTTP/2'ye ve HTTP kuyruklarına güvenir. Tarayıcılar kuyrukları JavaScript'e göstermez, bu nedenle bir tarayıcı yerel bir gRPC istemcisi olarak hareket edemez. Olağan geçici çözüm, tarayıcı ile gRPC arka ucunuz arasında oturan Envoy gibi bir çeviri proxy'si artı gRPC-Web'dir.
Bu işe yarar, ancak hareketli parçalar ekler. Artık bir proxy'yi çalıştırır ve yapılandırırsınız ve fazladan bir atlama noktasında hata ayıklarsınız. Bu ek yük olmadan tipolojili API'ler ve tarayıcı erişimi isteyen ekipler için kurulum, olması gerekenden daha ağır hissettirir.
Connect farklı bir yol izler. Kendi protokolü standart HTTP üzerinden çalışır, bu nedenle bir tarayıcı doğrudan çağırabilir ve tarayıcı trafiği için bir proxy'ye ihtiyacınız olmaz. Mevcut gRPC istemcilerine de hizmet vermeniz gerekiyorsa, aynı Connect sunucusu onları da yönetir. Tarayıcılara, komut satırı araçlarına ve gRPC hizmetlerine yanıt veren tek bir arka ucunuz olur.
Connect ve gRPC, gRPC-Web ve REST Karşılaştırması
Bu dört yaklaşım birbiriyle örtüşür, bu yüzden onları sıralamak faydalıdır.
gRPC, Protobuf'u HTTP/2 üzerinden ikili çerçeveleme ve kuyruklarla kullanır. Verimlidir ve dört akış modunun tümünü destekler, ancak bir tarayıcıdan veya bir kabuktan çağırmak zordur. Aktarım katmanını tekrar gözden geçirmek isterseniz, gRPC ve HTTP/2'nin birlikte nasıl çalıştığını inceleyebilirsiniz.
gRPC-Web, gRPC'nin tarayıcı dostu bir varyantıdır. Hala Protobuf'a odaklanır ve genellikle gerçek bir gRPC arka ucuna köprü kurmak için bir proxy'ye ihtiyaç duyar. gRPC-Web'in ne olduğuna dair kılavuzumuz, nereye oturduğunu anlatır.
Connect, Protobuf şemasını ve gRPC tarzı yöntem modelini korur, ancak protokolü HTTP/1.1, HTTP/2 ve HTTP/3 üzerinden sorunsuz bir şekilde çalışır. Tekli çağrılar, gRPC ikili çerçeveleme olmadan düz bir JSON veya Protobuf gövdesi taşır ve yanıtlar gerçek HTTP durum kodlarını kullanır. Bu kombinasyon, bir Connect çağrısını herhangi bir REST çağrısı kadar kolay erişilebilir kılar.
REST kaynak odaklıdır ve şema isteğe bağlıdır. En evrensel olarak desteklenen stildir, ancak Protobuf'un size sunduğu kod oluşturma ve katı tiplendirme özelliklerinden yoksundur. Karşılaştırmaları tartıyorsanız, gRPC vs REST farklılıkları ayrıntılı olarak açıklar.
Kısa versiyon: Connect, gRPC'nin tiplendirme ve araçlarını REST'in erişim ve hata ayıklanabilirliğiyle birleştirmeyi amaçlar. Tarayıcıların ve kabukların kaldıramadığı kısımları düşürürken Protobuf ve gRPC'nin yöntem modeline dayanır.
HTTP Üzerinden Bir Connect İsteği
Connect'i erişilebilir kılan şey budur. Tekli bir Connect çağrısı, sıradan bir HTTP POST isteğidir. URL yolu doğrudan Protobuf şemanızdan gelir ve gövde, fazladan çerçeveleme olmaksızın JSON veya ikili Protobuf'tur.
Yol formatı /<package>.<Service>/<Method> şeklindedir. Yani, greet.v1 paketindeki bir GreetService üzerindeki Greet metodu /greet.v1.GreetService/Greet adresinde bulunur.
Bunu curl ile çağırabilirsiniz:
curl \
--header "Content-Type: application/json" \
--data '{"name": "Jane"}' \
http://localhost:8080/greet.v1.GreetService/Greet
Yanıt düz JSON'dur:
{"greeting": "Hello, Jane!"}
Özel istemci yok, proxy yok, ikili kod çözme yok. İşte tüm istek bu. Gövde gerçek JSON olduğu ve durum gerçek bir HTTP durum kodu olduğu için, HTTP konuşan her araç çağrıyı inceleyebilir. Bu, Connect protokolünü ham gRPC'den ayıran özelliktir; ham gRPC'de aynı istek ikili çerçeveleme içine sarılır ve durumunu bir kuyrukta taşır.
Connect, tekli istekler için iki içerik türünü destekler:
- İnsan tarafından okunabilir JSON yükleri için
application/json. - Kompakt ikili Protobuf için
application/proto.
Daha küçük ağ boyutu istediğinizde ikili Protobuf gönderirsiniz, geliştirme sırasında okunabilirlik istediğinizde ise JSON. İkili göndermek için başlığı değiştirin ve kodlanmış bir gövde geçirin:
curl \
--header "Content-Type: application/proto" \
--data-binary @request.bin \
http://localhost:8080/greet.v1.GreetService/Greet
Akış çağrıları farklı bir içerik türü (application/connect+proto veya application/connect+json) kullanır ve her mesajı bir zarfa sarar: bir bayrak baytı, dört baytlık büyük endian uzunluk ve ardından mesaj. Tekli çağrılar bu zarfı tamamen atlar, bu nedenle normal bir HTTP isteğine bu kadar temiz bir şekilde eşlenirler. Yükleriniz için kablo formatları arasında seçim yapıyorsanız, Protobuf vs JSON boyut ve okunabilirlik ödünlerini kapsar.
Dil Desteği ve buf Araçları
ConnectRPC, çeşitli dillerde uygulamalar sunar. Go ve TypeScript (hem tarayıcı hem de Node.js için) kararlı ve üretim için hazır durumdadır. Apple platformları için Swift, JVM ve Android için Kotlin ve beta sürümünde Python mevcuttur. Bu yaygınlık, istemcileri el yazısıyla yazmak zorunda kalmadan bir Go arka ucu ve bir TypeScript ön ucu arasında aynı Protobuf sözleşmesini paylaşmanızı sağlar.
Kod oluşturma buf araç zinciri aracılığıyla çalışır. Hizmetinizi bir .proto dosyasında açıklarsınız, ardından mesajları ve Connect işleyicilerini oluşturmak için buf eklentilerini kullanırsınız. Bir Go projesi iki eklenti kullanır: Protobuf mesajları için protoc-gen-go ve Connect işleyicileri ve istemcileri için protoc-gen-connect-go.
Eklentiler bir buf.gen.yaml dosyasında listelenir ve oluşturma işlemini tek bir komutla çalıştırırsınız:
buf generate
Bu, hizmetiniz için tipolojili mesaj yapıları ile sunucu ve istemci kodunu üretir. Oradan işleyici metodlarını uygular ve bunları bir HTTP sunucusuna kaydedersiniz. Oluşturulan kod, Go'daki standart kütüphane net/http'i hedeflediği için, ayrı bir sunucu çalışma zamanı çekmezsiniz; bir Connect işleyicisi, mevcut rotalarınızla birlikte bağlayabileceğiniz normal bir HTTP işleyicisidir.
Connect ve gRPC Uç Noktalarını Test Etme ve Hata Ayıklama
Connect tekli çağrıları, JSON gövdeli düz HTTP olduğu için, bunları herhangi bir REST uç noktasını test ettiğiniz şekilde test edebilirsiniz. Bu pratik bir kazanımdır: geliştirme sırasında hizmetinizi kurcalamak için özel bir istemciye gerek yoktur.
Apidog'da, bir Connect tekli isteğini bir HTTP isteği olarak gönderirsiniz. Metodu POST olarak ayarlayın, http://localhost:8080/greet.v1.GreetService/Greet gibi şema tabanlı URL'yi kullanın, Content-Type: application/json başlığını ekleyin ve mesajınızı JSON gövdesine yerleştirin:
{"name": "Jane"}
JSON yanıtını ve doğrudan doğrulayabileceğiniz gerçek bir HTTP durum kodunu geri alırsınız. Apidog özel bir Connect istemcisi değildir, ancak buna ihtiyacı da yoktur; Connect protokolünün ortaya çıkardığı HTTP yüzeyini, tam olarak curl gibi, bir UI, kaydedilmiş istekler ve geçmişle birlikte kullanıyorsunuz. İlgili fiiller hakkında hızlı bir başlangıç için, HTTP metotlarının neler olduğuna bakabilirsiniz.
Bir Connect sunucusu aynı zamanda gRPC ile de konuştuğu için, hizmetinizin gRPC tarafı da test edilebilir. Apidog gRPC uç noktalarını destekler, böylece aynı .proto dosyasını içe aktarabilir, hizmet metotlarını gezinebilir ve tipolojili bir istek ile çağırabilirsiniz. Bu, tek bir aracın sunucunun her iki yüzünü de kapsadığı anlamına gelir: HTTP dostu Connect protokolü ve yerel gRPC protokolü. gRPC ana endişenizse, gRPC API'leri verimli bir şekilde nasıl test edeceğiniz iş akışını adım adım açıklar.
İstekleriniz beklediğiniz gibi davrandığında, bunları otomatik kontrollere taşıyabilirsiniz. Connect ve gRPC çağrılarınızı test senaryoları olarak kaydedin, ardından Apidog CLI ile CI'da çalıştırın. Node ile yükleyin:
npm install -g apidog-cli
Ardından kaydedilmiş bir senaryo veya paketi çalıştırın, bir ortama işaret edin ve rapor formatlarını seçin:
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t <scenarioOrSuiteId> \
-e <environmentId> \
-r cli,html,junit
CLI başsızdır, bu nedenle Node çalıştırabilen herhangi bir CI adımına düşebilir. Anlık istekler göndermek yerine kaydedilmiş test senaryolarını ve paketlerini çalıştırır, bu da Connect ve gRPC uç noktalarınızdaki regresyon kontrolleri için uygun hale getirir. Tam bir kılavuz için, komut satırından API test etmeye yönelik Apidog CLI eğitimine bakın.
Sıkça Sorulan Sorular
ConnectRPC, gRPC ile aynı mı? Hayır. ConnectRPC, üç protokolü uygulayan bir çerçevedir: gRPC, gRPC-Web ve kendi Connect protokolü. Bir Connect sunucusu gRPC istemcileri ve sunucuları ile birlikte çalışır, bu nedenle gRPC ekosistemine uyar, ancak Connect protokolünün kendisi, tarayıcıların ve kabukların doğrudan çağırabileceği ayrı bir HTTP tabanlı tasarımdır.
Bir tarayıcıya ulaşmak için hala Envoy gibi bir proxy'ye ihtiyacım var mı? Connect protokolü için hayır. Connect standart HTTP üzerinden çalıştığı için, bir tarayıcı çeviri proxy'si olmadan bir Connect sunucusunu çağırabilir. Envoy gibi bir proxy'ye yalnızca tarayıcı trafiğini yerel gRPC'den başka bir şey konuşmayan bir arka uca köprü kurmanız gerektiğinde başvurursunuz.
ConnectRPC hangi dilleri destekliyor? Go ve TypeScript (tarayıcı ve Node.js) kararlı, üretim için hazır uygulamalardır. Swift, Kotlin ve Python da mevcuttur, Python beta sürümündedir. Hepsi aynı Protobuf şemasından üretilir.
Connect ve buf arasındaki ilişki nedir? ConnectRPC, Buf tarafından oluşturuldu ve kod üretimi için buf araç zincirini kullanır. .proto dosyalarınızdan işleyiciler ve istemciler üretmek için protoc-gen-connect-go gibi eklentilerle buf generate komutunu çalıştırırsınız.
Bir Connect uç noktasını normal bir API istemcisiyle test edebilir miyim? Evet. Connect tekli çağrıları, JSON veya Protobuf gövdeli ve gerçek bir HTTP durum kodlu HTTP POST istekleridir. curl ve Apidog dahil olmak üzere herhangi bir HTTP istemcisi bunu gönderebilir. Apidog, .proto dosyasını içe aktararak aynı sunucunun gRPC tarafını da çağırabilir.