بدء سريع

• ضمان استقرار نوع route (الطلب) عن طريق حقن نوع Paths بأسلوب OpenAPI المستمد من Swagger/OpenAPI / AsyncAPI / مخططات مخصصة.
• تقوم جميع واجهات برمجة التطبيقات بإرجاع RxJS Observable.
• النواة مستقلة عن الإطار (لا تعتمد على Next.js)
• الميزات الخاصة بـ Next.js مفصولة في نقطة الدخول @byeolnaerim/typed-rx-http/next → تحتاج Next.js فقط عند استيراد /next.
• الميزات الخاصة بـ RSocket مفصولة في نقطة الدخول @byeolnaerim/typed-rx-http/rsocket → تحتاج حزمة RSocket فقط عند استيراد /rsocket.

npm

Core (مستقل عن الإطار)

محول Next.js (اختياري)

لا تستورد /next في المشاريع التي لا تستخدم Next.js.

محول RSocket (اختياري)

قم بتثبيت حزمة peer فقط في المشاريع التي تستخدم RSocket.

لا تستورد /rsocket في المشاريع التي لا تستخدم RSocket.

Paths في createHttpClient<Paths>() تعبر عن "مواصفات الطلب (route)". تُسمى عادةً paths في الوثيقة، لكن ليس من الضروري أن تكون OpenAPI/Swagger، أو أن يكون اسمها paths.

ومع ذلك، تستخدم النواة داخليًا قيد OpenApiPathsLike، لذا يجب أن تكون Paths مشابهة للشكل أدناه مثل OpenAPI paths.

• المفتاح الأعلى: سلسلة مسار URL (مثل: "/users/{id}")
• المفتاح الفرعي: طريقة HTTP (get/post/put/delete/patch …)
• يوجد داخل كل طريقة حقول مثل parameters.query/path/header/cookie وrequestBody وresponses (أو never)

تشير النواة بشكل أساسي إلى الحقول أدناه لتكوين نوع ServiceArguments.

• url: keyof Paths
• method: keyof Paths[url]
• queryString: parameters.query
• pathVariable: parameters.path
• body: requestBody

مثال: مخرجات openapi-typescript عادة ما تكون وفقًا للمواصفات التالية (بعض الاختصارات).

HeaderStore هو مخزن بسيط في الذاكرة لإدارة الرؤوس الأساسية في CSR.

• headerStore اختياري، ولكن يُوصى بإضافته إذا كنت ترغب في استخدام الرؤوس الأساسية/مصادقة الجلسة في CSR.
• headersProvider يُستخدم عندما تحتاج إلى حساب الرؤوس لكل طلب مثل SSR/تعدد المستأجرين.

نوع الطلب (url/method/pathVariable/queryString/body) يتم تحديده من النوع الذي تم حقنه في createHttpClient<Paths>() (عادةً ما يكون مسارات OpenAPI). نوع الاستجابة يتم اختياره من قبل المستدعي في callApi<R>() كـ R جنريك (النواة لا تستنتج تلقائيًا من responses).

هذه المكتبة لا تفرض تغليف الاستجابة. يمكنك اختيار شكل الاستجابة بشكل جنريك لكل API.

استجابة مغلفة

استجابة غير مغلفة

عندما يقدم الخادم NDJSON (JSON واحد في كل سطر)، استخدم callApiStream. إذا لم يكن هناك رأس Accept، يتم تعيين application/x-ndjson كقيمة افتراضية.

الوظائف التي يوفرها createCsrCache<CacheName>():

• callApiCsrCache(callApiFn, serviceArgs, cacheOptions)
• removeCsrCache(cacheName) — يدعم جميع أسماء نوع الذاكرة + السلاسل النصية.

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

العمليات:

• الحفاظ على Authorization في headerStore
• مزامنة الرمز باستخدام ensureToken$() (/api/auth/token)
• عند حدوث 401، حاول التحديث مرة واحدة (/api/auth/token/refresh) ثم أعد محاولة الطلب الأصلي.
• عند فشل التحديث، قم بتسجيل الخروج (/api/auth/logout) ثم نقل الخطأ.
• تغيير حالة تسجيل الدخول يتم معالجته خارجيًا بواسطة onLoginChange callback.

إذا كنت بحاجة فقط لمزامنة الرمز بدون تحديث/إعادة محاولة:

إذا لم يكن 2xx، يتم رمي HttpResponseError (بما في ذلك status و response و args و data).

التوافق مع الأنظمة القديمة: إذا كان جسم الخطأ على شكل { resultType: ... }، يتم رمي هذا الكائن كما هو.

redirectToUnauthorizedOnServer401

redirectToUnauthorizedOnServer401 هو التنفيذ الافتراضي (دالة مساعدة) الذي يقوم بإعادة التوجيه عند حدوث 401 في بيئة SSR لـ Next.js (App Router).

قواعد التشغيل (ثابتة):

• وجهة إعادة التوجيه: /unauthorized
• queryString: redirect_uri=<الصفحة الحالية> + logout=true
• يتم قراءة الصفحة الحالية من رأس x-page-url (إذا لم يكن موجودًا، يتم استخدام /)

أي، استخدم قواعد المسار/الاستعلام أعلاه كما هي فقط عندما تتطابق مع المشروع. إذا كان المسار مختلفًا أو كانت قواعد الاستعلام مختلفة، يمكنك تنفيذ onServer401 مباشرة كما هو موضح أدناه.

callApiSsrCache

مساعد ذاكرة التخزين المؤقت SSR القائم على next/cache(unstable_cache) من Next.

• GET + cacheTime > 0 → force-cache + revalidate
• بخلاف ذلك → no-store
• حقن ملفات تعريف الارتباط / التفويض لكل طلب باستخدام headersProvider
• عند حدوث 401، يتم تنفيذ onServer401 إذا كان موجودًا (عادةً redirect())

ملف rxjsHttpService.ts أدناه هو محول HTTP العام للمشروع المشار إليه في مثال المولد لاحقًا. هذا ليس ملفًا تم إنشاؤه بواسطة المكتبة، بل يتم إدارته مباشرة من قبل المشروع، ويصدر core client + session auth + CSR cache + SSR cache helper في مكان واحد. أدناه هو الكود الكامل.

createHttpClient<Paths>(options)

الإرجاع:

• callApi<R>(args): Observable<R>
• callApiStream<RChunk>(args): Observable<RChunk>
• uploadFile({ file, url, ifNoneMatch?, headers? }): Observable<Response>
• createSSEObservable<R>(args): Observable<R>

الخيارات:

• baseUrl: string
• headerStore?: HeaderStore
• headersProvider?: () => Record<string, string> | Promise<Record<string, string>>
• dropAuthWhenCacheControl?: boolean (القيمة الافتراضية: true)
• onServer401?: () => void | Promise<void>

createCsrCache<CacheName>()

get(), set(), merge(), remove(), clear()

createCsrCache<CacheName>()

• callApiCsrCache(callApiFn, serviceArgs, cacheForService)
• removeCsrCache(cacheName) (النوع + السلسلة)

تصديرات Stream & utility

• withSessionAuth(), withEnsureToken()
• ensureToken$(), refreshToken$(), logout$()

• استخدام fetch / Response API (rxjs/fetch)
• البث (NDJSON) يتطلب ReadableStream + TextDecoder
• SSE يتطلب EventSource

يتوفر في معظم المتصفحات الحديثة وبيئة تشغيل Next.js. قد تحتاج بيئات تشغيل Node المخصصة إلى polyfill.

تقدم هذه الحزمة، بالإضافة إلى عميل HTTP في وقت التشغيل، سكربت Node لإنشاء كود النوع/الخدمة من JSON OpenAPI/Swagger. هذا السكربت هو ميزة اختيارية.

لا يحتاج المستخدمون العاديون لـ @byeolnaerim/typed-rx-http، /next، /rsocket إلى تشغيل هذا السكربت، ولا يحتاجون إلى تثبيت openapi-typescript.

عزل الاعتماديات

تتطلب إنشاء أنواع OpenAPI استخدام openapi-typescript CLI. لكن هذه الحزمة لا تضيف openapi-typescript إلى الاعتماديات العامة.

تستخدم مكتبة @byeolnaerim/typed-rx-http نفسها TypeScript 6.0.3 كـ devDependencies.typescript. تحافظ نقاط الدخول إلى typed-rx-http، /next، /rsocket وبناء المكتبة على هذا المعيار TypeScript 6.0.3.

ومع ذلك، قد يتطلب openapi-typescript إصدارًا معينًا من TypeScript 5.x، لذا يتم تشغيل سكربت OpenAPI auto node فقط في بيئة تنفيذ مؤقتة منفصلة مع openapi-typescript و [email protected]. لا تغير هذه البيئة المؤقتة devDependencies.typescript 6.0.3 للمكتبة، ولا تستخدم إصدار typescript أو openapi-typescript المثبت في مشروع المستخدم.

القيمة الافتراضية هي إنشاء وتنفيذ الأوامر أدناه فقط في وقت تشغيل السكربت التلقائي.

لذا، لا تتغير طريقة الاستخدام نفسها. يمكنك استدعاء سكربت auto node كما هو معتاد، وسيتم استخدام بيئة TypeScript 5.9.3 المعزولة فقط في مرحلة إنشاء نوع OpenAPI. المستخدمون الذين لا يستخدمون السكربت التلقائي غير مقيدين بـ openapi-typescript أو TypeScript 5.9.3.

إذا لزم الأمر، يمكنك تثبيت الأوامر مباشرة باستخدام openApiTypescriptCommand.

أو يمكنك تغيير إصدار الحزمة التي تشكل الأوامر الأساسية فقط.

الملفات التي يتم إنشاؤها

الإعدادات الافتراضية تنشئ الملفات أدناه.

apiUnionArrays.ts ينشئ مصفوفات ثابتة للـ enum في مخطط OpenAPI بالإضافة إلى enum للمعلمات في الاستعلام، المسار، الرأس، وملف تعريف الكوكيز. كما يعالج items.enum لمعاملات الاستعلام.

مراقبة EventStream

طلب HTTP لمرة واحدة

إنشاء من ملف محلي

يتم كتابة كود الخلفية كما هو معتاد. في هذا المثال، يتم استلام الاسم كمتغير مسار، والرسالة كمعامل استعلام. Monoويتم الرد.

يتم استلامها من الخلفية لإنشاء ملف النوع والخدمة. يمكن استدعاء هذه العملية مرة واحدة عند تشغيل خادم التطوير أو ربطها بسكربت المراقبة. swagger.json3. إرسال الطلب باستخدام الوظيفة التي تم إنشاؤها.

يمكنك الضغط على الزر لفتح شاشة التنفيذ على اليمين. بعد تغيير القيم، جرب الضغط على زر الطلب. النتيجةو الجزء المرئي في المشروع الفعلي.كود الواجهة الأمامية لا يحتوي كود الشاشة على سلسلة URL أو واجهة استجابة. كلاهما موجود في Swagger.كود الخلفية