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

يتواصل كل تطبيق حقيقي تقريبًا مع خادم. يمكن لفلاتر استخدام حزمة http، لكن Dio يضيف المعترضات (interceptors) وإلغاء الطلبات وتقدّم الرفع، وهو أكثر انتشارًا في المشاريع الجادة.
أنشئ نسخة Dio مشتركة واحدة وأعطها الإعدادات الأساسية مرة واحدة:
final dio = Dio(BaseOptions(
baseUrl: 'https://api.example.com/api/v1',
connectTimeout: const Duration(seconds: 10),
receiveTimeout: const Duration(seconds: 20),
headers: {'Accept': 'application/json'},
));حوّل استجابة JSON إلى صنف Dart حتى تعمل بقية شيفرتك مع كائنات محدّدة النوع، لا مع Map خام:
class Course {
final String id;
final String name;
final int price;
const Course({required this.id, required this.name, required this.price});
factory Course.fromJson(Map<String, dynamic> json) => Course(
id: json['id'] as String,
name: json['name'] as String,
price: json['price'] as int,
);
}لا يجب أن تستدعي العناصر Dio مباشرة. أنشئ صنفًا وسيطًا:
class CourseRepository {
CourseRepository(this._dio);
final Dio _dio;
Future<List<Course>> fetchCourses() async {
final response = await _dio.get('/courses');
return (response.data as List)
.map((e) => Course.fromJson(e as Map<String, dynamic>))
.toList();
}
}إذا تغيّر عنوان الواجهة أو صيغتها يومًا ما، يتغيّر هذا الصنف وحده.
أخطاء الشبكة أنواع: لا اتصال، أو انتهاء المهلة، أو استجابة خطأ من الخادم. حوّلها كلها إلى رسالة واحدة مفهومة:
String friendlyMessage(Object error) {
if (error is DioException) {
switch (error.type) {
case DioExceptionType.connectionTimeout:
case DioExceptionType.receiveTimeout:
return 'The server did not respond. Please try again.';
case DioExceptionType.connectionError:
return 'Check your internet connection.';
default:
final data = error.response?.data;
if (data is Map && data['message'] is String) return data['message'];
}
}
return 'Something went wrong.';
}كل ما يجب أن يحدث مع كل طلب (مثل إضافة ترويسة المصادقة أو التسجيل) مكانه معترض:
dio.interceptors.add(InterceptorsWrapper(
onRequest: (options, handler) {
final token = tokenStore.read();
if (token != null) options.headers['Authorization'] = 'Bearer $token';
handler.next(options);
},
));احفظ القيم الحساسة مثل الرموز (tokens) في flutter_secure_storage، لا في SharedPreferences.
CancelToken.بهذه البنية، يمسّ تغيير الخادم أو إضافة نقطة نهاية جديدة ملفًا واحدًا فقط.
يبني فريق فست فلاتر تطبيقات أندرويد وiOS والويب وسطح المكتب والمواقع بفلاتر: تقدير فوري بالدولار، ودفع على مراحل، والشيفرة المصدرية كاملة.