إذا كنت قد حاولت استدعاء خدمة gRPC من متصفح، فأنت تعلم بالفعل مدى الصعوبة. لا يمكن للمتصفحات التحدث بلغة gRPC الخام لأنها لا تستطيع التحكم في تذييلات HTTP، لذلك ينتهي بك الأمر بتركيب وكيل مثل Envoy فقط لترجمة حركة المرور. يزيل ConnectRPC هذه الخطوة. يتيح لك بناء واجهات برمجة تطبيقات (APIs) تعتمد على Protobuf يمكن للمتصفح استدعاؤها مباشرة، وتستجيب لأمر curl بسيط، وتظل قابلة للتشغيل المتبادل مع نظام gRPC البيئي الأوسع.
يشرح هذا الدليل ماهية ConnectRPC، والمشكلة التي يحلها بروتوكول Connect، وكيف يقارن Connect بـ gRPC وgRPC-Web وREST، وكيف يبدو طلب Connect عبر HTTP. سترى أيضًا كيفية اختبار وتصحيح أخطاء نقاط نهاية Connect وgRPC باستخدام عميل API قياسي.
ما هو ConnectRPC
ConnectRPC هي مجموعة من المكتبات لبناء واجهات برمجة تطبيقات HTTP متوافقة مع المتصفحات ومتوافقة مع gRPC من Protocol Buffers. تقوم بتعريف خدمتك في ملف .proto، وتوليد الكود، وتنفيذ معالجاتك. يتولى Connect مهمة التوجيه والتسلسل والضغط وتوليد العميل.
تم إنشاء المشروع بواسطة Buf، الشركة التي تقف وراء أدوات بناء buf لـ Protobuf، وهو الآن مشروع صندوق حماية (sandbox project) لمؤسسة Cloud Native Computing Foundation (CNCF). هذا النسب مهم: تم تصميم Connect ليتناسب مع نفس سير العمل القائم على المخطط أولاً الذي تستخدمه الفرق بالفعل مع buf و Protobuf.
يدعم خادم ConnectRPC ثلاثة بروتوكولات في وقت واحد:
- gRPC: توافق كامل، بما في ذلك التدفق والتذييلات.
- gRPC-Web: دعم مباشر، بدون الحاجة إلى وكيل منفصل.
- Connect: بروتوكوله الخاص القائم على HTTP، والمُصمم للويب.
نظرًا لأن خادمًا واحدًا يتحدث الثلاثة، يمكن لعميل gRPC استدعاء خادم Connect، ويمكن لعميل Connect استدعاء أي خادم gRPC. تختار البروتوكول لكل عميل، غالبًا بتغيير تكوين واحد وبدون إعادة كتابة الكود.
المشكلة التي يحلها Connect
gRPC سريع وقوي النوع، لكنه يفترض افتراضات لا يحترمها الويب. يعتمد على HTTP/2 وعلى تذييلات HTTP لحمل معلومات الحالة. لا تعرض المتصفحات التذييلات لـ JavaScript، لذلك لا يمكن للمتصفح العمل كعميل gRPC أصلي. الحل البديل المعتاد هو gRPC-Web بالإضافة إلى وكيل ترجمة مثل Envoy الذي يقع بين المتصفح وواجهة gRPC الخلفية الخاصة بك.
هذا يعمل، لكنه يضيف مكونات متحركة. أنت الآن تقوم بتشغيل وتكوين وكيل، وتصحح خطأ في قفزة إضافية. بالنسبة للفرق التي ترغب في واجهات برمجة تطبيقات قوية النوع والوصول من المتصفح بدون هذا العبء، يبدو الإعداد أثقل مما ينبغي.
يتخذ Connect مسارًا مختلفًا. يعمل بروتوكوله الخاص عبر HTTP القياسي، لذا يمكن للمتصفح استدعائه مباشرة ولا تحتاج إلى وكيل لحركة مرور المتصفح. إذا كنت بحاجة أيضًا لخدمة عملاء gRPC الحاليين، فإن نفس خادم Connect يتعامل معهم أيضًا. تحصل على واجهة خلفية واحدة تستجيب للمتصفحات وأدوات سطر الأوامر وخدمات gRPC على حد سواء.
Connect مقابل gRPC مقابل gRPC-Web مقابل REST
تتداخل هذه الأساليب الأربعة، لذا من المفيد مقارنتها.
يستخدم **gRPC** Protobuf عبر HTTP/2 مع تأطير ثنائي وتذييلات. إنه فعال ويدعم جميع أوضاع التدفق الأربعة، لكنه صعب الاستدعاء من المتصفح أو باستخدام shell. إذا كنت ترغب في مراجعة طبقة النقل، انظر كيف يعمل gRPC و HTTP/2 معًا.
**gRPC-Web** هو نوع من gRPC صديق للمتصفح. لا يزال يركز على Protobuf وعادة ما يحتاج إلى وكيل للربط بواجهة gRPC خلفية حقيقية. يغطي دليلنا حول ما هو gRPC-Web مكان ملاءمته.
يحتفظ **Connect** بمخطط Protobuf ونموذج الطريقة على غرار gRPC، لكن بروتوكوله يعمل بسلاسة عبر HTTP/1.1 و HTTP/2 و HTTP/3. تحمل استدعاءات Unary نص JSON أو Protobuf عاديًا بدون تأطير ثنائي لـ gRPC، وتستخدم الاستجابات رموز حالة HTTP حقيقية. هذا المزيج هو ما يجعل استدعاء Connect سهل الوصول إليه مثل أي استدعاء REST.
**REST** موجه نحو الموارد واختياري للمخطط. إنه النمط الأكثر دعمًا عالميًا، لكنه يفتقر إلى توليد الكود والكتابة الصارمة التي يوفرها لك Protobuf. إذا كنت توازن بين الإيجابيات والسلبيات، فإن gRPC مقابل REST يوضح الاختلافات.
النسخة المختصرة: يهدف Connect إلى منحك الكتابة والأدوات الخاصة بـ gRPC مع مدى الوصول وإمكانية تصحيح الأخطاء الخاصة بـ REST. يعتمد على نموذج Protobuf وطريقة gRPC مع إسقاط الأجزاء التي لا تستطيع المتصفحات والـ shells التعامل معها.
طلب Connect عبر HTTP
إليك ما يجعل Connect سهل الاستخدام. استدعاء Connect أحادي هو طلب HTTP POST عادي. يأتي مسار URL مباشرة من مخطط Protobuf الخاص بك، ويكون النص إما JSON أو Protobuf ثنائي بدون تأطير إضافي.
تنسيق المسار هو /<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!"}
لا عميل مخصص، لا وكيل، لا فك تشفير ثنائي. هذا هو الطلب بأكمله. نظرًا لأن النص هو JSON حقيقي والحالة هي رمز حالة HTTP حقيقي، يمكن لكل أداة تتحدث HTTP فحص الاستدعاء. هذه هي الخاصية التي تفصل بروتوكول Connect عن gRPC الخام، حيث يتم تغليف نفس الطلب في تأطير ثنائي ويحمل حالته في تذييل.
يدعم Connect نوعين من المحتوى لطلبات Unary:
- `application/json` لبيانات JSON القابلة للقراءة البشرية.
- `application/proto` لـ Protobuf ثنائي مضغوط.
ترسل Protobuf ثنائي عندما تريد حجم سلك أصغر و JSON عندما تريد قابلية القراءة أثناء التطوير. لإرسال ثنائي، قم بتبديل الرأس وتمرير نص مشفر:
curl \
--header "Content-Type: application/proto" \
--data-binary @request.bin \
http://localhost:8080/greet.v1.GreetService/Greet
تستخدم استدعاءات التدفق نوع محتوى مختلفًا (`application/connect+proto` أو `application/connect+json`) وتغلف كل رسالة في غلاف: بايت إشارة واحد، ثم طول بأربعة بايتات بنهاية كبيرة، ثم الرسالة. تتخطى استدعاءات Unary هذا الغلاف بالكامل، ولهذا السبب تتطابق بسلاسة مع طلب HTTP عادي. إذا كنت تختار بين تنسيقات الأسلاك لبياناتك، فإن Protobuf مقابل JSON يغطي مقايضات الحجم وقابلية القراءة.
دعم اللغات وأدوات buf
يشحن ConnectRPC تطبيقات عبر عدة لغات. Go و TypeScript (لكل من المتصفح و Node.js) مستقران وجاهزان للإنتاج. Swift متاح لمنصات Apple، مع Kotlin لـ JVM و Android، و Python في مرحلة تجريبية. هذا الانتشار يتيح لك مشاركة عقد Protobuf واحد عبر واجهة Go خلفية وواجهة TypeScript أمامية دون كتابة العملاء يدويًا.
يتم توليد الكود من خلال مجموعة أدوات `buf`. تقوم بوصف خدمتك في ملف .proto، ثم تستخدم مكونات buf الإضافية لتوليد الرسائل ومعالجات Connect. يستخدم مشروع Go مكونين إضافيين: protoc-gen-go لرسائل Protobuf و protoc-gen-connect-go لمعالجات وعملاء Connect.
تُدرج المكونات الإضافية في ملف buf.gen.yaml، وتُشغّل عملية التوليد بأمر واحد:
buf generate
ينتج عن ذلك هياكل رسائل قوية النوع بالإضافة إلى كود الخادم والعميل لخدمتك. من هناك، تقوم بتنفيذ طرق المعالجة وتسجيلها على خادم HTTP. نظرًا لأن الكود المُولّد يستهدف مكتبة net/http القياسية في Go، فلن تحتاج إلى وقت تشغيل خادم منفصل؛ معالج Connect هو معالج HTTP عادي يمكنك تركيبه جنبًا إلى جنب مع مساراتك الحالية.
اختبار وتصحيح أخطاء نقاط نهاية Connect و gRPC
بما أن استدعاءات Connect الأحادية هي HTTP عادي مع نص JSON، يمكنك اختبارها بنفس الطريقة التي تختبر بها أي نقطة نهاية REST. هذا فوز عملي: لا يلزم عميل خاص للعبث بخدمتك أثناء التطوير.
في Apidog، ترسل طلب Connect أحادي كطلب HTTP. اضبط الطريقة على POST، استخدم عنوان URL المشتق من المخطط مثل http://localhost:8080/greet.v1.GreetService/Greet، أضف رأس Content-Type: application/json، وضع رسالتك في نص JSON:
{"name": "Jane"}
تحصل على استجابة JSON ورمز حالة HTTP حقيقي، والذي يمكنك تأكيده مباشرة. Apidog ليس عميل Connect مخصصًا، ولكنه لا يحتاج إلى ذلك؛ فأنت تمارس واجهة HTTP التي يكشفها بروتوكول Connect، تمامًا كما يفعل curl، مع واجهة مستخدم وطلبات محفوظة وسجل في الأعلى. للحصول على مقدمة سريعة للأفعال المعنية، انظر ما هي طرق HTTP.
نظرًا لأن خادم Connect يتحدث أيضًا gRPC، فإن جانب gRPC من خدمتك قابل للاختبار أيضًا. يدعم Apidog نقاط نهاية gRPC، لذا يمكنك استيراد نفس ملف `.proto`، وتصفح طرق الخدمة، واستدعائها بطلب مكتوب. هذا يعني أن أداة واحدة تغطي كلا وجهي الخادم: بروتوكول Connect الصديق لـ HTTP وبروتوكول gRPC الأصلي. إذا كان gRPC هو اهتمامك الرئيسي، فإن كيفية اختبار واجهات برمجة تطبيقات gRPC بكفاءة يشرح سير العمل.
بمجرد أن تتصرف طلباتك بشكل صحيح، يمكنك نقلها إلى فحوصات آلية. احفظ مكالمات 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) بلا رأس، لذا فهي تتناسب مع أي خطوة CI يمكنها تشغيل Node. إنها تشغل سيناريوهات ومجموعات اختبار محفوظة بدلاً من إرسال طلبات مخصصة، مما يجعلها مناسبة لفحوصات التراجع على نقاط نهاية Connect و gRPC الخاصة بك. للحصول على شرح كامل، راجع البرنامج التعليمي لـ Apidog CLI لاختبار واجهة برمجة تطبيقات من سطر الأوامر.
الأسئلة الشائعة
هل ConnectRPC هو نفسه gRPC؟ لا. ConnectRPC هو إطار عمل يطبق ثلاثة بروتوكولات: gRPC و gRPC-Web وبروتوكول Connect الخاص به. يتفاعل خادم Connect مع عملاء وخوادم gRPC، لذا فهو يتناسب مع نظام gRPC البيئي، لكن بروتوكول Connect نفسه هو تصميم منفصل قائم على HTTP يمكن للمتصفحات و الـ shells استدعاؤه مباشرة.
هل ما زلت بحاجة إلى وكيل مثل Envoy للوصول إلى المتصفح؟ ليس لبروتوكول Connect. يعمل Connect عبر HTTP القياسي، لذا يمكن للمتصفح استدعاء خادم Connect بدون وكيل ترجمة. لن تحتاج إلى وكيل مثل Envoy إلا عندما تحتاج إلى ربط حركة مرور المتصفح بواجهة خلفية تتحدث gRPC الأصلي فقط ولا شيء غير ذلك.
ما هي اللغات التي يدعمها ConnectRPC؟ Go و TypeScript (للمتصفح و Node.js) هي التطبيقات المستقرة والجاهزة للإنتاج. Swift و Kotlin و Python متاحة أيضًا، مع Python في مرحلة تجريبية. كلها تُولد من نفس مخطط Protobuf.
ما هي العلاقة بين Connect و buf؟ تم إنشاء ConnectRPC بواسطة Buf ويستخدم مجموعة أدوات `buf` لتوليد الكود. يمكنك تشغيل buf generate باستخدام مكونات إضافية مثل protoc-gen-connect-go لإنتاج المعالجات والعملاء من ملفات .proto الخاصة بك.
هل يمكنني اختبار نقطة نهاية Connect باستخدام عميل API عادي؟ نعم. استدعاءات Connect الأحادية هي طلبات HTTP POST بنص JSON أو Protobuf ورمز حالة HTTP حقيقي. يمكن لأي عميل HTTP، بما في ذلك curl و Apidog، إرسال أحدها. يمكن لـ Apidog أيضًا استدعاء جانب gRPC من نفس الخادم عن طريق استيراد ملف .proto.