نظرة عامة

عميل HTTP آمن من نوع RxJS لـ TypeScript ومحولات Next.js/RSocket الاختيارية.

@byeolnaerim/typed-rx-httpهو عميل HTTP يقوم بحقن أنواع Paths بأسلوب OpenAPI، ويتحقق من URL وطريقة HTTP ومعلمات path/query وجسم الطلب كأنواع، ويعيد النتائج كـ RxJS Observable.

ما كنت أريده من هذه المكتبة لم يكن تجريد HTTP معقد. كان الهدف هو استيراد الوظائف التي تم إنشاؤها واستدعاؤها مباشرة دون الحاجة إلى إعادة كتابة URL و DTO الطلب/الاستجابة المكتوبة في الخلفية.

طريقة الاستخدام الأساسية لـ Core

تتضمن التدفق الأساسي إعداد أنواع Paths بأسلوب OpenAPI، وإنشاء HeaderStore إذا لزم الأمر، ثم إنشاء عميل باستخدام createHttpClient<Paths>() واستدعاء callApi<R>(). لا تعتبر مولدات الخدمة التلقائية أو WebFlux backend شرطًا أساسيًا لهذا التدفق.

يتم تحديد نوع الطلب من Paths، ويختار المستدعي نوع الاستجابة من R في callApi<R>(). لا يتم فرض ResponseWrapper معين. يتم إضافة NDJSON وCSR cache ومصادقة الجلسة وميزات Next.js وRSocket فقط عند الحاجة.

إنشاء OpenAPI التلقائي هو ميزة اختيارية.

نص Node التلقائي الذي ينشئ أنواع TypeScript وملفات الخدمة من Swagger/OpenAPI JSON هو ميزة اختيارية منفصلة عن عميل HTTP Core. لا يحتاج المستخدمون العاديون لـ Core أو /next أو /rsocket إلى تشغيل generator.

قصة الأصل

أستخدم Next.js و TypeScript في الواجهة، و Java و WebFlux في الخلفية. أثناء إنشاء المشروع بهذا المزيج، كان هناك الكثير من التكرار في كتابة نفس المحتوى في الجانبين.

في الخلفية، يتم إنشاء الكيانات و DTO الطلب/الاستجابة وكتابة النقاط النهائية. ولكن لاستدعاء تلك النقطة النهائية في الواجهة، كان يجب إعادة كتابة URL، وإنشاء نوع أو واجهة مشابهة لـ DTO الخلفية. بصراحة، لم يكن هناك فرق بين كتابة ما كتبته في الخلفية مرة أخرى في الواجهة.

هذا التكرار لا يزيد فقط من كمية الكود، بل يزيد أيضًا من احتمال تفويت تغيير في حقل أو URL في أحد الجانبين. لذلك، شعرت بشدة بالحاجة إلى إنشاء مواصفات REST API في الخلفية بشكل يمكن التنبؤ به في كود عميل HTTP في الواجهة.

في هذه العملية، تم تطبيق نموذج أولي لـ nplauction.com للخلفيةreactive-mongo-dslوwebflux-fe-dev-assistantنموذج أولي لـ typed-rx-http في الواجهة. لم يبدأ typed-rx-http كفكرة منفصلة، بل نشأ كإضافة أثناء إنشاء webflux-fe-dev-assistant.

طريقة الاستخدام في مشروع إنشاء Swagger التلقائي.

في المشاريع التي تستخدم إنشاء خدمة Swagger تلقائيًا، في كود الشاشة createHttpClientلا أكتب URL في كل مرة. أعدت إنشاء commonService.tsقم بإنشاء محول HTTP عام مملوك للمشروع مرة واحدة، واستخدم فقط وظائف الخدمة التي تم إنشاؤها من OpenAPI. commonService.ts هو اسم الملف الذي يحدده المشروع وليس اسم الملف الذي تنشئه المكتبة، ويمكنك التحقق من الكود الكامل أولاً في وثيقة بدء الاستخدام/عميل HTTP.

const response = await firstValueFrom(
  workplacesSearch({ params: { keyword: "kim" } }),
);

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

أين سيكون الأنسب؟

إذا كانت الواجهة الخلفية والواجهة الأمامية مفصولة، ويمكن للواجهة الخلفية تقديمswagger.json، يمكنك تقليل العمل المتكرر في واجهة TypeScript الأمامية. إذا كنت تستخدم نقطة النهاية الوظيفية Java WebFlux، يمكنك دمج webflux-fe-dev-assistant لربط إنشاء الوثائق بإنشاء الخدمة.

نواة typed-rx-http ليست معتمدة على WebFlux. متوافقة مع مواصفات OpenAPI بغض النظر عن تنفيذ الواجهة الخلفية في TypeScript المسارات إذا كان هناك نوع، يمكن استخدامه لتقليل كتابة عنوان URL من نوع سلسلة ونوع الطلب يدويًا في كل مرة. يمكن استخدام عميل RSocket مباشرة من نقطة الدخول /rsocket، ويمكن استخدام مولد AsyncAPI فقط في المشاريع التي تحتاج إلى إنشاء خدمات route/request/response تلقائيًا.

النطاق الذي تم التحقق منه حاليًا

يمكن أن تختلف نتائج الإنشاء بناءً على هيكل وثائق OpenAPI أو AsyncAPI والأداة المستخدمة في الإنشاء. لا نضمن مخرجات جميع الأطر وأدوات إنشاء الوثائق، لذا تحقق من النتائج التي تم إنشاؤها قبل التطبيق.swagger.json أوasyncapi-rsocket.jsonالذي تم إنشاؤه أولاً.

المستودع: github.com/joohyoungkim19940805/typed-rx-http