كيف تضيف فلاتر صور للبالغين إلى تطبيقك

تبدو إضافة فلتر صور للبالغين إلى منتجٍ ما مسألة معالجة صور، ثم تتبيّن أنها مسألة سباكة برمجية. عمل النموذج نفسه تشتريه باستدعاء واحد. أمّا ما يلتهم دورة التطوير فهو كل ما يحيط به: عمليات رفع تنتهي مهلتها، ومهام تكتمل بينما لا أحد يستمع، ومحاولات إعادة تُحاسَب مرتين بصمت، وطابور دعم فني يسأل أين ذهبت النتيجة. يمرّ هذا الدليل على التكامل من طرفه إلى طرفه، ويشير إلى المواضع التي تخسر فيها الفرق وقتها بانتظام.

مِمّ يتألف التكامل فعليًا

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

1. أرسل الصورة والـ preset المطلوب، واستلم معرّف المهمة.
2. تابع المهمة، إمّا بالاستطلاع الدوري أو بالاشتراك في الأحداث.
3. اجلب الصورة الجاهزة حين تُبلِغ المهمة بالنجاح.
4. عالج مسارات الفشل وإعادة المحاولة، وفيها يكمن معظم العمل الحقيقي.

الخطوة الأولى: إرسال المهمة

الإرسال طلب multipart يحمل الصورة ومعرّف الـ preset وتأكيدًا بأن لديك الحقوق والموافقة اللازمة لمعالجة الصورة. أرفق معه مفتاح idempotency. هذا الترويسة الواحدة هي الفرق بين تكامل نظيف ومشكلة دعم فني، وإضافتها لا تكلّف شيئًا.

curl -X POST https://api.example/api/v1/jobs \
  -H "X-API-Key: $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F image=@photo.jpg \
  -F feature=bikini \
  -F consent=confirmed

تحمل الاستجابة معرّف المهمة وحالتها الأولية. احفظ هذا المعرّف مقترنًا بسجل المستخدم أو الجلسة لديك فورًا، قبل أي خطوة أخرى. فإن مات المسار البرمجي في الثانية التالية، فذلك السجل هو الشيء الوحيد الذي يتيح لك العثور على العمل من جديد.

الخطوة الثانية: متابعة التقدّم

هناك طريقتان لمتابعة مهمة، والتكاملات الناضجة تستخدم كلتيهما. يمنحك اتصال WebSocket تغيّرات الحالة والتقدّم لحظةً بلحظة، وهو ما تريده لتشغيل شريط التقدّم في الواجهة. أمّا الاستطلاع الدوري لنقطة نهاية المهمة فهو البديل الاحتياطي الذي يجعل النظام صحيحًا لا مجرّد مريح: الاتصالات تنقطع، والهواتف تنام، واستطلاع كل بضع ثوانٍ لا يكلّف شيئًا يُذكر.

تعامَل مع WebSocket كتحسين، ومع الاستطلاع كمصدر للحقيقة. الفرق التي تعكس هذا الترتيب ينتهي بها الأمر بمهام اكتملت تمامًا على الخادم لكنها تبدو عالقة إلى الأبد لدى العميل، لأن الحدث الوحيد المهم وصل بينما كان الـ socket يعيد الاتصال.

الخطوة الثالثة: جمع النتيجة

حين تُبلِغ المهمة بالنجاح تحمل معها قائمة بالمخرجات. يُجلب كل مخرج بالمفتاح نفسه الذي أنشأ المهمة، فالنتائج غير قابلة للوصول العام ولا يمكن تخمينها من رابط. نزّل الصورة إلى تخزينك الخاص فور استلامها إن كان منتجك سيعرضها لاحقًا؛ فواجهة الصور خدمة معالجة لا مكتبة صور، والنتائج لا يُحتفظ بها إلى ما لا نهاية.

الخطوة الرابعة: الإخفاقات وإعادة المحاولة وفخّ المحاسبة المزدوجة

الإخفاق المثير للاهتمام ليس ذاك الذي تُرجع فيه الواجهة خطأً، بل الحالة الملتبسة: خرج طلبك، وانقطعت الشبكة، ولا تدري أنشئت المهمة أم لا. أعد المحاولة بسذاجة، وتكون قد دفعت مرتين وأنتجت نتيجتين لفعل واحد من المستخدم.

هذا تحديدًا ما يحلّه مفتاح idempotency. كرّر الطلب بالمفتاح نفسه فتستعيد المهمة الأصلية بدل إنشاء أخرى، مهما تكرّرت المحاولات. أنشئ المفتاح لحظة وقوع فعل المستخدم، واحفظه مع سجل المهمة، وأعد استخدامه في كل محاولة إعادة للفعل ذاته — لا مفتاحًا جديدًا لكل محاولة، فذلك يُبطل الآلية كلّها.

أين تتعثّر التكاملات عادةً

• التحقق من الملفات المرفوعة على العميل فقط. افحص الملف على الخادم بحسب محتواه لا امتداده، قبل أن تنفق عليه استدعاء API.
• بناء المسار كلّه بشكل متزامن، ثم اكتشاف أن عملاء الهاتف يقطعون الاتصال قبل انتهاء التوليد بوقت طويل.
• اعتبار WebSocket القناة الوحيدة للتقدّم، دون بديل بالاستطلاع الدوري.
• عدم تخزين أي شيء محليًا، فتضيع عند إعادة التشغيل العلاقة بين مستخدميك والمهام الجارية.
• نسيان أن النتائج مؤقتة، وتوقّع أن تعمل الواجهة كتخزين دائم.

ترتيب عمل معقول

مرّر صورة واحدة عبر المسار كاملًا باستخدام curl قبل كتابة أي شيفرة تطبيق: إرسال، استطلاع، تنزيل. ثم اربط الاستدعاءات الأربعة نفسها بواجهتك الخلفية مع التخزين الدائم. أضف WebSocket في النهاية، بوصفه تحسينًا لشريط التقدّم فوق نظام يعمل أصلًا بدونه. بهذا الترتيب يكون التكامل عمل يوم واحد؛ وبالترتيب العكسي يصبح أسبوعين من التنقيح.

الأسئلة الشائعة