Jika Anda pernah mencoba memanggil layanan gRPC dari peramban, Anda sudah tahu hambatannya. Peramban tidak dapat berbicara gRPC mentah karena tidak dapat mengontrol trailer HTTP, sehingga Anda akhirnya memasang proxy seperti Envoy hanya untuk menerjemahkan lalu lintas. ConnectRPC menghilangkan langkah itu. Ini memungkinkan Anda membangun API berbasis Protobuf yang dapat dipanggil langsung oleh peramban, yang merespons perintah curl biasa, dan yang masih berinteroperasi dengan ekosistem gRPC yang lebih luas.
Panduan ini menjelaskan apa itu ConnectRPC, masalah yang dipecahkan oleh protokol Connect, bagaimana Connect dibandingkan dengan gRPC, gRPC-Web, dan REST, serta bagaimana tampilan permintaan Connect melalui HTTP. Anda juga akan melihat cara menguji dan men-debug endpoint Connect dan gRPC dengan klien API standar.
Apa Itu ConnectRPC
ConnectRPC adalah keluarga pustaka untuk membangun API HTTP yang kompatibel dengan peramban dan gRPC dari Protocol Buffers. Anda menentukan layanan Anda dalam berkas .proto, menghasilkan kode, dan mengimplementasikan penangan Anda. Connect menangani perutean, serialisasi, kompresi, dan pembuatan klien.
Proyek ini dibuat oleh Buf, perusahaan di balik perkakas pembangunan buf untuk Protobuf, dan sekarang menjadi proyek kotak pasir Cloud Native Computing Foundation (CNCF). Silsilah itu penting: Connect dirancang agar sesuai dengan alur kerja 'schema-first' yang sama yang sudah digunakan tim dengan buf dan Protobuf.
Server ConnectRPC mendukung tiga protokol sekaligus:
- gRPC: kompatibilitas penuh, termasuk streaming dan trailer.
- gRPC-Web: dukungan langsung, tanpa proxy terpisah yang diperlukan.
- Connect: protokol berbasis HTTP-nya sendiri, disetel untuk web.
Karena satu server dapat berbicara ketiganya, klien gRPC dapat memanggil server Connect, dan klien Connect dapat memanggil server gRPC apa pun. Anda memilih protokol per klien, seringkali hanya dengan satu perubahan konfigurasi dan tanpa penulisan ulang kode.
Masalah yang Dipecahkan Connect
gRPC cepat dan memiliki tipe yang kuat, tetapi membuat asumsi yang tidak dihormati oleh web. Ini mengandalkan HTTP/2 dan trailer HTTP untuk membawa informasi status. Peramban tidak mengekspos trailer ke JavaScript, sehingga peramban tidak dapat bertindak sebagai klien gRPC asli. Solusi umum adalah gRPC-Web ditambah proxy penerjemah seperti Envoy yang berada di antara peramban dan backend gRPC Anda.
Itu berfungsi, tetapi menambahkan bagian yang bergerak. Anda sekarang menjalankan dan mengonfigurasi proxy, dan Anda men-debug satu lompatan ekstra. Bagi tim yang menginginkan API bertipe dan akses peramban tanpa overhead tersebut, pengaturannya terasa lebih berat dari yang seharusnya.
Connect mengambil jalur yang berbeda. Protokolnya sendiri berjalan di atas HTTP standar, sehingga peramban dapat memanggilnya secara langsung dan Anda tidak memerlukan proxy untuk lalu lintas peramban. Jika Anda juga perlu melayani klien gRPC yang sudah ada, server Connect yang sama juga menanganinya. Anda mendapatkan satu backend yang melayani peramban, perkakas baris perintah, dan layanan gRPC secara setara.
Connect vs gRPC vs gRPC-Web vs REST
Keempat pendekatan ini tumpang tindih, jadi ada baiknya untuk menyelaraskannya.
gRPC menggunakan Protobuf melalui HTTP/2 dengan pembingkaian biner dan trailer. Ini efisien dan mendukung keempat mode streaming, tetapi canggung untuk dipanggil dari peramban atau dengan shell. Jika Anda ingin menyegarkan kembali pengetahuan tentang lapisan transport, lihat bagaimana gRPC dan HTTP/2 bekerja sama.
gRPC-Web adalah varian gRPC yang ramah peramban. Ini masih berpusat pada Protobuf dan biasanya membutuhkan proxy untuk menjembatani ke backend gRPC yang sesungguhnya. Panduan kami tentang apa itu gRPC-Web membahas posisinya.
Connect mempertahankan skema Protobuf dan model metode bergaya gRPC, tetapi protokolnya berjalan dengan bersih di atas HTTP/1.1, HTTP/2, dan HTTP/3. Panggilan unary membawa badan JSON atau Protobuf biasa tanpa pembingkaian biner gRPC, dan respons menggunakan kode status HTTP yang sesungguhnya. Kombinasi itulah yang membuat panggilan Connect semudah panggilan REST mana pun.
REST berorientasi sumber daya dan opsional skema. Ini adalah gaya yang paling didukung secara universal, tetapi ia tidak memiliki pembangkitan kode dan pengetikan ketat yang diberikan Protobuf kepada Anda. Jika Anda sedang mempertimbangkan komprominya, gRPC vs REST menguraikan perbedaannya.
Singkatnya: Connect bertujuan untuk memberi Anda pengetikan dan perkakas gRPC dengan jangkauan dan kemampuan debug REST. Ini bersandar pada Protobuf dan model metode gRPC sambil menghilangkan bagian-bagian yang tidak dapat ditangani oleh peramban dan shell.
Permintaan Connect Melalui HTTP
Inilah yang membuat Connect mudah didekati. Panggilan Connect unary adalah HTTP POST biasa. Jalur URL berasal langsung dari skema Protobuf Anda, dan badan permintaannya adalah JSON atau Protobuf biner tanpa pembingkaian tambahan.
Format jalurnya adalah /<package>.<Service>/<Method>. Jadi metode Greet pada GreetService dalam paket greet.v1 berada di /greet.v1.GreetService/Greet.
Anda dapat memanggilnya dengan curl:
curl \
--header "Content-Type: application/json" \
--data '{"name": "Jane"}' \
http://localhost:8080/greet.v1.GreetService/Greet
Responsnya adalah JSON biasa:
{"greeting": "Hello, Jane!"}
Tidak ada klien kustom, tidak ada proxy, tidak ada decoding biner. Itulah keseluruhan permintaan. Karena badan permintaannya adalah JSON asli dan statusnya adalah kode status HTTP asli, setiap perkakas yang berbicara HTTP dapat memeriksa panggilan tersebut. Ini adalah properti yang memisahkan protokol Connect dari gRPC mentah, di mana permintaan yang sama akan dibungkus dalam pembingkaian biner dan akan membawa statusnya dalam trailer.
Connect mendukung dua tipe konten untuk permintaan unary:
application/jsonuntuk payload JSON yang dapat dibaca manusia.application/protountuk Protobuf biner yang ringkas.
Anda mengirim Protobuf biner saat Anda menginginkan ukuran wire yang lebih kecil dan JSON saat Anda menginginkan keterbacaan selama pengembangan. Untuk mengirim biner, alihkan header dan lewati badan yang dikodekan:
curl \
--header "Content-Type: application/proto" \
--data-binary @request.bin \
http://localhost:8080/greet.v1.GreetService/Greet
Panggilan streaming menggunakan tipe konten yang berbeda (application/connect+proto atau application/connect+json) dan membungkus setiap pesan dalam sebuah amplop: satu byte penanda, panjang empat-byte big-endian, lalu pesan. Panggilan unary melewatkan amplop itu sepenuhnya, itulah sebabnya mereka memetakan dengan sangat bersih ke permintaan HTTP normal. Jika Anda memilih antara format wire untuk payload Anda, Protobuf vs JSON mencakup kompromi ukuran dan keterbacaan.
Dukungan Bahasa dan Perkakas buf
ConnectRPC menyediakan implementasi di beberapa bahasa. Go dan TypeScript (untuk peramban dan Node.js) stabil dan siap produksi. Swift tersedia untuk platform Apple, dengan Kotlin untuk JVM dan Android, dan Python dalam versi beta. Penyebaran itu memungkinkan Anda berbagi satu kontrak Protobuf di antara backend Go dan frontend TypeScript tanpa menulis klien secara manual.
Pembangkitan kode berjalan melalui toolchain buf. Anda menjelaskan layanan Anda dalam berkas .proto, lalu menggunakan plugin buf untuk menghasilkan pesan dan penangan Connect. Proyek Go menggunakan dua plugin: protoc-gen-go untuk pesan Protobuf dan protoc-gen-connect-go untuk penangan dan klien Connect.
Plugin-plugin tercantum dalam berkas buf.gen.yaml, dan Anda menjalankan pembangkitan dengan satu perintah:
buf generate
Itu menghasilkan struct pesan bertipe serta kode server dan klien untuk layanan Anda. Dari sana Anda mengimplementasikan metode penangan dan mendaftarkannya pada server HTTP. Karena kode yang dihasilkan menargetkan net/http pustaka standar di Go, Anda tidak perlu menarik runtime server terpisah; penangan Connect adalah penangan HTTP normal yang dapat Anda pasang di samping rute yang sudah ada.
Menguji dan Men-debug Endpoint Connect dan gRPC
Karena panggilan unary Connect adalah HTTP biasa dengan badan JSON, Anda dapat mengujinya dengan cara yang sama seperti Anda menguji endpoint REST mana pun. Itu adalah keuntungan praktis: tidak ada klien khusus yang diperlukan untuk menguji layanan Anda selama pengembangan.
Di Apidog, Anda mengirim permintaan unary Connect sebagai permintaan HTTP. Atur metodenya ke POST, gunakan URL yang diturunkan dari skema seperti http://localhost:8080/greet.v1.GreetService/Greet, tambahkan header Content-Type: application/json, dan masukkan pesan Anda ke dalam badan JSON:
{"name": "Jane"}
Anda mendapatkan kembali respons JSON dan kode status HTTP asli, yang dapat Anda verifikasi secara langsung. Apidog bukanlah klien Connect khusus, tetapi tidak perlu menjadi itu; Anda melatih permukaan HTTP yang diekspos oleh protokol Connect, persis seperti yang dilakukan curl, dengan UI, permintaan yang disimpan, dan riwayat di atasnya. Untuk pengantar singkat tentang kata kerja yang terlibat, lihat apa itu metode HTTP.
Karena server Connect juga berbicara gRPC, sisi gRPC layanan Anda juga dapat diuji. Apidog mendukung endpoint gRPC, sehingga Anda dapat mengimpor berkas .proto yang sama, menjelajahi metode layanan, dan memanggilnya dengan permintaan bertipe. Itu berarti satu perkakas mencakup kedua sisi server: protokol Connect yang ramah HTTP dan protokol gRPC asli. Jika gRPC adalah perhatian utama Anda, cara menguji API gRPC secara efisien menjelaskan alur kerjanya.
Setelah permintaan Anda berfungsi, Anda dapat memindahkannya ke pemeriksaan otomatis. Simpan panggilan Connect dan gRPC Anda sebagai skenario pengujian, lalu jalankan di CI dengan Apidog CLI. Instal dengan Node:
npm install -g apidog-cli
Kemudian jalankan skenario atau suite yang disimpan, menunjuk ke lingkungan dan memilih format laporan:
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t <scenarioOrSuiteId> \
-e <environmentId> \
-r cli,html,junit
CLI ini tanpa kepala (headless), sehingga dapat digunakan di langkah CI mana pun yang dapat menjalankan Node. Ini menjalankan skenario dan suite pengujian yang disimpan daripada mengirim permintaan ad hoc, yang membuatnya cocok untuk pemeriksaan regresi pada endpoint Connect dan gRPC Anda. Untuk panduan lengkap, lihat tutorial Apidog CLI untuk menguji API dari baris perintah.
Pertanyaan yang Sering Diajukan
Apakah ConnectRPC sama dengan gRPC? Tidak. ConnectRPC adalah kerangka kerja yang mengimplementasikan tiga protokol: gRPC, gRPC-Web, dan protokol Connect-nya sendiri. Server Connect beroperasi bersama dengan klien dan server gRPC, sehingga sesuai dengan ekosistem gRPC, tetapi protokol Connect itu sendiri adalah desain berbasis HTTP terpisah yang dapat dipanggil langsung oleh peramban dan shell.
Apakah saya masih memerlukan proxy seperti Envoy untuk mencapai peramban? Tidak untuk protokol Connect. Connect berjalan di atas HTTP standar, sehingga peramban dapat memanggil server Connect tanpa proxy penerjemah. Anda hanya akan menggunakan proxy seperti Envoy ketika Anda perlu menjembatani lalu lintas peramban ke backend yang berbicara gRPC asli dan tidak ada yang lain.
Bahasa apa saja yang didukung ConnectRPC? Go dan TypeScript (peramban dan Node.js) adalah implementasi yang stabil dan siap produksi. Swift, Kotlin, dan Python juga tersedia, dengan Python dalam versi beta. Semuanya dihasilkan dari skema Protobuf yang sama.
Apa hubungan antara Connect dan buf? ConnectRPC dibuat oleh Buf dan menggunakan toolchain buf untuk pembangkitan kode. Anda menjalankan buf generate dengan plugin seperti protoc-gen-connect-go untuk menghasilkan penangan dan klien dari berkas .proto Anda.
Dapatkah saya menguji endpoint Connect dengan klien API normal? Ya. Panggilan unary Connect adalah permintaan HTTP POST dengan badan JSON atau Protobuf dan kode status HTTP asli. Klien HTTP apa pun, termasuk curl dan Apidog, dapat mengirimkannya. Apidog juga dapat memanggil sisi gRPC dari server yang sama dengan mengimpor berkas .proto.