نظرة عامة
تشرح الخلفية والمبادئ التي حولت العمل التطويري المتكرر، مثل كتابة نفس عقد API ونوعه مرتين أثناء تطوير الواجهة الأمامية والخلفية، إلى إنشاء قائم على المصدر.
قصة الأصل
أعمل على الواجهة الخلفية والواجهة الأمامية معًا. عند إنشاء ميزة، كتبت نقطة النهاية وDTO الطلب/الاستجابة في Java WebFlux، ثم كان علي كتابة نفس URL ونوع TypeScript في الواجهة الأمامية. لتطابق وثيقة Swagger مباشرة، كان يتعين علي نقل المعلومات الموجودة بالفعل في الواجهة الخلفية مرة أخرى بتنسيق مختلف.
أكبر عنق زجاجة كان إعادة كتابة عقد API الذي تم إنشاؤه في الواجهة الخلفية إلى شكل يمكن للواجهة الأمامية استخدامه. إذا تم تعديل أي من URL، طريقة HTTP، معلمات path/query أو هيكل الطلب/الاستجابة بشكل مختلف في الجانبين، اكتشفنا المشكلة بعد وقت طويل من التجميع. كانت المشكلة أكبر من مجرد كونها مزعجة، حيث كانت عدم التوافق الناتجة عن إدارة نفس المحتوى مرتين من قبل البشر مشكلة أكبر.
أردت أيضًا تقليل التكرار عند إنشاء RouterFunction وhandler جديدة. إذا أضفت مرجعًا مثل ApiAccountHandler::search إلى الموجه، اعتقدت أنه يجب أن يتم إنشاء هيكل class وmethod handler غير الموجود تلقائيًا.
لذلك تم إنشاء Swagger/OpenAPI، وإنشاء هيكل handler، وإنشاء enum حقل Mongo أولاً، ثم أضفنا إنشاء AsyncAPI أثناء استخدام RSocket. على الرغم من أن كل منها يبدو فكرة منفصلة، إلا أن نقطة البداية هي نفسها. الهدف هو عدم إعادة كتابة الحقائق التي تم تدوينها بالفعل في مصدر الواجهة الخلفية، والسماح للأدوات بتوليد الأجزاء القابلة للقراءة من قبل الآلة.
فلسفة التطوير
أستند إلى مصدر الواجهة الخلفية
استخدم المعلومات الموجودة بالفعل في RouterFunction وhandler وDTO وentity كمصدر لوثائق API والكود المولد. النقطة الأساسية هي عدم إدارة نفس العقد في ملف منفصل.
اختيار الأتمتة في وقت التطوير بدلاً من السحر في وقت التشغيل
لا يكون إطار عمل يعترض الطلبات في الإنتاج، بل يحلل المصدر في بيئة التطوير المحلية وينشئ الملفات الفعلية. يمكنك التحقق من النتائج بصريًا وإدارتها بالإصدار.
يتبع تقاليد المشروع بشكل يمكن التنبؤ به
لا أهدف إلى إنشاء مترجم شامل يفهم كل كود Java. أركز على تحليل هيكل نقطة النهاية الوظيفية في WebFlux التي أستخدمها فعليًا بقواعد واضحة.
إزالة الفترات المتكررة من الاتصال
إنشاء Swagger من نقطة النهاية الخلفية، ويربط مولد الواجهة الأمامية تلك الوثيقة بإنشاء الخدمة والنوع في سلسلة أتمتة واحدة.
ماذا نقرأ في الخلفية
مصدر RouterFunction
يقرأ طريقة HTTP، المسار المتداخل، مرجع طريقة المعالج و predicate.
مصدر المعالج
يقرأ جسم الطلب، قيم الاستعلام/المسار ونوع ناشر الاستجابة.
طلب / استجابة DTO
يربط نوع Java الذي تم كتابته بالفعل في الخلفية بمخطط OpenAPI.
مصدر كيان Mongo
يقرأ الاسم الخام للتخزين لحقل Java و @Field، ومجموعة @Document.
وحدة تحكم RSocket
يقرأ مسار @MessageMapping ونوع الحمولة للطلب/الاستجابة.
ماذا نصنع بدلاً من الكتابة المتكررة
swagger.json
يجعل نقطة نهاية REST عقد API يمكن أن تستخدمه خدمة الواجهة الأمامية ومولد نوع TypeScript.
asyncapi-rsocket.json
يجعل مسار RSocket والحمولة عقدًا يمكن لمولد عميل RSocket في الواجهة الأمامية قراءته.
مصدر المعالج
ينشئ ويعدل هيكل الفئة والطريقة بناءً على مرجع المعالج الذي تم ذكره أولاً في RouterFunction.
{Entity}Fields enum
ينشئ enum لحقل Java الخاص بالكيان واسم التخزين الخام لتجنب تكرار أسماء الحقول النصية.
enum لأسماء المجموعات
ينشئ ليتم استخدام اسم المجموعة المعلن في @Document بدلاً من السلسلة النصية.
تدفق الأتمتة في المشروع الحالي
• يكتب RouterFunction، المعالج و DTO الطلب/الاستجابة في الخلفية.
• يكتشف مراقب الملف الشخصي المحلي تغييرات المصدر ويحدث swagger.json أو asyncapi-rsocket.json.
• يقرأ برنامج إنشاء @byeolnaerim/typed-rx-http الوثيقة وينشئ وظائف الخدمة ونوع TypeScript.
• في كود الشاشة، يتم استخدام الوظائف التي تم إنشاؤها عن طريق استيرادها دون إعادة كتابة URL ونوع الاستجابة.
• عند تغيير الكيان، يتم تحديث enum الحقول المستخدمة في الاستعلام وenum المجموعات.