ConnectRPC คืออะไร? โปรโตคอล Connect

หากคุณเคยพยายามเรียกใช้บริการ gRPC จากเบราว์เซอร์ คุณจะทราบถึงปัญหาที่เกิดขึ้น เบราว์เซอร์ไม่สามารถสื่อสาร gRPC ดิบได้ เนื่องจากไม่สามารถควบคุม HTTP trailers ได้ คุณจึงต้องติดตั้ง proxy อย่าง Envoy เพื่อแปลการรับส่งข้อมูล ConnectRPC จะช่วยลดขั้นตอนนั้นลง ช่วยให้คุณสร้าง API ที่ใช้ Protobuf ที่เบราว์เซอร์สามารถเรียกใช้ได้โดยตรง ตอบสนองต่อคำสั่ง curl ธรรมดา และยังคงทำงานร่วมกับระบบนิเวศ gRPC ในวงกว้างได้

คู่มือนี้จะอธิบายว่า ConnectRPC คืออะไร ปัญหาที่โปรโตคอล Connect แก้ไข Connect เปรียบเทียบกับ gRPC, gRPC-Web และ REST อย่างไร และคำขอ Connect มีลักษณะอย่างไรผ่าน HTTP คุณยังจะได้เห็นวิธีการทดสอบและแก้ไขข้อบกพร่องของ Connect และ gRPC endpoints ด้วยไคลเอนต์ API มาตรฐาน

ConnectRPC คืออะไร

ConnectRPC คือชุดไลบรารีสำหรับการสร้าง HTTP API ที่เข้ากันได้กับเบราว์เซอร์และ gRPC โดยใช้ Protocol Buffers คุณกำหนดบริการของคุณในไฟล์ .proto สร้างโค้ด และใช้ handlers Connect จะดูแลเรื่องการกำหนดเส้นทาง, การแปลงข้อมูล (serialization), การบีบอัด และการสร้างไคลเอนต์

โครงการนี้สร้างขึ้นโดย Buf บริษัทเบื้องหลังเครื่องมือสร้าง buf สำหรับ Protobuf และตอนนี้เป็นโครงการ sandbox ของ Cloud Native Computing Foundation (CNCF) ที่มานี้สำคัญ: Connect ได้รับการออกแบบมาเพื่อให้เข้ากับเวิร์กโฟลว์ schema-first แบบเดียวกับที่ทีมต่างๆ ใช้กับ buf และ Protobuf อยู่แล้ว

เซิร์ฟเวอร์ ConnectRPC รองรับสามโปรโตคอลพร้อมกัน:

gRPC: เข้ากันได้เต็มรูปแบบ รวมถึงการสตรีมและ trailers
gRPC-Web: รองรับโดยตรง ไม่ต้องใช้ proxy แยกต่างหาก
Connect: โปรโตคอลของตัวเองที่ใช้ HTTP ปรับแต่งมาสำหรับเว็บ

เนื่องจากเซิร์ฟเวอร์เดียวรองรับทั้งสามโปรโตคอล ไคลเอนต์ gRPC สามารถเรียกใช้เซิร์ฟเวอร์ Connect ได้ และไคลเอนต์ Connect สามารถเรียกใช้เซิร์ฟเวอร์ gRPC ใดก็ได้ คุณเลือกโปรโตคอลสำหรับไคลเอนต์แต่ละตัว ซึ่งมักจะมีการเปลี่ยนแปลงการกำหนดค่าเพียงครั้งเดียวและไม่ต้องเขียนโค้ดใหม่

ปัญหาที่ Connect แก้ไข

gRPC รวดเร็วและมีการกำหนดประเภทที่เข้มงวด (strongly typed) แต่มีการสมมติฐานที่เว็บไม่รองรับ มันพึ่งพา HTTP/2 และ HTTP trailers ในการส่งข้อมูลสถานะ เบราว์เซอร์ไม่ได้เปิดเผย trailers ให้ JavaScript ทราบ ดังนั้นเบราว์เซอร์จึงไม่สามารถทำหน้าที่เป็น gRPC ไคลเอนต์แบบเนทีฟได้ วิธีแก้ไขทั่วไปคือ gRPC-Web บวกกับ translating proxy เช่น Envoy ที่อยู่ระหว่างเบราว์เซอร์กับแบ็กเอนด์ gRPC ของคุณ

วิธีนี้ใช้ได้ผล แต่เพิ่มส่วนประกอบที่เคลื่อนไหวได้ คุณต้องเรียกใช้และกำหนดค่า proxy และแก้ไขข้อบกพร่องของ hop พิเศษ สำหรับทีมที่ต้องการ API ที่มีการกำหนดประเภทและการเข้าถึงจากเบราว์เซอร์โดยไม่มี overhead นั้น การตั้งค่านี้รู้สึกว่าหนักเกินไป

Connect ใช้เส้นทางที่แตกต่างออกไป โปรโตคอลของตัวเองทำงานผ่าน HTTP มาตรฐาน ดังนั้นเบราว์เซอร์จึงสามารถเรียกใช้ได้โดยตรง และคุณไม่จำเป็นต้องมี proxy สำหรับการรับส่งข้อมูลจากเบราว์เซอร์ หากคุณต้องการให้บริการไคลเอนต์ gRPC ที่มีอยู่ เซิร์ฟเวอร์ Connect เดียวกันก็รองรับได้เช่นกัน คุณจะได้แบ็กเอนด์เดียวที่ตอบสนองทั้งเบราว์เซอร์, เครื่องมือ command-line และบริการ gRPC ได้เหมือนกัน

Connect เทียบกับ gRPC เทียบกับ gRPC-Web เทียบกับ REST

วิธีการทั้งสี่นี้มีความทับซ้อนกัน จึงเป็นประโยชน์ที่จะจัดเรียงเพื่อเปรียบเทียบ

gRPC ใช้ Protobuf ผ่าน HTTP/2 พร้อม binary framing และ trailers มีประสิทธิภาพและรองรับการสตรีมทั้งสี่โหมด แต่เรียกใช้จากเบราว์เซอร์หรือด้วยเชลล์ได้ยาก หากคุณต้องการทบทวนในชั้น transport layer โปรดดู gRPC และ HTTP/2 ทำงานร่วมกันอย่างไร

gRPC-Web เป็น gRPC รุ่นที่เหมาะกับเบราว์เซอร์ ยังคงเน้นที่ Protobuf และมักจะต้องใช้ proxy เพื่อเชื่อมต่อกับแบ็กเอนด์ gRPC จริงๆ คู่มือของเราเกี่ยวกับ gRPC-Web คืออะไร ครอบคลุมถึงตำแหน่งที่เหมาะสม

Connect ยังคงใช้ Protobuf schema และโมเดลเมธอดแบบ gRPC แต่โปรโตคอลของมันทำงานได้อย่างราบรื่นผ่าน HTTP/1.1, HTTP/2 และ HTTP/3 การเรียกแบบ Unary ส่ง JSON หรือ Protobuf body ธรรมดาโดยไม่มี gRPC binary framing และการตอบสนองใช้รหัสสถานะ HTTP จริงๆ การผสมผสานนี้เองที่ทำให้การเรียก Connect เข้าถึงได้ง่ายเหมือนการเรียก REST ทั่วไป

REST เน้นทรัพยากรและ schema-optional เป็นสไตล์ที่ได้รับการสนับสนุนอย่างกว้างขวางที่สุด แต่ขาดการสร้างโค้ดและการกำหนดประเภทที่เข้มงวดที่ Protobuf ให้คุณ หากคุณกำลังพิจารณาข้อดีข้อเสีย gRPC เทียบกับ REST จะแยกแยะความแตกต่าง

สรุปสั้นๆ: Connect มีเป้าหมายที่จะให้การกำหนดประเภทและเครื่องมือของ gRPC แก่คุณ ด้วยการเข้าถึงและการดีบักที่เหมือน REST มันพึ่งพา Protobuf และโมเดลเมธอดของ gRPC ในขณะที่ตัดส่วนที่เบราว์เซอร์และเชลล์ไม่สามารถจัดการได้

คำขอ Connect ผ่าน HTTP

นี่คือสิ่งที่ทำให้ Connect เข้าถึงได้ง่าย การเรียก Connect แบบ Unary เป็น HTTP POST ธรรมดา เส้นทาง URL มาจาก Protobuf schema ของคุณโดยตรง และ body เป็น JSON หรือ Protobuf แบบไบนารีโดยไม่มี framing เพิ่มเติม

รูปแบบเส้นทางคือ /<package>.<Service>/<Method> ดังนั้นเมธอด Greet บน GreetService ในแพ็คเกจ greet.v1 จะอยู่ที่ /greet.v1.GreetService/Greet

คุณสามารถเรียกใช้ด้วย curl:

curl \
    --header "Content-Type: application/json" \
    --data '{"name": "Jane"}' \
    http://localhost:8080/greet.v1.GreetService/Greet

การตอบสนองเป็น JSON ธรรมดา:

{"greeting": "Hello, Jane!"}

ไม่มีไคลเอนต์แบบกำหนดเอง, ไม่มี proxy, ไม่มีการถอดรหัสไบนารี นี่คือคำขอทั้งหมด เนื่องจาก body เป็น JSON จริง และสถานะเป็นรหัสสถานะ HTTP จริงๆ เครื่องมือทุกชนิดที่สื่อสาร HTTP สามารถตรวจสอบการเรียกได้ นี่คือคุณสมบัติที่แยกโปรโตคอล Connect ออกจาก gRPC ดิบ ซึ่งคำขอเดียวกันจะถูกห่อหุ้มด้วย binary framing และส่งสถานะใน trailer

Connect รองรับสอง content types สำหรับคำขอแบบ Unary:

application/json สำหรับ JSON payloads ที่อ่านง่ายสำหรับมนุษย์
application/proto สำหรับ Protobuf ไบนารีขนาดกะทัดรัด

คุณส่ง Protobuf ไบนารีเมื่อคุณต้องการขนาดสายที่เล็กกว่า และ JSON เมื่อคุณต้องการความสามารถในการอ่านระหว่างการพัฒนา หากต้องการส่งไบนารี ให้เปลี่ยน header และส่ง encoded body:

curl \
    --header "Content-Type: application/proto" \
    --data-binary @request.bin \
    http://localhost:8080/greet.v1.GreetService/Greet

การเรียกแบบสตรีมมิ่งใช้ content type ที่แตกต่างกัน (application/connect+proto หรือ application/connect+json) และห่อหุ้มแต่ละข้อความในซองจดหมาย: หนึ่งไบต์ flag, ความยาวสี่ไบต์แบบ big-endian, จากนั้นเป็นข้อความ การเรียกแบบ Unary ข้ามซองจดหมายนั้นทั้งหมด ซึ่งเป็นเหตุผลที่สามารถแมปเข้ากับการร้องขอ HTTP ปกติได้อย่างราบรื่น หากคุณกำลังเลือกระหว่างรูปแบบ wire format สำหรับ payloads ของคุณ Protobuf เทียบกับ JSON ครอบคลุมข้อดีข้อเสียด้านขนาดและการอ่านง่าย

การรองรับภาษาและเครื่องมือ buf

ConnectRPC มีการใช้งานในหลายภาษา Go และ TypeScript (สำหรับทั้งเบราว์เซอร์และ Node.js) มีความเสถียรและพร้อมสำหรับการใช้งานจริง Swift มีให้สำหรับแพลตฟอร์ม Apple, Kotlin สำหรับ JVM และ Android, และ Python อยู่ในเวอร์ชันเบต้า การกระจายนี้ช่วยให้คุณสามารถใช้สัญญา Protobuf เดียวกันระหว่างแบ็กเอนด์ Go และฟรอนต์เอนด์ TypeScript โดยไม่ต้องเขียนไคลเอนต์ด้วยมือ

การสร้างโค้ดทำงานผ่าน toolchain ของ buf คุณอธิบายบริการของคุณในไฟล์ .proto จากนั้นใช้ปลั๊กอิน buf เพื่อสร้างข้อความและ Connect handlers โครงการ Go ใช้ปลั๊กอินสองตัว: protoc-gen-go สำหรับข้อความ Protobuf และ protoc-gen-connect-go สำหรับ Connect handlers และไคลเอนต์

ปลั๊กอินแสดงอยู่ในไฟล์ buf.gen.yaml และคุณเรียกใช้การสร้างด้วยคำสั่งเดียว:

buf generate

สิ่งนี้จะสร้างโครงสร้างข้อความที่มีการกำหนดประเภท (typed message structs) พร้อมโค้ดเซิร์ฟเวอร์และไคลเอนต์สำหรับบริการของคุณ จากนั้นคุณจะใช้เมธอด handler และลงทะเบียนบนเซิร์ฟเวอร์ HTTP เนื่องจากโค้ดที่สร้างขึ้นกำหนดเป้าหมายไปยัง net/http ของไลบรารีมาตรฐานใน Go คุณจึงไม่จำเป็นต้องดึงรันไทม์เซิร์ฟเวอร์แยกต่างหาก; Connect handler เป็น HTTP handler ปกติที่คุณสามารถติดตั้งร่วมกับเส้นทางที่มีอยู่ของคุณได้

การทดสอบและแก้ไขข้อบกพร่องของ Connect และ gRPC Endpoints

เนื่องจากการเรียก Connect แบบ Unary เป็น HTTP พร้อม JSON body คุณจึงสามารถทดสอบได้ในลักษณะเดียวกับการทดสอบ REST endpoint ใดๆ นั่นเป็นข้อดีในทางปฏิบัติ: ไม่จำเป็นต้องมีไคลเอนต์พิเศษเพื่อตรวจสอบบริการของคุณระหว่างการพัฒนา

ใน Apidog คุณส่งคำขอ Connect Unary เป็นคำขอ HTTP ตั้งค่าเมธอดเป็น POST ใช้ URL ที่ได้จาก schema เช่น http://localhost:8080/greet.v1.GreetService/Greet เพิ่ม header Content-Type: application/json และใส่ข้อความของคุณใน JSON body:

{"name": "Jane"}

คุณจะได้รับการตอบกลับเป็น JSON และรหัสสถานะ HTTP จริง ซึ่งคุณสามารถยืนยันได้โดยตรง Apidog ไม่ใช่ไคลเอนต์ Connect โดยเฉพาะ แต่ก็ไม่จำเป็นต้องเป็นเช่นนั้น คุณกำลังใช้ HTTP surface ที่โปรโตคอล Connect เปิดเผยอยู่ เหมือนกับที่ curl ทำ ด้วย UI, คำขอที่บันทึกไว้ และประวัติเพิ่มเติม สำหรับข้อมูลเบื้องต้นเกี่ยวกับ verb ที่เกี่ยวข้อง โปรดดู HTTP methods คืออะไร

เนื่องจากเซิร์ฟเวอร์ Connect ยังสื่อสาร gRPC ได้ด้วย ด้าน gRPC ของบริการของคุณก็สามารถทดสอบได้เช่นกัน Apidog รองรับ gRPC endpoints ดังนั้นคุณสามารถนำเข้าไฟล์ .proto เดียวกัน เรียกดูเมธอดบริการ และเรียกใช้ด้วยคำขอที่มีการกำหนดประเภท สิ่งนี้หมายความว่าเครื่องมือเดียวครอบคลุมทั้งสองด้านของเซิร์ฟเวอร์: โปรโตคอล Connect ที่เป็นมิตรกับ HTTP และโปรโตคอล gRPC แบบเนทีฟ หาก gRPC เป็นข้อกังวลหลักของคุณ วิธีการทดสอบ gRPC APIs อย่างมีประสิทธิภาพ จะอธิบายเวิร์กโฟลว์โดยละเอียด

เมื่อคำขอของคุณทำงานได้ตามที่ต้องการ คุณสามารถย้ายไปสู่การตรวจสอบอัตโนมัติได้ บันทึกการเรียก Connect และ gRPC ของคุณเป็นสถานการณ์ทดสอบ จากนั้นรันใน CI ด้วย Apidog CLI ติดตั้งด้วย Node:

npm install -g apidog-cli

จากนั้นรันสถานการณ์หรือชุดทดสอบที่บันทึกไว้ โดยชี้ไปที่สภาพแวดล้อมและเลือกรูปแบบรายงาน:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenarioOrSuiteId> \
  -e <environmentId> \
  -r cli,html,junit

CLI เป็นแบบ headless จึงสามารถใช้ได้ในขั้นตอน CI ใดๆ ที่สามารถรัน Node ได้ มันรันสถานการณ์และชุดทดสอบที่บันทึกไว้ แทนที่จะส่งคำขอเฉพาะกิจ ซึ่งทำให้เหมาะสำหรับการตรวจสอบ regression บน Connect และ gRPC endpoints ของคุณ สำหรับคำแนะนำฉบับเต็ม โปรดดู บทช่วยสอน Apidog CLI สำหรับการทดสอบ API จาก command line

button

คำถามที่พบบ่อย

ConnectRPC เหมือนกับ gRPC หรือไม่? ไม่ ConnectRPC เป็นเฟรมเวิร์กที่ใช้สามโปรโตคอล: gRPC, gRPC-Web และโปรโตคอล Connect ของตัวเอง เซิร์ฟเวอร์ Connect สามารถทำงานร่วมกับไคลเอนต์และเซิร์ฟเวอร์ gRPC ได้ ดังนั้นจึงเข้ากับระบบนิเวศ gRPC แต่โปรโตคอล Connect นั้นเป็นดีไซน์ที่ใช้ HTTP แยกต่างหากที่เบราว์เซอร์และเชลล์สามารถเรียกใช้ได้โดยตรง

ฉันยังจำเป็นต้องมี proxy เช่น Envoy เพื่อเข้าถึงเบราว์เซอร์หรือไม่? ไม่จำเป็นสำหรับโปรโตคอล Connect Connect ทำงานผ่าน HTTP มาตรฐาน ดังนั้นเบราว์เซอร์จึงสามารถเรียกใช้เซิร์ฟเวอร์ Connect ได้โดยไม่ต้องมี translating proxy คุณจะใช้ proxy เช่น Envoy ก็ต่อเมื่อคุณต้องการเชื่อมต่อการรับส่งข้อมูลของเบราว์เซอร์ไปยังแบ็กเอนด์ที่ใช้ gRPC เนทีฟเท่านั้น

ConnectRPC รองรับภาษาใดบ้าง? Go และ TypeScript (เบราว์เซอร์และ Node.js) เป็นการใช้งานที่เสถียรและพร้อมสำหรับการใช้งานจริง Swift, Kotlin และ Python ก็มีให้ใช้งาน โดย Python อยู่ในเวอร์ชันเบต้า ทั้งหมดสร้างมาจาก Protobuf schema เดียวกัน

ความสัมพันธ์ระหว่าง Connect และ buf คืออะไร? ConnectRPC สร้างโดย Buf และใช้ toolchain buf สำหรับการสร้างโค้ด คุณเรียกใช้ buf generate ด้วยปลั๊กอินเช่น protoc-gen-connect-go เพื่อสร้าง handlers และไคลเอนต์จากไฟล์ .proto ของคุณ

ฉันสามารถทดสอบ Connect endpoint ด้วยไคลเอนต์ API ปกติได้หรือไม่? ได้ การเรียก Connect แบบ Unary เป็นคำขอ HTTP POST ที่มี JSON หรือ Protobuf body และรหัสสถานะ HTTP จริง ไคลเอนต์ HTTP ใดๆ รวมถึง curl และ Apidog สามารถส่งคำขอได้ Apidog ยังสามารถเรียกใช้ด้าน gRPC ของเซิร์ฟเวอร์เดียวกันได้โดยการนำเข้าไฟล์ .proto