كيفية استخدام grpc-curl لاختبار وتصحيح واجهات برمجة التطبيقات الخاصة بك

إذا كنت مطورًا يعمل مع واجهات برمجة التطبيقات (APIs)، فمن المحتمل أنك تعرف مدى أهمية اختبارها وتصحيح الأخطاء فيها قبل نشرها في الإنتاج. تريد التأكد من أن واجهات برمجة التطبيقات الخاصة بك موثوقة وآمنة وفعالة، وأنها تلبي توقعات عملائك ومستخدميك.

لكن كيف يمكنك اختبار وتصحيح أخطاء واجهات برمجة التطبيقات الخاصة بك، خاصة إذا كانت تستخدم gRPC، وهو بروتوكول حديث وفعال للتواصل بين الخدمات الصغيرة؟ هنا يأتي دور grpc-curl. grpc-curl هو أداة سطر الأوامر التي تتيح لك التفاعل مع خوادم gRPC بسهولة وبشكل بديهي.

في هذه التدوينة، سأوضح لك كيف تستخدم grpc-curl لاختبار وتصحيح أخطاء واجهات برمجة التطبيقات الخاصة بك، ولماذا يجب أن تفكر في استخدامه لمشاريع gRPC الخاصة بك.

💡

إذا كنت ترغب في رفع مستوى اختبار وتصحيح أخطاء gRPC الخاص بك، فقد ترغب في استخدام grpc-curl مع Apidog، وهي أداة قوية ومرنة لوثائق واختبارات API. Apidog هي أداة تتيح لك إنشاء وإدارة ومشاركة وثائق واختبارات واجهات برمجة التطبيقات باستخدام واجهة بسيطة وبديهية. يمكنك استخدام Apidog لتوثيق واختبار أي نوع من واجهات برمجة التطبيقات، بما في ذلك REST، SOAP، GraphQL، وgRPC مجانًا.

button

ما هو grpc-curl؟

grpc-curl هو أداة سطر الأوامر التي تتيح لك استدعاء طرق RPC على خادم gRPC من سطر الأوامر. يدعم طرق RPC المتنوعة، بما في ذلك الأحادية، البث من الخادم، البث من العميل، والبث ثنائي الاتجاه. يمكنك أيضًا استعراض المخطط لخدمات gRPC، إما عن طريق استعلام خادم يدعم الانعكاس من الخادم أو عن طريق تحميل ملفات بروتوسيت المترجمة.

grpc-curl مكتوب بلغة .NET، وله بعض المزايا على gRPCurl، مثل:

يدعم كل من .NET Core و .NET Framework، ويمكن تشغيله على Windows و Linux و Mac OS.
يمتاز بصياغة أكثر إيجازًا ووضوحًا، ويمكنه استنتاج أسماء الخدمة والطريقة من عنوان URL.
يمكنه تنسيق مخرجات JSON تلقائيًا بالألوان والمسافات، ويمكنه أيضًا إخراج XML أو نص عادي.
يمكنه التعامل مع الرسائل المتداخلة والحقول المكررة بشكل أفضل، ويمكنه أيضًا قبول المدخلات من الملفات أو المدخلات القياسية.
يمكنه استخدام متغيرات البيئة للخيارات الشائعة، مثل عنوان URL للخادم، والرؤوس، وإعدادات TLS.
يمكنه إنشاء مقتطفات رمزية لـ C# و Java و Python و Go، لمساعدتك في كتابة شيفرة العميل الخاصة بك.

grpc-curl متاحة كحزمة NuGet، ويمكنك تثبيتها باستخدام الأمر التالي:

dotnet tool install -g grpc-curl

كيفية استخدام grpc-curl؟

لاستخدام grpc-curl، تحتاج إلى تشغيل خادم gRPC، وتحتاج إلى معرفة عنوان URL الخاص به وأسماء الخدمة والطريقة التي تريد استدعاؤها. تحتاج أيضًا إلى الحصول على المخطط لخدمات gRPC، إما باستخدام الانعكاس من الخادم أو عن طريق تحميل ملفات بروتوسيت.

في هذا المثال، سأستخدم خادم gRPC بسيط ينفذ خدمة آلة حاسبة، مع أربع طرق: الجمع، الطرح، الضرب، والقسمة. الخادم مكتوب بلغة C#، ويدعم الانعكاس من الخادم.

لإطلاق الخادم، قم بتشغيل الأمر التالي من مجلد المشروع:

dotnet run

سوف يستمع الخادم على المنفذ 5000 بشكل افتراضي. يمكنك تغيير رقم المنفذ في ملف appsettings.json.

لإجراء استدعاء لطريقة الجمع على الخادم، قم بتشغيل الأمر التالي من محطة أخرى:

grpc-curl http://localhost:5000 Calculator/Add -d '{"x": 3, "y": 5}'

يجب أن تبدو المخرجات كما يلي:

{
  "result": 8
}

كما ترى، يقوم grpc-curl تلقائيًا باستنتاج أسماء الخدمة والطريقة من عنوان URL، وينسق مخرجات JSON بالألوان والمسافات. يمكنك أيضًا استخدام الخيار -o لتحديد تنسيق إخراج مختلف، مثل xml أو النص.

لإجراء استدعاء لطريقة الطرح، قم بتشغيل الأمر التالي:

grpc-curl http://localhost:5000 Calculator/Subtract -d '{"x": 10, "y": 4}'

يجب أن تبدو المخرجات كما يلي:

{
  "result": 6
}

لإجراء استدعاء لطريقة الضرب، قم بتشغيل الأمر التالي:

grpc-curl http://localhost:5000 Calculator/Multiply -d '{"x": 2, "y": 7}'

يجب أن تبدو المخرجات كما يلي:

{
  "result": 14
}

لإجراء استدعاء لطريقة القسمة، قم بتشغيل الأمر التالي:

grpc-curl http://localhost:5000 Calculator/Divide -d '{"x": 15, "y": 3}'

يجب أن تبدو المخرجات كما يلي:

{
  "result": 5
}

إذا حاولت القسمة على الصفر، ستحصل على رسالة خطأ، مثل هذه:

grpc-curl http://localhost:5000 Calculator/Divide -d '{"x": 15, "y": 0}'

{
  "error": "لا يمكن القسمة على الصفر."
}

يدعم grpc-curl أيضًا طرق البث، التي يمكن أن ترسل أو تستقبل العديد من الرسائل في استدعاء واحد. على سبيل المثال، لنفترض أن لدينا طريقة بث من الخادم تُدعى Fibonacci، والتي تأخذ عدد n كدخل وتعيد أول n من أرقام فيبوناتشي كتيار من الرسائل. يبدو كود الخادم لهذه الطريقة كالتالي:

public override async Task Fibonacci(Number request, IServerStreamWriter<Number> responseStream, ServerCallContext context)
{
    int n = request.Value;
    int a = 0;
    int b = 1;
    for (int i = 0; i < n; i++)
    {
        await responseStream.WriteAsync(new Number { Value = a });
        int temp = a;
        a = b;
        b = temp + b;
    }
}

لإجراء استدعاء لهذه الطريقة باستخدام grpc-curl، قم بتشغيل الأمر التالي:

grpc-curl http://localhost:5000 Calculator/Fibonacci -d '{"value": 10}'

يجب أن تبدو المخرجات كما يلي:

{
  "value": 0
}
{
  "value": 1
}
{
  "value": 1
}
{
  "value": 2
}
{
  "value": 3
}
{
  "value": 5
}
{
  "value": 8
}
{
  "value": 13
}
{
  "value": 21
}
{
  "value": 34
}

كما ترى، يقوم grpc-curl بطباعة كل رسالة كما يتلقاها من الخادم، ويغلق الاتصال عندما تكتمل التدفق.

يدعم grpc-curl أيضًا طرق البث من العميل، التي يمكن أن ترسل العديد من الرسائل إلى الخادم وتستقبل ردًا واحدًا. على سبيل المثال، لنفترض أن لدينا طريقة بث من العميل تُدعى Sum، والتي تأخذ تيارًا من الأرقام كدخل وتعيد مجموعها كاستجابة. يبدو كود الخادم لهذه الطريقة كالتالي:

public override async Task<Number> Sum(IAsyncStreamReader<Number> requestStream, ServerCallContext context)
{
    int sum = 0;
    await foreach (var number in requestStream.ReadAllAsync())
    {
        sum += number.Value;
    }
    return new Number { Value = sum };
}

لإجراء استدعاء لهذه الطريقة باستخدام grpc-curl، نحتاج إلى تقديم الرسائل المدخلة من ملف أو من المدخلات القياسية. على سبيل المثال، يمكننا إنشاء ملف يسمى numbers.json بمحتوى التالي:

{"value": 1}
{"value": 2}
{"value": 3}
{"value": 4}
{"value": 5}

بعد ذلك، يمكننا تشغيل الأمر التالي:

grpc-curl http://localhost:5000 Calculator/Sum -d @numbers.json

يجب أن تبدو المخرجات كما يلي:

{
  "value": 15
}

بدلاً من ذلك، يمكننا استخدام الرمز - للإشارة إلى أن الرسائل المدخلة تأتي من المدخلات القياسية، ثم كتابة أو لصق الرسائل في المحطة، متبوعة بـ Ctrl+D لإنهاء الإدخال. على سبيل المثال:

grpc-curl http://localhost:5000 Calculator/Sum -d -
{"value": 1}
{"value": 2}
{"value": 3}
{"value": 4}
{"value": 5}
^D

يجب أن تكون المخرجات مماثلة لما سبق.

يدعم grpc-curl أيضًا طرق البث ثنائي الاتجاه، التي يمكن أن ترسل وتستقبل العديد من الرسائل في كلا الاتجاهين. على سبيل المثال، لنفترض أن لدينا طريقة بث ثنائي الاتجاه تُدعى Chat، التي تأخذ تيارًا من الرسائل كدخل وتعيد تيارًا من الرسائل كإخراج. يبدو كود الخادم لهذه الطريقة كالتالي:

public override async Task Chat(IAsyncStreamReader<Message> requestStream, IServerStreamWriter<Message> responseStream, ServerCallContext context)
{
    await foreach (var message in requestStream.ReadAllAsync())
    {
        Console.WriteLine($"تم الاستلام: {message.Text}");
        var reply = new Message { Text = $"صدى: {message.Text}" };
        await responseStream.WriteAsync(reply);
        Console.WriteLine($"تم الإرسال: {reply.Text}");
    }
}

لإجراء استدعاء لهذه الطريقة باستخدام grpc-curl، نحتاج إلى تقديم الرسائل المدخلة من ملف أو من المدخلات القياسية، ونحتاج إلى استخدام خيار -s للإشارة إلى أننا نريد تلقي الرسائل الإخراجية كتيار. على سبيل المثال، يمكننا إنشاء ملف يسمى chat.json بمحتوى التالي:

{"text": "مرحبًا"}
{"text": "كيف حالك؟"}
{"text": "وداعًا"}

بعد ذلك، يمكننا تشغيل الأمر التالي:

grpc-curl http://localhost:5000 Calculator/Chat -d @chat.json -s

يجب أن تبدو المخرجات كما يلي:

{
  "text": "صدى: مرحبًا"
}
{
  "text": "صدى: كيف حالك؟"
}
{
  "text": "صدى: وداعًا"
}

كما ترى، يقوم grpc-curl بإرسال كل رسالة إلى الخادم، ويطبع كل رد من الخادم، حتى تنتهي تدفق الإدخال.

لماذا تستخدم grpc-curl؟

grpc-curl هي أداة مفيدة لاختبار وتصحيح واجهات gRPC الخاصة بك، لأنها تتيح لك:

استدعاء أي نوع من طرق RPC، بما في ذلك طرق البث، من سطر الأوامر، دون الحاجة لكتابة أي شيفرة عميل.
استعراض المخطط الخاص بخدمات gRPC، إما عن طريق استعلام خادم يدعم الانعكاس من الخادم، أو عن طريق تحميل ملفات بروتوسيت.
تنسيق الإخراج بطرق مختلفة، مثل JSON أو XML أو نص عادي، مع الألوان والمسافات.
التعامل مع الرسائل المتداخلة والحقول المكررة بشكل أفضل من gRPCurl، وقبول المدخلات من الملفات أو المدخلات القياسية.
استخدام متغيرات البيئة للخيارات الشائعة، مثل عنوان URL للخادم، والرؤوس، وإعدادات TLS.
إنشاء مقتطفات رمزية لـ C#، Java، Python، و Go، لمساعدتك في كتابة شيفرة العميل الخاصة بك.

grpc-curl أيضًا سهل التثبيت والاستخدام، ويعمل على منصات متعددة، مثل Windows، Linux، و Mac OS. إنه متوافق مع كل من .NET Core و .NET Framework، ويدعم كل من بروتوكولات HTTP/1.1 و HTTP/2.

grpc-curl ليس فقط مفيدًا للمطورين، ولكن أيضًا للاختباريين، ومهندسي ضمان الجودة، ومهندسي DevOps، وأي شخص يحتاج إلى التفاعل مع خوادم gRPC. يمكن أن تساعدك في التحقق من وظائف وأداء وأمان وموثوقية واجهات برمجة التطبيقات الخاصة بك، وتحديد وإصلاح أي مشاكل أو أخطاء.

كيفية استخدام grpc-curl مع apidog؟

إذا كنت ترغب في رفع مستوى اختبار وتصحيح أخطاء gRPC الخاص بك، فقد ترغب في استخدام grpc-curl مع apidog، وهي أداة قوية ومرنة لوثائق واختبارات API.

Apidog هي أداة تتيح لك إنشاء وإدارة ومشاركة وثائق واختبارات واجهات برمجة التطبيقات، باستخدام واجهة بسيطة وبديهية. يمكنك استخدام apidog لتوثيق واختبار أي نوع من واجهات برمجة التطبيقات، بما في ذلك REST، SOAP، GraphQL، و gRPC.

button

مع apidog، يمكنك:

استيراد المخطط الخاص بواجهة برمجة التطبيقات من مصادر مختلفة، مثل OpenAPI، Swagger، WSDL، GraphQL، أو ملفات بروتوسيت.
إنشاء وتنظيم نقاط النهاية، الطرق، المعلمات، الرؤوس، والاستجابات الخاصة بواجهة برمجة التطبيقات، باستخدام محرر رسومي أو محرر كود.
إضافة أوصاف، أمثلة، تحقق، وتعليقات إلى عناصر واجهة برمجة التطبيقات، باستخدام Markdown أو HTML.
إنشاء وثائق API تفاعلية وجميلة، مع أمثلة حية، مقتطفات رمز، ومخططات.
إنشاء وتشغيل اختبارات واجهة برمجة التطبيقات، باستخدام أدوات تشغيل الاختبارات المدمجة أو أداة سطر الأوامر.
مراقبة وتصحيح مكالمات واجهة برمجة التطبيقات الخاصة بك، باستخدام وكيل مدمج أو ملحق المتصفح.
التعاون ومشاركة مشاريع واجهة برمجة التطبيقات الخاصة بك مع فريقك أو عملائك، باستخدام منصة سحابية أو حل مستضاف ذاتيًا.

البث من الخادم

كما يشير الاسم، ينطوي البث من الخادم على إرسال بيانات استجابة متعددة في طلب واحد. على سبيل المثال، قد ينطوي على الاشتراك في جميع بيانات أسعار المعاملات للأسهم ضمن إطار زمني مدته دقيقة واحدة.

البث من العميل

في هذا الوضع، يمكن أن يرسل العميل باستمرار العديد من رسائل الطلب إلى الخادم دون الانتظار للحصول على ردود فورية. بعد معالجة جميع الطلبات، يرسل الخادم رسالة رد واحدة إلى العميل. هذه الطريقة مناسبة لنقل كميات كبيرة من البيانات بكفاءة بطريقة متدفقة، مما يساعد على تقليل الكمون وتحسين تبادل البيانات.

البث ثنائي الاتجاه

يمكن أن يمكّن البث ثنائي الاتجاه العملاء والخوادم من إنشاء اتصال ثنائي الاتجاه دائم ونقل العديد من الرسائل في نفس الوقت. يُستخدم عادةً في الألعاب عبر الإنترنت وبرامج مكالمات الفيديو في الوقت الحقيقي، وهو مناسب لتواصل في الوقت الحقيقي وسيناريوهات نقل بيانات كبيرة. بعد بدء المكالمة، يحافظ العميل والخادم على جلسة بينهما ويتلقيان ردودًا في الوقت الحقيقي بعد إرسال محتويات طلب مختلفة.

التعاون في واجهات gRPC

يمكن أن يولد Apidog مستندات واجهة gRPC قابلة للقراءة من ملفات .proto، مما يسهل التعاون على الواجهات. انقر على زر القائمة على الجانب الأيمن من الواجهة للحصول على رابط التعاون ومشاركته مع أعضاء الفريق الآخرين لتوحيد نهج تصحيح الواجهة.

إنشاء حساب Apidog، وتسجيل الدخول إلى تطبيق Apidog على الويب.
إنشاء مشروع واجهة برمجة تطبيقات جديد، وإعطائه اسمًا ووصفًا.
استيراد مخطط gRPC الخاص بك من ملف بروتوسيت، أو إنشاؤه يدويًا باستخدام المحرر الرسومي أو محرر الكود.
إضافة نقاط النهاية، الطرق، المعلمات، الرؤوس، والاستجابات الخاصة بـ gRPC، وملء التفاصيل والأمثلة.
إنشاء وثائق واجهة برمجة التطبيقات الخاصة بك، وعرضها في المتصفح أو تصديرها كملف PDF أو HTML.
إنشاء اختبارات واجهة برمجة التطبيقات الخاصة بك، وتشغيلها باستخدام أداة اختبار مدمجة أو أداة سطر الأوامر.
مراقبة وتصحيح مكالمات واجهة برمجة التطبيقات الخاصة بك، باستخدام وكيل مدمج أو ملحق المتصفح.
مشاركة مشروع واجهة برمجة التطبيقات الخاص بك مع فريقك أو عملائك، باستخدام منصة سحابية أو حل مستضاف ذاتيًا.

لتعلم المزيد حول Apidog، وكيفية استخدامه مع grpc-curl، يمكنك زيارة موقع Apidog، أو مراجعة وثائق Apidog.

الخاتمة

grpc-curl هي أداة سطر أوامر تتيح لك التفاعل مع خوادم gRPC بطريقة بسيطة وبديهية. تعتمد على gRPCurl، لكنها تضيف بعض الميزات والتحسينات التي تجعلها أكثر سهولة في الاستخدام وقوة. يمكنك استخدام grpc-curl لاختبار وتصحيح واجهات gRPC الخاصة بك، ولإنشاء مقتطفات رمزية لشيفرة العميل الخاصة بك.

كما أن grpc-curl متوافقة مع apidog، أداة تستند إلى الويب لوثائق واختبارات واجهة برمجة التطبيقات. يمكنك استخدام apidog لإنشاء وإدارة ومشاركة مشاريع واجهة برمجة التطبيقات الخاصة بك، ولتشغيل ومراقبة اختبارات واجهة برمجة التطبيقات الخاصة بك.

إذا كنت مطورًا يعمل مع gRPC، أو إذا كنت مهتمًا بمعرفة المزيد عن gRPC، يجب عليك بالتأكيد تجربة grpc-curl و Apidog. يمكن أن تساعدك في تحسين جودة وقابلية استخدام واجهات برمجة التطبيقات الخاصة بك، وجعل عملية التطوير أكثر سهولة وسرعة.

button