OpenAPI & مولد الخدمة
برنامج نصي اختياري يتم توفيره بشكل منفصل عن Core HTTP client. يستخدم فقط عند إنشاء أنواع TypeScript وملفات الخدمة من OpenAPI/Swagger JSON.
وظيفة اختيارية: غير ضرورية لاستخدام Core
لا يحتاج مستخدمو @byeolnaerim/typed-rx-http أو /next أو /rsocket إلى تشغيل هذا البرنامج النصي أو تثبيت openapi-typescript في مشروعهم.
عزل اعتماد openapi-typescript
تتطلب عملية إنشاء أنواع OpenAPI استخدام openapi-typescript CLI، لكن الحزمة لا تضيفها إلى الاعتمادات العامة. تحافظ devDependencies.typescript الخاصة بـ typed-rx-http على معيار TypeScript 6.0.3، وتستخدم بيئة npx مؤقتة منفصلة فقط في برنامج نصي auto node الخاص بـ OpenAPI.
في مرحلة إنشاء OpenAPI الأساسية، يتم تشغيل openapi-typescript و [email protected] معًا، لذا لا يتم تغيير أو استخدام إصدار TypeScript/openapi-typescript المثبت في مشروع المستخدم.
إذا لزم الأمر، يمكن تثبيت الأمر الكامل على openApiTypescriptCommand.
أو يمكنك تغيير إصدار الحزمة فقط الذي يشكل الأمر الأساسي.
أولاً: إعداد ملف المشروع الذي سيشير إليه commonServiceFile
يجب فهم هذا الملف قبل ظهور commonServiceFile في مثال المولد. commonServiceFile هو مسار الملف الذي يمتلكه المشروع والذي تستورد منه الخدمة المولدة الوظائف HTTP المشتركة. يمكن اختيار اسم الملف بحرية مثل rxjsHttpService.ts أو commonService.ts.
الكود الكامل للحد الأدنى من الشكل المكتمل
الملف أدناه ينشئ createHttpClient مرة واحدة في المشروع ويصدر callApi و callApiStream لإعادة استخدامهما بواسطة الخدمة المولدة. إذا لم تكن بحاجة إلى ذاكرة التخزين المؤقت أو مصادقة الجلسة، يمكنك البدء من هذا الهيكل.
rxjsHttpService.ts
tsالكود الكامل بما في ذلك ذاكرة التخزين المؤقت للجلسة/CSR/SSR
لتوسيع الخدمة المولدة لاستخدام callApiClientCache أو callApiServerCache أو لمعالجة رأس الطلب ومصادقة الجلسة بشكل مشترك في Next.js، قم بتوسيع الشكل الكامل التالي.
rxjsHttpService.ts
tsطريقة التنفيذ
الملفات التي يتم إنشاؤها
الإعدادات الافتراضية تنشئ الملفات أدناه.
apiUnionArrays.tsينشئ مصفوفة ثوابت readonly ليس فقط لـ OpenAPI schema enum ولكن أيضًا لـ query و path و header و cookie parameter enum، ويعالج أيضًا items.enum لمتغيرات المصفوفة.
اختياري: ربط Swagger الخلفي بـ commonService للمشروع
من هنا فصاعدًا، هذا مثال على ربط المولد بمشروع حقيقي. WebFlux/webflux-fe-dev-assistant هو مجرد طريقة واحدة لتوفير Swagger وليس اعتمادًا ضروريًا.
إعداد وثيقة Swagger
يمكن أن تكون Swagger من Springdoc، أو أدوات OpenAPI أخرى، أو ملف كتبته بنفسك. إذا كنت تستخدم نقطة النهاية الوظيفية WebFlux، webflux-fe-dev-assistantيمكن أيضًا استخدام طريقة تقديم وثيقة Swagger.
مثال على إنشاء خيارات محددة في المشروع
يمكنك تحديد نقطة النهاية الخلفية، وswagger.json الذي سيتم تخزينه، ومسار إخراج النوع/الخدمة و commonServiceFile وفقًا لبنية المشروع.
generateSwagger.cjs
jsفي البيئات التي لا يمكن فيها تلقي الوثائق عبر HTTP، يمكنك استخدام نفس خيارات الإخراج مع توليدSwaggerمنملف.
commonServiceFile هو مسار الهدف للاستيراد
commonServiceFileهو مسار الملف الذي يمتلكه المشروع والذي تستورد منه الخدمة المولدة callApi و callApiStream و cache wrapper. ليس خيارًا لإنشاء أو الكتابة فوق هذا الملف.
ApiBusinessService.ts
tsمثال على نتائج الإنشاء في المشروع
الملف العام المحدد بـ commonServiceFile مثل rxjsHttpService.ts يتم إدارته مباشرة من قبل المشروع. يتم إعادة إنشاء النتائج تحت auto و @types/auto عند تغيير الوثيقة.
قواعد أسماء الملفات والأسماء الدالة
يتم تحديد اسم ملف الخدمة من أول مقطعين من URL، ويتم تحديد اسم الدالة من المقطع الثالث وما بعده. يتم تضمين المتغيرات في اسم الدالة بشكل By + PascalCase.
GET /api/business/workplaces/search
ApiBusinessService.ts → workplacesSearch({ params })
GET /api/business/workplaces/{id}
ApiBusinessService.ts → workplacesById({ path })
GET /api/orders/history/search
ApiOrdersService.ts → historySearch({ params })
POST /oauth2/login
Oauth2LoginService.ts → post({ body })
معلمات استدعاء دالة الإنشاء
GeneratedServiceUsage.tsx
tsxمفتاح معلمات الاستعلام للخدمة المولدة هو params، والمتغيرات في المسار هي path، وجسم الطلب هو body. يتم تحويل كل من queryString و pathVariable و body إلى ServiceArguments داخل دالة الإنشاء.