flutter guidelines

إرشادات الرفرفة

مرحبًا! تحتوي هذه الوثيقة على توصياتي الشخصية للسياسات والإجراءات والمعايير المتعلقة بكيفية إجراء التنمية.

هيكل رمز المشروع

يجب تنظيم رمز المشروع بمزيج من المجلد على أساس الجسد ونوع المجلد .

معنى على مستوى الجذر لديك مجلدات تحدد الميزات. على سبيل المثال:

 |-- common/
|-- authentication/
|-- settings/

تحتوي الميزة المشتركة/الأساسية على فئات أو وظائف أو عناصر واجهة المستخدم التي يجب أن تتوفر افتراضيًا في أي ميزات.

لذا فإن الفكرة هي أن يكون لديك ميزات لتطبيقك مقسومًا على المجلدات العليا.

فكر في كل مجلدات المستوى الأعلى كحزمة DART/FFLUTRE المنفصلة أو التبعيات أو حدود الوصول إلى التطبيق الخاص بك.

لذا ، إذا قمت بإضافة شيء ما إلى المجلد المشترك ، فيجب عليك أن تسأل نفسك ، هل ستحتاج ميزات تطبيقنا 99. ٪ إلى ذلك؟

إذا كنت تفكر في الأمر باعتباره تبعية ، فسيتم الإعلان دائمًا عن التبعية الشائعة في PubSpec.yaml.

لذلك قبل إضافة فئة أو وظيفة أو عنصر واجهة مستخدم إلى المجلد المشترك ، اسأل نفسك:

• هل هو شيء تحتاجه كل ميزة في PubSpec.yaml ، أم أنه شيء أكثر اختيارية؟
• إذا كانت الإجابة بنعم من إضافتها إلى الشائعة ، إذا كانت الإجابة لا من استخراجها إلى مجلد آخر.

داخل كل مجلد ميزة لديك مجلدات محددة حسب النوع.

فيما يلي أنواع المجلدات التي ستكون جزءًا من مجلد الميزة.

 |-- ui/
|-- cubits/
|-- domain_objects/
|-- exceptions/
|-- use_cases
|-- services/
|-- repositories/
|-- data_sources/
|-- dtos/

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

 |-- authentication/
|---- cubits/
|------ login/
|-------- login_cubit.dart
|-------- login_cubit.freezed.dart
|-------- login_cubit.g.dart

واجهة المستخدم (واجهة المستخدم)

الكود المرتبط بواجهة جهاز المستخدم ، على سبيل المثال: لاعبي PageBileds UI ، وشاشات واجهة المستخدم ، وعرض واجهة المستخدم ، ومكونات واجهة المستخدم.

شاشة

الشاشة عبارة عن مكون واجهة المستخدم يملأ عرض الجهاز بأكمله وهو حاوية عرض واجهة المستخدم أو مكون (الزر ، مربعات الاختيار ، الصور ، ECT).

أيضا ، الشاشة هي وجهة تنقل تطبيق محددة.

المبدأ التوجيهي:

• شاشات اسم الملف والفصول يجب أن تكون لاحقة مع الشاشة .
• يجب أن تتفاعل فصول الشاشات فقط مع فئات Cubit.
• يجب تقسيم طريقة بناء الشاشة بواسطة عناصر واجهة مستخدم خاصة تفصل منطقة التحديث / استخدامها . على سبيل المثال:

 class LoginScreen extends StatelessWidget {
  //...fields and constructor...
  @override
  Widget build ( BuildContext context) {
    return Column (
      children : < Widget > [
        _LoginLogo ,
        _LoginForm ,
        _LoginActions ,
        _LoginFooter
      ],
    );
  }
}

// extracted by use case.
class _LoginLogo extends StatelessWidget {}

// extracted by update area.
class _LoginForm extends StatefullWidget {}

// extracted by update area.
class _LoginActions extends StatelesssWidget {}

// extracted by update area.
class _LoginFooter extends StatelessWidget {}

• بعد الاستخراج إلى الحاجيات الخاصة. إذا كان عدد ملفات الشاشة أكبر من 400 ، فيجب عليك نقل الأدوات الخاصة إلى ملف جزء. اتفاقية تسمية ملف الجزء: $ {اسم ملف الشاشة} _components.dart. على سبيل المثال:

login_screen.dart

 part 'login_screen_components.dart' ;

class LoginScreen extends StatelessWidget {
  //...fields and constructor...
  @override
  Widget build ( BuildContext context) {
    return Column (
      children : < Widget > [
        _LoginLogo ,
        _LoginForm ,
        _LoginActions ,
        _LoginFooter
      ],
    );
  }
}

// Is kept here because it's does not break the 400 max line rule.
class _LoginLogo extends StatelessWidget {}

login_screen_components.dart

 part of 'login_screen.dart' ;

/// [LoginScreen] 's fields.
class _LoginForm extends StatelessWidget {}

// ************************ Footer ************************

/// [LoginScreen] 's footer.
class _LoginFooter extends StatelessWidget {}

// ************************* ACTIONS *********************************

/// [LoginScreen] 's actions.
class _LoginActions extends StatelessWidget {}

• لا تقم بتمرير Cubit إلى مُنشطات الفحص ، بدلاً من ذلك ، يمكنك الوصول إليها باستخدام blocbuilder أو bloclistener أو blocconsumer. على سبيل المثال:

 class LoginScreen extends StatelessWidget {
  @override
  Widget build ( BuildContext context) {
    return BlocBuilder < LoginCubit , LoginCubitState >(
      // Here cubit is not specified either.
      builder : ( BuildContext context, LoginCubitState state) {},
    );
  }
}

• استخدم فئات القطعة الخاصة بدلاً من الوظائف لبناء الأشجار الفرعية ، على سبيل المثال:

 class SomeWidget extends StatelessWidget {
  @override
  Widget build ( BuildContext context) {
    //...
  }
}

class _SubTree1 extends StatelessWidget {}

class _SubTree2 extends StatelessWidget {}

class _SubTree3 extends StatelessWidget {}

class _SubTree4 extends StatelessWidget {}

• يجب أن يكون رد فعل إجراء الشاشة/الحدث جزءًا من فئة الشاشة كطريقة.
  • يجب أن تبدأ طريقة رد الاتصال الإجراء/الحدث مع البادئة .
  • يجب أن يتطابق اسم الإجراء/الحدث. على سبيل المثال:

 class LoginScreen extends StatelessWidget {
  @override
  Widget build ( BuildContext context) {
    return Column (
      childreen : < Widget > [
        Button1 (onClick : _openRegisterUser),
        Button2 (onClick : _openLogin),
        Field (onTextChanged : _onUserNameTextChanged),
      ],
    );
  }
  
  void _openRegisterUser () {}
  
  void _openLogin () {}
  
  void _onUserNameTextChanged ( String newText) {}
}

عرض واجهة المستخدم

العرض هو مكون واجهة المستخدم لا يملأ عرض الجهاز بأكمله وهو حاوية عرض واجهة المستخدم أو مكون (الزر ، مربعات الاختيار ، الصور ، إلخ).

أيضا ، فإن العرض ليس وجهة تنقل التطبيق.

المبدأ التوجيهي:

• عرض اسم الملف والطبقات يجب أن تكون لاحقة مع العرض .
• يجب أن تتفاعل فصول العرض فقط مع فئات Cubit.
• يجب تقسيم طريقة بناء الشاشة بواسطة عناصر واجهة مستخدم خاصة تفصل منطقة التحديث / استخدامها . على سبيل المثال:

الاشتراء

Cubits عبارة عن فصول تحتوي على منطق عمل لواجهة واجهة المستخدم الخاصة بك ، فإن Cubit مرتبط بالدولة ، التي تمثل حالة واجهة المستخدم.

توصيات التوجيهية:

• فقط تغطي منطق العمل اللازم لواجهة المستخدم.
• إرجاع العقود المستقبلية للإجراءات العامة.
• التفاعل فقط مع فئات عالية المستوى ، المعنى: استخدام الحالات.
• إرجاع الإجراءات النهائية نتيجة للمتصل. على سبيل المثال:

 Future < String ?> bookAppointment ( BookingData booking);

Future < bool > login ( String username, String password);

• فقط استخدم المستودعات والخدمات واجهات الخدمات وليس التطبيقات الملموسة.
• لاحقة الفصل الخاص بك مع cubit ، مثال logincubit.
• يجب أن تكون ملفات فئة Cubit ضمن مجلد Cubits من الميزة.

دولة Cubit.

تمثل فئة حالة Cubit حالة واجهة المستخدم التي تحدها وقتًا معينًا.

توصيات التوجيهية:

• استخدم فئة واحدة للحالة أو تحديد فئة أساسية وتحديد الفئة الفرعية لكل ولاية.
• لا ينبغي أن تكون نتيجة الإجراءات النهائية جزءًا من الدولة. على سبيل المثال:

 class LoginState {
  bool logginSuceeded // avoid this.
}

• احتفظ بالفئة في نفس الملف تم تعريف فئة Cubit.

استخدام الحالات

الفصول الدراسية المستخدمة في إجراء عملية عمل/هدف/مهمة/مهمة واحدة في مجالك.

الإرشادات:

• يجب أن يكون لاسم USECASE دائمًا بادئة ، والتي يجب أن تكون فعلًا ، تصف المهمة التي يقوم بها هذا الفصل. على سبيل المثال: class GetCurrentUserUseCase ، class SignInUseCase .
• يجب أن يكون للاسم usecase دائمًا لاحقة UseCase ؛
• يجب أن يكون لدى فئة USECASE دائمًا call() ، حيث يكون نوع الإرجاع نتيجة لتنفيذ حالة الاستخدام ؛
• يجب أن تتمتع USECASE بالوصول فقط إلى Repositories أو Services أو أي high level coordinators ؛
• لا ينبغي أن تتمتع USECASE بالوصول إلى DataSource أو Cubit أو التفاعل مع DTOs أو أي كائن آخر منخفض المستوى ؛
• يجب استخدام usecase في Cubit أو في UseCases الأخرى.

أمثلة:

 class GetCurrentUserUseCase {
	final UserRepository _repository;
	const GetCurrentUserUseCase ( this ._repository);
	Future < User ?> call () async {
		await _repository. getCurrentUser ();
	}
}

 class AuthenticateMemberUseCase {
  /// Create a [AuthenticateMemberUseCase] .
  const AuthenticateMemberUseCase (
    /* constructor arguments */
  );

  /* ... fields ...*/

  /// Execute the use case.
  Future < TegTask < void >> call ( MemberAuthenticationCredentials credentials) {
    return runTaskSafelyAsync < void >(() async {
      final bool isEmailValid = credentials.email.isEmail;

      if ( ! isEmailValid) {
        throw const TegEmailInvalidException ();
      }
      
      final bool isConnected = await _hostDeviceInternetService. isConnected ();

      if ( ! isConnected) {
        throw const TegInternetUnavailableException ();
      }

      final String ? deviceId = await _hostDeviceInfoRepository. getDeviceId ();

      if (deviceId == null ) {
        throw const TegDeviceIdUnavailableException ();
      }

      final PublicPrivateKeyPair keyPair = await _keyGenerator. generate ();

      final Member member = await _authService. signIn (
        email : credentials.email,
        password : credentials.password,
        deviceId : deviceId,
        publicKey : keyPair.publicKey,
      );

      await _updateCurrentMemberUseCase (
        member : member,
        memberPrivateKey : keyPair.privateKey,
        deviceId : deviceId,
      );

      await _saveMemberAuthenticationCredentialsUseCase (credentials);

      final TegTask < List < Account >> memberAccountsTask = await _getMemberAccountsUseCase ();

      if (memberAccountsTask.failed) {
        throw memberAccountsTask.exception;
      }

      await _updateMemberCurrentAccountUseCase (
        member : member,
        deviceId : deviceId,
        memberPrivateKey : keyPair.privateKey,
        account : memberAccountsTask.result.first,
      );
    });
  }
}

المستودعات

الفئات التي توفر الوصول إلى البيانات باستخدام عمليات CRUD فقط لميزة معينة أو نطاق من الميزة ، على سبيل المثال:

 abstract class BookingRepository {
  Futute < Booking > getBookingById ( String id);

  Future < List < Booking >> getBookings ();

  Future < void > deleteBookingById ( String id);

  Future < void > saveBooking ( Booking booking);
}

توصيات التوجيهية:

• اسم فئة لاحقة مع مستودع.
• حدد المستودعات فقط للميزات أو نطاق الميزات وتسميتها.
• استخدم المستودعات لتوفير الوصول إلى البيانات ومعالجة البيانات.
• يجب على المستودعات تنسيق الوصول بين مصادر البيانات أو تحديد مصدر البيانات الذي يجب استخدامه على سبيل المثال بواسطة علامة الميزة. مثال:

 class DefaultBookingRepository implements BookingRepository {
  final LocalBookingDataSource local;
  final RemoteBookingDataSource remote;

  Future < Booking ?> getBookingById ( String id) async {
    Booking ? savedBooking = await local. getBookingById (id);

    if (savedBooking == null ) {
      Booking ? remoteBooking = await remote. getBookingById (id);

      if (remoteBooking != null ) {
        await local. saveBooking (remoteBooking);
      }
      return remoteBooking;
    }
    return savedBooking;
  }

//...other operations...
}

• تحديد واجهات API المستودع وتنفيذ الخرسانة حسب النوع ، على سبيل المثال:

واجهة

 abstract class BookingRepository {}

التطبيقات

 class DefaultBookingRepository implements BookingRepository {}

class AnonymousBookingRepository implements BookingRepository {}

class PremiumBookingRepository implements BookingRepository {}

• لا تستخدم الأدوات ، والمكتبات ذات الصلة من النظام الأساسي أو تنفيذ منطق الشبكة في المستودعات ، وتغلف ذلك في مصادر البيانات.
• فقط استخدم مصادر البيانات داخل المستودعات.
• تلقي فقط ككائن بدائي أو كائن المجال ومجال الإخراج.
• يجب تسمية تطبيقات واجهة برمجة تطبيقات المستودع باستخدام اسم فئة المستودع كاحتياج.
• تجنب تسمية مستودعات مع لاحقة INRA ، قم بتسميةها باستخدام الاسم الافتراضي بادئة + اسم مستودع الأساس .
• إرجاع النوع غير المتزامن لواجهة برمجة التطبيقات العامة (المستقبل أو الدفق).
• يجب ألا يغير تنفيذ المستودع واجهة برمجة التطبيقات العامة (نوع الإرجاع ، وسيطات الطريقة).
• يجب أن تكون ملفات فئة المستودع تحت مجلد المستودعات من الميزة.

خدمات

الفصول التي توفر الوصول إلى وظائف لميزة معينة أو نطاق من الميزة ، على سبيل المثال:

 abstract class AuthenticationService {
  Future < void > authenticate ( String username, String password);

//...other functionalities...
}

abstract class AppointmentService {
  Future < void > register ( Appointment appointment);

//...other functionalities...
}

توصيات التوجيهية.

• اسم فئة لاحقة مع الخدمة .
• حدد الخدمات فقط للميزات أو نطاق الميزات وتسميتها.
• استخدم الخدمات لتوفير الوظائف المطلوبة لتنفيذ منطق العمل.
• استخدم مصادر البيانات للوصول إلى البيانات المطلوبة لتنفيذ منطق أعمال الوظائف.
• لا تستخدم الأدوات ، والمكتبات ذات الصلة من النظام الأساسي ، ولا تنفيذ منطق الشبكة في الخدمات ، وتنفيذها في مصادر البيانات.
• فقط استخدم مصادر البيانات داخل الخدمات.
• تلقي فقط ككائن بدائي أو كائن المجال ومجال الإخراج.
• يجب تسمية تطبيقات واجهة برمجة تطبيقات الخدمة مع اسم فئة الخدمة باسم لاحقة.
• تجنب تسمية الخدمات مع لاحقة INM ، قم بتسميةها باستخدام الاسم الافتراضي بادئة + اسم خدمة قاعدة .
• إرجاع النوع غير المتزامن لواجهة برمجة التطبيقات العامة (المستقبل أو الدفق).
• يجب ألا يغير تنفيذ الخدمة واجهة برمجة التطبيقات العامة الخاصة بهم (نوع الإرجاع ، وسيطات الطريقة).
• يجب أن تكون ملفات فئة الخدمة ضمن مجلد الخدمات للميزة.

مصادر البيانات

الفئات التي تنفذ الوصول إلى البيانات الموجودة محليًا أو عن بُعد. مثال

 abstract class LocalBookingDataSource {
  Futture < void > saveBooking ( Booking booking);

//...other functionalities...
}

abstract class RemoteBookingDataSource {
  Future <booking> saveBooking ();
}

توصيات التوجيهية:

• الحفاظ على النوع الأساسي لمصادر البيانات إلى المحلية والبعيدة.
• تطبيق الأسماء بعد المكتبة أو الأداة المستخدمة واسم مصدر البيانات على أنه لاحقة ، على سبيل المثال:

 class SQLiteBookingDataSource implements LocalBookingDataSource {
  //...............Implementation................
}

class RestApiBookingDataSource implements RemoteBookingDataSource {
  //...............Implementation................
}

class MemoryBookingDataSource implements LocalBookingDataSource {
  //...............Implementation................
}

• التعامل مع أخطاء المكتبة أو الأداة في مصدر البيانات وتحويلها إلى استثناء مخصص للتطبيق.
• تلقي فقط ككائن بدائي أو كائن المجال ومجال الإخراج أو بدائي.
• يجب تسمية تطبيقات واجهة برمجة تطبيقات مصدر البيانات باسم فئة مصدر البيانات على أنها لاحقة.
• إرجاع النوع غير المتزامن لواجهة برمجة التطبيقات العامة (المستقبل أو الدفق).
• يجب ألا يغير تنفيذ مصادر البيانات واجهة برمجة التطبيقات العامة الخاصة بهم (نوع الإرجاع ، وسيطات الطريقة).
• يجب أن تكون ملفات فئة مصادر البيانات ضمن مجلد DataSources من الميزة.

كائنات نقل البيانات - DTO

كائنات نقل البيانات - تستخدم لنقل البيانات من نظام إلى آخر. مثال

 class ApiRequest {
  //...fields...
}

class ApiResponse {
  //...fields...
}

 class SQLiteTableDefinition {
  //...fields...
}

الإرشادات:

• استخدم DTO لتمثيل جداول قاعدة البيانات.
• استخدم DTO لتمثيل طلب API والاستجابة.
• استخدم DTO لتنفيذ البيانات المطلوبة. على سبيل المثال لاستخدام مكتبة الثبات ، تحتاج بياناتك إلى تمديد كائن أو إضافة المزيد من الحقول ، قم بإنشاء DTO بدلاً من ذلك.
• تنفيذ التعيينات في فئة DTO ، على سبيل المثال.

 class ApiRequest {
  //...fields...

  factory ApiRequest . fromDO ( DOObject doObject) {
    //...mapper code...
  }

  DOObject toDO () {
    //...mapper code...
  }
}

• لا تقم بتنفيذ المنطق حفظ أو جلب في DTO ، وتطبيقه في مصادر البيانات.
• يجب أن تكون ملفات فئة DTO ضمن مجلد DTOS للميزة.

كائن المجال

كائن المجال هو فئات البيانات تمثيل جزء من العمل أو عنصر داخله ، يتم استخدامها لتنفيذ منطق الأعمال بشكل مستقل عن النظام الأساسي أو المكتبة أو الأدوات.

قد يمثل كائن المجال ، على سبيل المثال ، شخص أو مكان أو حدث أو عملية تجارية أو مفهوم وفاتورة أو منتج أو معاملة أو حتى تفاصيل الشخص .

المبدأ التوجيهي:

• يجب أن يكون اسم فئات كائن المجال مع ذلك.
• يجب أن تحتوي فئات كائن المجال فقط على حقول بيانات أو طريقة لتنسيق حقول البيانات.
• يجب أن تنفذ فئات كائن المجال أساليب متساوية وطرق رمز التجزئة ، FromJson و Tojson.
• يجب أن يكون نوع فئات كائن المجال بدائية أو كائن مجال آخر.
• يجب أن تكون ملفات فئة كائن المجال ضمن مجلد Domain_objects من الميزة.

كيفية تنظيم الأصول

نفس الشيء بالنسبة لهيكل رمز المشروع.

أولا اسم الميزة ، ثم مجلد assets يحتوي على ملفات.

مثال:

 |-- authentication/
|---- assets/
|------ password_hidden_icon.svg
|------ forget_password_icon.svg
|------ background.png