Riverpod — إدارة التبعيات المُجمَّعة لتطبيقات Flutter

ما هو Riverpod؟

Riverpod هي مكتبة لإدارة الحالة وحقن التبعيات لتطبيقات Flutter تقوم بتجميع أوصاف مقدمي الخدمة إلى كود Dart آمن. على عكس Provider، مقدمي الخدمة في Riverpod غير مرتبطين بـ BuildContext: يتم إنشاؤهم عالميًا أو في ProviderScope ويمكن الوصول إليهم من أي مكان. يتحقق المترجم من الأنواع والتبعيات وسلامة رسم بياني لمقدمي الخدمة في وقت البناء، مما يلغي أخطاء وقت التشغيل مثل ProviderNotFoundException.

يستخدم Riverpod نموذج override للاختبار: يمكن تجاوز كل مزود عبر ProviderScope.overrideWithout الحاجة إلى إنشاء فئات فرعية أو محاكاة واجهات. هذا يجعل الاختبار معزولاً: يحصل كل اختبار على نسخته الخاصة من رسم بياني التبعيات التي يتم التحكم فيها بالكامل.

وفقًا لـ Flutter Community Survey 2025، يحتل Riverpod المركز الثالث من حيث الشعبية بعد Provider و BLoC. ومع ذلك، فإن Riverpod هو الحزمة الأسرع نموًا: +120% تثبيت في 2024. الأسباب الرئيسية: الأمان في وقت التجميع، عدم وجود ProviderNotFoundException، دعم غير متزامن مدمج عبر AsyncValue.

أنواع مقدمي الخدمة

Riverpod يوفر 8 أنواع من مقدمي الخدمة، كل منها لسيناريو محدد: Provider (ثابت/خدمة)، StateProvider (حالة بدائية)، StateNotifierProvider (منطق معقد مع StateNotifier)، ChangeNotifierProvider (للترحيل من Provider)، FutureProvider (بيانات غير متزامنة، لمرة واحدة)، StreamProvider (تدفق تفاعلي)، NotifierProvider (API جديد، Flutter 3.10+) و AsyncNotifierProvider (Notifier غير متزامن).

final counterProvider = StateNotifierProvider<CounterNotifier, int>((ref) {
  return CounterNotifier();
});

class CounterNotifier extends StateNotifier<int> {
  CounterNotifier() : super(0);

  void increment() => state++;
  void decrement() => state--;
}

class CounterScreen extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return Text('$count');
  }
}

ProviderRef — كائن يتم تمريره لكل مزود للوصول إلى مقدمي الخدمة الآخرين. ref.watch — اشتراك في التغييرات، ref.read — قراءة لمرة واحدة، ref.invalidate — إعادة تعيين الذاكرة المؤقتة. يستبدل ProviderRef BuildContext من Provider: يمكن لأي مزود قراءة مقدمي الخدمة الآخرين دون الوصول إلى شجرة الأدوات. هذا يسمح ببناء رسم بياني للتبعيات خارج طبقة واجهة المستخدم.

ProviderScope — الأداة الجذرية، إلزامية لعمل Riverpod. يخزن ProviderScope جميع مقدمي الخدمة، ويدير دورة حياتهم ويخزن القيم مؤقتًا. بدون ProviderScope سيتعطل التطبيق مع ProviderNotFoundException. يمكن أن يكون ProviderScope متداخلاً — النطاق المتداخل يتجاوز مقدمي الخدمة الأصل، مما يستخدم للاختبار وعزل الميزات.

AsyncValue والعمل مع عدم التزامن

AsyncValue — فئة مختومة من Riverpod لتمثيل الحالة غير المتزامنة. AsyncValue له ثلاثة أشكال: AsyncData (بيانات ناجحة)، AsyncError (خطأ)، AsyncLoading (تحميل). بدلاً من التبديل اليدوي بين التحميل/الخطأ/البيانات، كل FutureProvider أو StreamProvider يعيد تلقائيًا AsyncValue، وتتعامل الأداة مع جميع الحالات الثلاث عبر ref.watch.

final userProvider = FutureProvider((ref) async {
  final api = ref.watch(apiProvider);
  return await api.fetchUser();
});

class UserScreen extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final userAsync = ref.watch(userProvider);
    return userAsync.when(
      data: (user) => UserWidget(user),
      error: (e, _) => ErrorWidget(e.toString()),
      loading: () => CircularProgressIndicator(),
    );
  }
}

AsyncValue.when — طريقة لمطابقة الأنماط لجميع الحالات الثلاث. يتحقق المترجم من معالجة جميع الحالات الثلاث — إذا نسيت التحميل أو الخطأ، لن يتم تجميع الكود. AsyncValue.whenData — فقط للبيانات (إذا لم يكن التحميل/الخطأ ضروريين). AsyncValue.guard — غلاف حول try-catch لتحويل الاستثناءات إلى AsyncError. keepAlive — علامة تمنع تدمير ذاكرة التخزين المؤقت للمزود عند الخروج من النطاق.

توليد الكود و @riverpod

توليد الكود — ميزة رئيسية في Riverpod 2.0+. التعليق @riverpod على دالة يولد تلقائيًا مزودًا بالنوع الصحيح ودعم إعادة الهيكلة والإكمال التلقائي. يستخدم توليد الكود riverpod_generator و build_runner. يكتب المطور دالة نقية، وكل شيء آخر — الأنواع والفئات والمنشئات المصنعية — يتم توليده تلقائيًا.

@riverpod
String helloWorld(HelloWorldRef ref) {
  return 'Hello World';
}

// تم التوليد: final helloWorldProvider = Provider((ref) => 'Hello World');

@riverpod
class Counter extends _$Counter {
  int build() => 0;
  void increment() => state++;
}

Notifier — API الجديد للحالة القابلة للتغيير مع توليد الكود. Notifier هو فئة بطريقة build() وطرق تغيير الحالة. على عكس StateNotifier، لا يتطلب Notifier فئة حالة منفصلة ويوفر وصولاً مباشرًا إلى state عبر getter/setter. يولد Riverpod تلقائيًا NotifierProvider لكل فئة Notifier موسومة بـ @riverpod.

build_runner: يتم تشغيل توليد الكود بأمر dart run build_runner build. الملفات المولدة لها اللاحقة .g.dart ويتم استيرادها في الكود المصدري. عندما تتغير التعليقات أو أنواع مقدمي الخدمة، يجب إعادة تشغيل توليد الكود. يوصي Riverpod 2.x بتوليد الكود لجميع المشاريع الجديدة — إنشاء مقدمي الخدمة يدويًا أصبح قديمًا.

Riverpod مقابل Provider

الاختلافات الرئيسية بين Riverpod و Provider: الاستقلال عن BuildContext، الأمان في وقت التجميع، دعم غير متزامن مدمج، التخزين المؤقت التلقائي، والاختبار عبر override. يتطلب Provider BuildContext للوصول إلى الحالة (context.watch, context.read)، يستخدم Riverpod WidgetRef ومقدمي الخدمة المعلنين عالميًا.

الترحيل من Provider: يدعم Riverpod ChangeNotifierProvider.adaptive لاستخدام ChangeNotifier الموجود دون إعادة كتابة. الترحيل التدريجي: أولاً تكتب الميزات الجديدة بـ Riverpod، ثم يتم استبدال مثيلات Provider القديمة بمقدمي خدمة Riverpod عبر محول. يمكن للحزمتين التعايش في مشروع واحد، مما يسمح بالترحيل دون تجميد التطوير.

اختبار Riverpod

اختبار Riverpod مبني على ProviderScope.overrideWith. يتم تجاوز كل مزود داخل ProviderScope اختباري دون محاكاة أو حاويات DI. ProviderContainer — بيئة معزولة للاختبارات بدون Flutter (Dart نقي)، مما يسمح باختبار مقدمي الخدمة دون عرض الأدوات.

import 'package:flutter_test/flutter_test.dart';
import 'package:riverpod/riverpod.dart';

void main() {
  test('Counter increments correctly', () {
    final container = ProviderContainer();
    container.read(counterProvider.notifier).increment();
    expect(container.read(counterProvider), 1);
  });

  testWidgets('UI updates on increment', (tester) async {
    await tester.pumpWidget(
      ProviderScope(
        overrides: [counterProvider.overrideWithValue(5)],
        child: CounterScreen(),
      ),
    );
    expect(find.text('5'), findsOneWidget);
  });
}

ProviderContainer — بدون Flutter. استخدم ProviderContainer لاختبارات الوحدة لمقدمي الخدمة دون أدوات. overrideWithValue — استبدال مزود بقيمة محددة. overrideWith — استبدال بمصنع مزود (لمحاكاة الخدمات). autodispose — في الاختبارات تحقق من تدمير المزود عند الخروج من النطاق باستخدام container.dispose().