flutter guidelines

Pedoman Flutter

Halo! Dokumen ini berisi rekomendasi pribadi saya untuk kebijakan, prosedur, dan standar mengenai bagaimana pengembangan harus dilakukan.

Struktur Kode Proyek

Kode proyek harus disusun dengan campuran folder-by-feature dan folder-by-type .

Artinya di level root Anda memiliki folder yang mendefinisikan fitur. Misalnya:

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

Fitur umum/inti berisi kelas, fungsi atau widget yang secara default harus tersedia di fitur apa pun.

Jadi idenya adalah untuk memiliki fitur aplikasi Anda yang dibagi berdasarkan folder tingkat atas.

Pikirkan setiap folder tingkat atas sebagai paket DART/Flutter terpisah, dependensi atau batas akses aplikasi Anda.

Jadi, jika Anda menambahkan sesuatu ke folder umum, Anda harus bertanya pada diri sendiri, akankah 99.% fitur aplikasi kami membutuhkannya?

Jika Anda menganggapnya sebagai ketergantungan, ketergantungan umum selalu dinyatakan dalam pubspec.yaml Anda.

Jadi sebelum menambahkan kelas, fungsi atau widget ke folder umum, tanyakan pada diri sendiri:

• Apakah itu sesuatu yang dibutuhkan setiap fitur di pubspec.yaml, atau lebih dari sesuatu yang opsional?
• Jika jawabannya ya daripada menambahkannya ke umum, jika jawabannya tidak daripada mengekstraknya ke folder lain.

Di dalam setiap folder fitur Anda memiliki folder yang ditentukan berdasarkan jenis.

Berikut adalah jenis folder yang akan menjadi bagian dari folder fitur.

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

Jika ada lebih dari satu file yang terkait dengan satu file, Anda dapat mengelompokkannya di folder, misalnya kode yang dihasilkan untuk kelas dalam file. Misalnya:

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

Antarmuka Pengguna (UI)

Kode yang terkait dengan antarmuka perangkat pengguna, misalnya: UI PageBuilders, layar UI, tampilan UI, komponen UI.

Layar

Layar adalah komponen antarmuka pengguna yang mengisi seluruh tampilan perangkat dan merupakan wadah tampilan atau komponen antarmuka pengguna (tombol, kotak centang, gambar dan ECT).

Juga, layar adalah tujuan navigasi aplikasi tertentu.

Pedoman:

• Layar nama file dan kelas harus sufiks dengan layar .
• Kelas layar seharusnya hanya berinteraksi dengan kelas hubit.
• Metode pembuatan layar harus dibagi dengan widget pribadi yang memisahkan area pembaruan / kasus penggunaannya . Misalnya:

 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 {}

• Setelah mengekstraksi ke widget pribadi. Jika jumlah file layar lebih besar dari 400, Anda harus memindahkan widget pribadi ke file bagian. Konvensi Penamaan File Bagian untuk Layar: $ {Nama file layar} _components.dart. Misalnya:

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 {}

• Jangan lulus hubit untuk menyaring konstruktor, alih -alih mengaksesnya menggunakan blocbuilder, bloclistener atau blocconsumer. Misalnya:

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

• Gunakan kelas widget pribadi alih -alih fungsi untuk membangun subtree, misalnya:

 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 {}

• Callback tindakan/acara layar harus menjadi bagian dari kelas layar sebagai metode.
  • Metode Callback Tindakan/Acara harus dimulai dengan Awalan .
  • Nama tindakan/acara harus sesuai dengan kasus penggunaannya. Misalnya:

 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) {}
}

Ui tampilan

Tampilan adalah komponen antarmuka pengguna yang tidak mengisi seluruh tampilan perangkat dan merupakan wadah tampilan atau komponen antarmuka pengguna (tombol, kotak centang, gambar dan ECT).

Juga, tampilan bukanlah tujuan navigasi aplikasi.

Pedoman:

• Lihat nama file dan kelas harus sufiks dengan tampilan .
• Lihat kelas seharusnya hanya berinteraksi dengan kelas hubit.
• Metode pembuatan layar harus dibagi dengan widget pribadi yang memisahkan area pembaruan / kasus penggunaannya . Misalnya:

Hasta

Cubit adalah kelas yang berisi logika bisnis untuk UI Anda, Cubit terikat pada suatu negara, yang mewakili negara UI.

Rekomendasi Pedoman:

• Hanya mencakup logika bisnis yang diperlukan untuk UI.
• Return Futures untuk tindakan publik.
• Hanya berinteraksi dengan kelas tingkat tinggi, artinya: menggunakan kasus.
• Kembalikan hasil tindakan akhir ke penelepon. Misalnya:

 Future < String ?> bookAppointment ( BookingData booking);

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

• Hanya gunakan repositori , antarmuka layanan bukan implementasi konkret.
• Suffix kelas Anda dengan hubit, contoh logincubit.
• File kelas Cubit harus berada di bawah folder Cubit dari fitur.

Keadaan Cubit.

Kelas negara bagian Cubit mewakili keadaan UI yang terikat pada waktu tertentu.

Rekomendasi Pedoman:

• Gunakan satu kelas untuk keadaan atau tentukan kelas dasar dan tentukan subkelas untuk setiap negara bagian.
• Tindakan akhir Hasil tidak boleh menjadi bagian dari negara. Misalnya:

 class LoginState {
  bool logginSuceeded // avoid this.
}

• Simpan kelas dalam file yang sama adalah kelas hubit didefinisikan.

Menggunakan kasus

Kelas yang digunakan untuk membuat operasi bisnis tunggal/tujuan/pekerjaan/tugas di domain Anda.

Pedoman:

• Nama Usecase harus selalu memiliki awalan , yang seharusnya menjadi kata kerja, yang menggambarkan pekerjaan yang dilakukan kelas ini. Contoh: class GetCurrentUserUseCase , class SignInUseCase ;
• Nama Usecase harus selalu memiliki akhiran UseCase ;
• Kelas Usecase harus selalu memiliki call() , di mana jenis pengembalian adalah hasil dari menjalankan kasus penggunaan;
• Usecase harus memiliki akses hanya ke Repositories , Services atau high level coordinators lainnya;
• Usecase seharusnya tidak memiliki akses ke DataSource atau Cubit atau berinteraksi dengan DTO atau objek tingkat rendah lainnya;
• Usecase harus digunakan di Cubit atau di UseCases lainnya.

Contoh:

 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,
      );
    });
  }
}

Repositori

Kelas yang menyediakan akses ke data hanya menggunakan operasi CRUD untuk fitur tertentu atau ruang lingkup fitur, misalnya:

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

  Future < List < Booking >> getBookings ();

  Future < void > deleteBookingById ( String id);

  Future < void > saveBooking ( Booking booking);
}

Rekomendasi Pedoman:

• Nama kelas akhiran dengan repositori.
• Hanya tentukan repositori untuk fitur atau ruang lingkup fitur dan sebutkan demikian.
• Gunakan repositori untuk menyediakan akses ke data dan memanipulasi data.
• Repositori harus mengoordinasikan akses antara sumber data atau memutuskan sumber data mana yang akan digunakan misalnya dengan bendera fitur. Contoh:

 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...
}

• Tentukan antarmuka untuk API repositori dan implementasi konkret berdasarkan jenis, misalnya:

Antarmuka

 abstract class BookingRepository {}

Implementasi

 class DefaultBookingRepository implements BookingRepository {}

class AnonymousBookingRepository implements BookingRepository {}

class PremiumBookingRepository implements BookingRepository {}

• Jangan gunakan alat, pustaka terkait platform atau melakukan logika jaringan dalam repositori, merangkumnya dalam sumber data.
• Hanya gunakan sumber data di dalam repositori.
• Hanya menerima sebagai objek input primitif atau domain dan objek domain output.
• Implementasi API repositori harus dinamai dengan nama kelas repositori sebagai akhiran.
• Hindari penamaan repositori dengan sufiks IMP , beri nama mereka menggunakan awalan default + nama repositori dasar .
• Mengembalikan jenis asinkron untuk API publik (masa depan atau aliran).
• Implementasi repositori tidak boleh mengubah API publik mereka (tipe pengembalian, argumen metode).
• File kelas repositori harus berada di bawah folder repositori fitur.

Layanan

Kelas yang menyediakan akses ke fungsionalitas untuk fitur tertentu atau ruang lingkup fitur, misalnya:

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

//...other functionalities...
}

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

//...other functionalities...
}

Rekomendasi Pedoman.

• Nama kelas akhiran dengan layanan .
• Hanya tentukan layanan untuk fitur atau ruang lingkup fitur dan sebutkan demikian.
• Gunakan layanan untuk menyediakan fungsionalitas yang diperlukan untuk mengimplementasikan logika bisnis.
• Gunakan sumber data untuk mengakses data yang diperlukan untuk mengimplementasikan logika bisnis fungsionalitas.
• Jangan gunakan alat, pustaka terkait platform atau melakukan logika jaringan dalam layanan, mengimplementasikannya dalam sumber data.
• Hanya menggunakan sumber data di dalam layanan.
• Hanya menerima sebagai objek input primitif atau domain dan objek domain output.
• Implementasi API Layanan harus dinamai dengan nama kelas layanan sebagai akhiran.
• Hindari penamaan layanan dengan sufiks impl , beri nama mereka menggunakan awalan default + nama layanan dasar .
• Mengembalikan jenis asinkron untuk API publik (masa depan atau aliran).
• Implementasi Layanan tidak boleh mengubah API publik mereka (tipe pengembalian, argumen metode).
• File kelas layanan harus di bawah folder layanan fitur.

Sumber Data

Kelas yang menerapkan akses ke data yang berlokasi secara lokal atau jarak jauh. Contoh

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

//...other functionalities...
}

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

Rekomendasi Pedoman:

• Simpan jenis dasar sumber data ke lokal dan jauh.
• Implementasi Nama Setelah Perpustakaan atau Alat yang Digunakan dan Nama Sumber Data Sebagai Sufiks, misalnya:

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

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

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

• Menangani kesalahan pustaka atau alat dalam sumber data dan mengonversinya menjadi pengecualian khusus.
• Hanya menerima sebagai objek input primitif atau domain dan objek domain output atau primitif.
• Implementasi API sumber data harus dinamai dengan nama kelas sumber data sebagai akhiran.
• Mengembalikan jenis asinkron untuk API publik (masa depan atau aliran).
• Implementasi sumber data tidak boleh mengubah API publik mereka (tipe pengembalian, argumen metode).
• Sumber data file kelas harus di bawah folder DataSources fitur.

Objek Transfer Data - DTO

Objek transfer data - digunakan untuk mentransfer data dari satu sistem ke sistem lainnya. Contoh

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

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

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

Pedoman:

• Gunakan DTO untuk mewakili tabel database.
• Gunakan DTO untuk mewakili permintaan dan respons API.
• Gunakan DTO untuk mengimplementasikan data yang diperlukan perpustakaan. Misalnya menggunakan pustaka persistensi data Anda perlu memperluas objek atau menambahkan lebih banyak bidang, buat DTO sebagai gantinya.
• Menerapkan pemetaan di kelas DTO, misalnya.

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

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

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

• Jangan mengimplementasikan penghematan atau pengambilan logika di DTO, mengimplementasikannya dalam sumber data.
• File kelas DTO harus berada di bawah folder DTOS fitur.

Objek domain

Objek domain adalah representasi kelas data dari bagian dari bisnis atau item di dalamnya, mereka digunakan untuk menjalankan logika bisnis secara independen dari platform, perpustakaan, atau alat.

Objek domain dapat mewakili, misalnya, seseorang, tempat, acara, proses bisnis, atau konsep dan faktur, produk, transaksi atau bahkan perincian seseorang .

Pedoman:

• Nama kelas objek domain harus sufiks dengan do.
• Kelas objek domain hanya boleh berisi bidang data atau metode untuk memformat bidang data.
• Kelas objek domain harus mengimplementasikan metode yang sama dan kode hash, dariJSON dan TOJSON.
• Jenis kelas objek domain hanya harus menjadi objek domain primitif atau lainnya.
• File kelas objek domain harus di bawah folder fitur Domain_Objects.

Cara menyusun aset

Sama seperti untuk struktur kode proyek.

Pertama nama fitur, lalu folder assets yang berisi file.

Contoh:

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