اليوم ، تستخدم الأساليب التالية على نطاق واسع لوصف تفاعل المتصفح والخادم ، مثل OpenApi و GraphQL.
في هذه المقالة ، سأتحدث عن محاولتنا لإنشاء واجهة برمجة تطبيقات REST مكتوبة بشكل ثابت وحفظ الفريق الأمامي من كتابة التعليمات البرمجية لكتابة طلبات البيانات ، وتبسيط الاختبار وتقليل عدد الأخطاء المحتملة.
هذه الأدوات تساعدنا:
- تصميم واجهات برمجة التطبيقات (APIs) وفقًا للمعايير بناءً على المواصفات
- أنشئ رمزًا ثابتًا وقابل لإعادة الاستخدام لواجهة برمجة التطبيقات لديك بأي لغة تقريبًا
- تحسين تجربة المطور من خلال وثائق API التفاعلية
- إجراء اختبارات وظيفية بسهولة على واجهات برمجة التطبيقات.
- قم بإنشاء وتطبيق أفضل إرشادات نمط واجهة برمجة التطبيقات في بنية واجهة برمجة التطبيقات
الفكرة الرئيسية لهذا النهج هي أن وجود أنواع البيانات نفسها على العميل والخادم ، يصعب على المطورين في الفريق ارتكاب خطأ على العميل ، وباستخدام إنشاء الشفرة ، لن يحتاج الأمر إلى كتابتها وصيانتها وبالتالي تغطيتها باختبارات الوحدة.
لن يتم ترجمة تطبيق الواجهة الأمامية إذا ارتكب الأمر خطأ في أنواع البيانات التي يقبلها / يوفرها REST API.
وبالتالي ، بعد الحصول على كود مكتوب بشكل ثابت على العميل ، يمكننا التخلص من الأخطاء الغبية المتعلقة بالأنواع والتأكد من أن كودنا متوافق تمامًا مع الإصدار الحالي من API.
من أجل الحصول على جميع المزايا المذكورة أعلاه لواجهة برمجة التطبيقات التي تمت كتابتها بشكل ثابت ، نحتاج إلى استخدام مُنشئ تعليمات برمجية يمكنه ، وفقًا لمواصفات OpenAPI ، إنشاء ملفات وصف لأنواع Typescript هذه ملفات * .d.ts.
يستخدم مشروعنا بنية microservice ويتم كتابة الواجهة الخلفية بالكامل في .NET ، لذلك استخدمنا NSwag لإنشاء عملاء API للواجهة الأمامية / الخلفية. تتيح لك هذه الأداة إنشاء مستندات OpenAPI ، والتي بدورها تُستخدم بالفعل لإنشاء رمز العميل.
هندسة معمارية
بشكل عام ، تتكون عملية إنشاء الكود من عدة مراحل:
- OpenAPI Document Generation
- إنشاء رمز باستخدام مستند OpenAPI
في حالتنا ، تتم كتابة الواجهة الخلفية باستخدام .Net وترجع لغة تطوير C # الرئيسية إلى اختيار الأدوات. نستخدم نفس الأداة المسماة NSwag لإنشاء مستندات OpenAPI وعملاءها.
الشكل 1 الشكل 1. هندسة حل لتوليد بقية رمز العميليوضح الشكل:
- Microservice 1 ... N - microservices توفير API
- NSwag - إنشاء مستند OpenAPI من رمز واجهة برمجة تطبيقات microservice (يمكن كتابة خدمة microservice بأي لغة توجد بها أداة لإنشاء مستند OpenAPI)
- NSwag - إنشاء رمز واجهة برمجة تطبيقات عميل لوثائق OpenAPI (هناك العديد من الأدوات التي يمكنك اختيار الأداة التي تناسب تكدس التكنولوجيا الخاصة بك أكثر)
- مستند OpenAPI - تم إنشاء وثائق OpenAPI
- API Client 1 ... N - العملاء الذين يستهلكون بيانات واجهة برمجة التطبيقات (يمكن تنفيذها على أي لغة تدعم المولد الخاص بـ NSwag C # و Typescript)
- SPA 1 ... N - تطبيق Frontend ، في حالتنا React (NSwag تدعم جيل العميل لـ AngularJS / Angular ، React (جلب) ، JQuery (وعد / معاودة الاتصال) ، أوريليا)
تسلسل الإجراءات كما يلي:
- بمناسبة وحدة تحكم API مع العلامة المناسبة / سمة / ديكور يعتمد على لغة API
- قم بإنشاء وثائق رمز OpenAPI API
- إنشاء رمز واجهة برمجة تطبيقات العميل باستخدام وثائق OpenAPI
- دمج رمز واجهة برمجة تطبيقات العميل في تطبيق واجهة برمجة تطبيقات مستهلك البيانات
الوثائق
لكي نتمكن من إنشاء رمز ، نحتاج إلى وصف أنواع القيم المقبولة / المرتجعة لوحدة تحكم API ، في هذا المثال ، حيث يتم استخدام لغة C # ، باستخدام سمة SwaggerOperation ، وضعنا علامة على طريقة ستُرجع قائمة بجميع الاستبيانات على الخادم ، في رمز العميل ، طريقة للحصول على سيتم استدعاء البيانات GetAllQuestionnaires:
[HttpGet, Route("")] [SwaggerOperation(OperationId = "GetAllQuestionnaires")] [SuccessResponse(typeof(IEnumerable<QuestionnaireViewModel>))] public IEnumerable<QuestionnaireViewModel> Get() { var surveys = _questionnaireRepository.GetAll(); return surveys.Select(QuestionnaireViewModel.ToViewModel).ToArray(); }
سرد 1 مثال C # رمز تصف طريقة APIثم ، باستخدام NSwag ، نقوم تلقائيًا بإنشاء مستند OpenAPI يحتوي على جميع نقاط نهاية واجهة برمجة التطبيقات التي تم تمييزها بالسمات المقابلة في رمز الواجهة الخلفية.
الشكل 2 وثيقة OpenAPIوبالتالي ، تمكنا من إنشاء مستندات محدثة تلقائيًا دائمًا لواجهة برمجة التطبيقات لدينا.
الكتابة
تحتوي وثائق OpenAPI على معلومات حول أنواع البيانات التي سيتم إرسالها / استلامها بواسطة وحدة التحكم الخلفية. وبالتالي ، على الجانب الأمامي ، يمكننا الاعتماد تمامًا على الأنواع التي توفرها الخلفية لنا وليس إنشاء أنواع خاصة بنا ، ولكن استيرادها من رمز العميل الذي تم إنشاؤه باستخدام مستند OpenAPI.
على سبيل المثال ، يحتوي المستند على معلومات حول نوع QuestionnaireViewModel (هنا يتم تقديم المواصفات في نموذج HTML لسهولة القراءة)
الشكل 3 مثال على نموذج البيانات في مستند OpenAPIوالخطوة التالية هي تمرير هذه المعلومات إلى رمز تطبيق الواجهة الأمامية.
توليد الشفرة
نستخدم أيضًا NSwag لإنشاء رمز واجهة برمجة تطبيقات العميل. عند الإدخال ، يتلقى مستند OpenAPI ويقوم بإنشاء رمز واجهة برمجة تطبيقات العميل وفقًا للإعدادات المحددة. للأمام ، بجانب الرمز الذي تم استلامه ، نضيف package.json ونرسله إلى سجل npm المحلي.
كما ترون من قائمة الرموز الخلفية (انظر القائمة 1) ، وضعنا علامة على طريقة التحكم باستخدام السمة
[SwaggerOperation(OperationId = "GetAllQuestionnaires")]
ستصبح العملية المحددة في السمة C # في حالتنا هي اسم طريقة العميل.
الشكل 4 مثال على استخدام API العميل الذي تم إنشاؤهأيضًا ، بعد إنشاء العميل ، تلقينا ملف d.ts يحتوي على الأوصاف المقابلة لأنواع البيانات ، الموضحة في الشكل أدناه.
الشكل 5 مثال على وصف نوع البيانات في ملف .d.tsالآن ، في رمز التطبيق للواجهة الأمامية ، يمكنك استخدام أنواع البيانات التي يتم تصديرها من رمز API للعميل واستخدام الإكمال التلقائي في محرر الكود ، يتم عرض مثال في الشكل أدناه.
الشكل 6 مثال على استخدام معلومات نوع بيانات واجهة برمجة تطبيقات العميلتعمل جميع أجهزة التحقق من صحة نوع البيانات ذات الصلة في Typescript أيضًا.
مثال في الأشكال أدناه.
الشكل 7 مثال العميل التحقق من صحة نوع بيانات API
الشكل 8 مثال على التحقق من صحة نوع بيانات واجهة برمجة التطبيقات للعميلالنتائج
بعد تطبيق هذا النهج ، تلقينا المزايا التالية:
- أخطاء نوع البيانات أقل
- كود أقل ، عمل أقل للتصحيح ، الاختبار ، الدعم
- دائما ما يصل إلى تاريخ الوثائق لجميع أساليب API لكل من microservices
- القدرة على اختبار أتمتة API
- نظام نوع موحد للواجهة الأمامية والخلفية
مراجع