الأدلةدروس

إنشاء محوّل Flutter مع حفظ مفتاح API على الخادم

أنشئ محوّلاً typed في Flutter يجلب السعر عبر proxy، ويعرض المصدر وحالة التحميل والفشل وعمر cache، مع التقريب عند العرض فقط.

29 سبتمبر 2026 · قراءة خلال 8 دقائق

تطبيق Flutter على الهاتف عميل عام، لذلك لا يجوز أن يحمل bearer key الخاص بـ exchangerate.dev. ضع المفتاح في proxy على /api/fx، وأرسل {from,to} من Flutter، واحفظ السعر والمصدر وجلسة السوق ووقت الرصد معاً في نموذج typed.

  • يستدعي ملف Dart proxy الخاص بك؛ لا يحمل التطبيق مفتاح exchangerate.dev.
  • يتحقق النموذج من السعر وdata_updated_at قبل العرض.
  • يرى المستخدم حالة التحميل وأخطاء HTTP/التنسيق والمصدر والجلسة وعمر cache.
  • يستخدم العرض منازل عشرية ثابتة مع إبقاء قيمة API غير المقربة في الكود.
  • السعر الإرشادي للتقدير والعرض؛ يتولى مزود الدفع التسوية.

حفظ بيانات الاعتماد على الخادم

يستقبل مسار الخادم from وto، ويضيف Authorization: Bearer $EXCHANGERATE_API_KEY، ويستدعي /v1/latest/{from}?symbols={to}، ثم يعيد الحقول المطلوبة فقط. احفظ المفتاح في بيئة الخادم. يستقبل التطبيق عنوان proxy عبر --dart-define=FX_PROXY_BASE_URL=… ولا يستلم مفتاح الخدمة الأصلي.

proxy contract · response
GET /api/fx?from=USD&to=EUR{"from":"USD","to":"EUR","rate":0.9245,"source":"live","market_session":"open","data_updated_at":"2026-09-29T10:00:00Z"}

إضافة اعتماد HTTP

أنشئ تطبيق Flutter وأضف حزمة http الحالية إلى pubspec.yaml، واحفظ محول Flutter الكامل في lib/main.dart. شغّله عبر flutter run --dart-define=FX_PROXY_BASE_URL=https://your-app.example/api/fx. نزّل proxy Node الأدنى، واضبط EXCHANGERATE_API_KEY وشغّل Node 20 أو أحدث. يستمع proxy على loopback 8787 للاختبار المحلي؛ وقبل ربط جهاز، وفّر وصول HTTPS موثقاً مع تقييد الطلبات. يتحقق proxy من العملة والمبلغ ويمرر المفتاح ويعيد حقول العرض typed فقط. راجع دليل Flutter الرسمي للشبكات.

التحقق من السعر قبل العرض

يرفض النموذج rate المفقود أو غير الموجب أو غير المحدود أو غير الرقمي، وكذلك data_updated_at المفقود. يمنع ذلك صفحات HTML وأخطاء proxy وJSON الفارغ من الوصول إلى نتيجة التحويل. يفرض العميل مهلة عشر ثوانٍ ويعرض حالات غير 2xx.

Dart · typed response shape
class FxQuote {  final String from;  final String to;  final double rate;  final String source;  final String marketSession;  final DateTime dataUpdatedAt;}

عرض التحميل والخطأ ووقت البيانات

يعطّل العرض الزر أثناء الطلب ويظهر مؤشر التحميل، ويحفظ رسالة مقروءة عند فشل proxy. بعد النجاح يعرض المبلغ والسعر والمصدر والجلسة ووقت الرصد وعمر cache منذ جلب الجهاز وعمر الرصد منذ data_updated_at، لتمييز الرصد اللحظي عن المرجع اليومي.

تقريب العرض مع إبقاء القيمة

اعرض JPY بلا منازل، وUSD وEUR وGBP وIDR بمنزلتين، واعرض السعر بست منازل للقراءة. هذا تقريب عرض فقط؛ احتفظ بالقيمة الرقمية الأصلية واستخدم decimal أو fixed-point في المحاسبة، ولا تستخدم قيمة العرض العائمة كسجل تسوية.

يمكن قراءة credentials داخل تطبيق الهاتف

لا تجعل obfuscation أو ثوابت البناء أو مستودع Flutter الخاص مفتاح API سرياً بعد توزيع التطبيق. proxy جزء من التصميم وليس تقوية اختيارية.

اختبار تدفق المستخدم

شغّل التطبيق باستجابة proxy تجريبية، واختبر timeout و401/429 وJSON غير الصالح والسعر المفقود وdata_updated_at القديم. تحتاج إعدادات الشبكات وTLS والنشر إلى فحص على جهاز أو محاكي؛ الملف مثال عميل قابل للتشغيل وليس proxy مستضافاً.

أسعار إرشادية فقط

استخدم النتيجة للتقدير والعرض والتحليل. يجب أن يحصل نظام الدفع أو النظام المنظم على عرضه القابل للتنفيذ وسجل التسوية بنفسه.

أسئلة

هل يمكن لـ Flutter استدعاء exchangerate.dev مباشرة؟

يمكن للتطبيق العام الوصول إلى endpoint مجهول للتقييم، لكنه لا يجوز أن يحمل مفتاح الإنتاج. استخدم proxy للوصول بحساب ومفتاح.

ما معنى عمر cache في المثال؟

عمر cache هو الزمن منذ جلب الجهاز للاستجابة، وعمر الرصد محسوب من data_updated_at. قد تتضمن الاستجابة الجديدة رصداً يومياً قديماً أو بيانات أثناء إغلاق السوق؛ اعرض العمرين.

هل يغيّر toStringAsFixed سعر API؟

لا، إنه ينسق نص العرض فقط. احتفظ بالقيمة الرقمية لمنطق التطبيق واستخدم استراتيجية decimal مناسبة للحساب الدقيق.

هل يستطيع هذا المحول تسوية المدفوعات؟

لا. يقدم بيانات مرجعية للتقدير والعرض، لا عرض تسوية قابلاً للتنفيذ.

تابع القراءة

ابدأ بمفتاح API مجاني

5,000 طلب شهريًا ضمن الخطة المجانية. لا حاجة إلى بطاقة ائتمان.

احصل على مفتاح مجاني