flutter guidelines

Pautas de flutador

¡Hola! Este documento contiene mis recomendaciones personales para políticas, procedimientos y estándares sobre cómo se debe realizar el desarrollo.

Estructura del código de proyecto

El código del proyecto debe estructurarse con una mezcla de carpeta por función y carpeta por tipo .

Es decir, en el nivel de raíz, tiene carpetas que definen características. Por ejemplo:

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

La función Common/Core contiene clases, funciones o widgets que, por defecto, deberían estar disponibles en cualquier característica.

Entonces, la idea es tener características de su aplicación divididas por carpetas de nivel superior.

Piense en cada carpetas de nivel superior como un paquete de dardo/flutador separado, dependencias o límites de acceso de su aplicación.

Entonces, si agrega algo a la carpeta común, debe preguntarse, ¿el 99.% de las características de nuestra aplicación lo necesitarán?

Si lo considera una dependencia, la dependencia común siempre se declara en su pubspec.yaml.

Entonces, antes de agregar una clase, función o un widget a la carpeta común, pregúntese:

• ¿Es algo que cada característica necesita en pubspec.yaml, o es más opcional?
• Si la respuesta es sí, agregarla a común, si la respuesta es no, extraerla a otra carpeta.

Dentro de cada carpeta de características tiene carpetas definidas por tipo.

Aquí están los tipos de carpetas que serían parte de una carpeta de características.

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

Si hay más de un archivo relacionado con un solo archivo, puede agruparlos en una carpeta, por ejemplo, el código generado para una clase en un archivo. Por ejemplo:

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

Interfaz de usuario (UI)

Código relacionado con la interfaz del dispositivo del usuario, por ejemplo: constructores de páginas de interfaz de usuario, pantallas de interfaz de usuario, vista de interfaz de usuario, componentes de UI.

Pantalla

Una pantalla es un componente de interfaz de usuario que llena toda la pantalla del dispositivo y es el contenedor de la vista o componente de la interfaz de usuario (botón, casillas de verificación, imágenes y ECT).

Además, una pantalla es un destino específico de navegación de aplicaciones.

Pauta:

• El nombre de archivo y las clases de las pantallas deben sufrirse con la pantalla .
• Las clases de pantallas solo deben interactuar con las clases de CUBIT.
• El método de compilación de la pantalla debe dividirse por widgets privados que separen su área de actualización / caso de uso . Por ejemplo:

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

• Después de extraer a widgets privados. Si el número de archivos de pantalla de líneas es superior a 400, debe mover los widgets privados a un archivo de pieza. Convención de nomenclatura de archivos para la pantalla: $ {nombre del archivo de pantalla} _Components.Dart. Por ejemplo:

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

• No pase el Cubit a los constructores de pantalla, sino que accedan a ellos usando BlocBuilder, BlocListener o Blocconsumer. Por ejemplo:

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

• Use clases de widgets privados en lugar de funciones para construir subárboles, por ejemplo:

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

• Una acción de llamada de acción/evento del evento debe ser parte de la clase de pantalla como método.
  • El método de devolución de llamada de acción/evento debe comenzar con el prefijo.
  • El nombre de una acción/evento debe coincidir con su caso de uso. Por ejemplo:

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

Vista de ui

Una vista es un componente de interfaz de usuario que no llena toda la pantalla del dispositivo y es el contenedor de la vista o componente de la interfaz de usuario (botón, casillas de verificación, imágenes y ECT).

Además, una vista no es un destino de navegación de aplicaciones.

Pauta:

• Ver el nombre de archivo y las clases deben sufijar con la vista .
• Las clases de vista solo deben interactuar con las clases de CUBIT.
• El método de compilación de la pantalla debe dividirse por widgets privados que separen su área de actualización / caso de uso . Por ejemplo:

Codazo

Los codos son clases que contienen lógica de negocios para su interfaz de usuario, Cubit está vinculado a un estado, que representan el estado de la UI.

Recomendaciones de directriz:

• Solo cubre la lógica comercial necesaria para la interfaz de usuario.
• Devuelve futuros para acciones públicas.
• Solo interactúa con clases de alto nivel, que significa: casos de uso.
• Devuelve el resultado de acciones finales a la persona que llama. Por ejemplo:

 Future < String ?> bookAppointment ( BookingData booking);

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

• Solo use repositorios , interfaces de servicios , no implementaciones concretas.
• Sufijo su clase con CUBIT, Ejemplo de logincubit.
• Los archivos de clase CUBIT deben estar debajo de la carpeta Cubits de la función.

Estado de CUBIT.

Una clase estatal de cúbito representa el estado de la interfaz de usuario limitado a él un momento determinado.

Recomendaciones de directriz:

• Use una sola clase para el estado o defina una clase base y defina la subclase para cada estado.
• El resultado de las acciones finales no debe ser parte del estado. Por ejemplo:

 class LoginState {
  bool logginSuceeded // avoid this.
}

• Mantenga la clase en el mismo archivo donde se definió la clase Cubit.

Casos de uso

Clases que se utilizan para hacer una sola operación comercial/objetivo/trabajo/tarea en su dominio.

Pautas:

• El nombre USECase siempre debe tener un prefijo , que debería ser un verbo, que describe el trabajo que esta clase está haciendo. Ej: class GetCurrentUserUseCase , class SignInUseCase ;
• El nombre USECase siempre debe tener un sufijo UseCase ;
• La clase USECase siempre debe tener una call() , donde el tipo de retorno es el resultado de ejecutar el caso de uso;
• USECase debe tener acceso solo a Repositories , Services o cualquier otro high level coordinators ;
• USECase no debe tener acceso a DataSource o Cubit o interactuar con DTO o cualquier otro objeto de bajo nivel;
• USECase debe usarse en Cubit o en otros UseCases .

Ejemplos:

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

Repositorios

Clases que proporcionan acceso a datos utilizando solo operaciones CRUD para una característica específica o un alcance de una característica, por ejemplo:

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

  Future < List < Booking >> getBookings ();

  Future < void > deleteBookingById ( String id);

  Future < void > saveBooking ( Booking booking);
}

Recomendaciones de directriz:

• Nombre de clase sufijo con repositorio.
• Solo defina los repositorios para características o alcance de características y nombrarlos así.
• Use repositorios para proporcionar acceso a datos y manipular datos.
• Los repositorios deben coordinar el acceso entre fuentes de datos o decidir qué fuente de datos usar, por ejemplo, por indicador de características. Ejemplo:

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

• Definir interfaces para la API de repositorio e implementación concreta por tipo, por ejemplo:

Interfaz

 abstract class BookingRepository {}

Implementación

 class DefaultBookingRepository implements BookingRepository {}

class AnonymousBookingRepository implements BookingRepository {}

class PremiumBookingRepository implements BookingRepository {}

• No use herramientas, bibliotecas relacionadas con la plataforma ni realice la lógica de red en repositorios, encapsule eso en fuentes de datos.
• Solo use fuentes de datos dentro de repositorios.
• Solo reciba como objeto primitivo o de dominio de entrada y objetos de dominio de salida.
• Las implementaciones de la API del repositorio deben nombrarse con el nombre de la clase de repositorio como sufijo.
• Evite nombrar repositorios con sufijo Impl , nombrarlos utilizando el nombre predeterminado de repositorios de prefijo + base .
• Devuelve el tipo asíncrono para la API pública (futuro o transmisión).
• La implementación del repositorio no debe cambiar su API pública (tipo de retorno, argumentos de método).
• Los archivos de clase de repositorio deben estar en la carpeta de repositorios de la función.

Servicios

Clases que proporcionan acceso a funcionalidades para una característica específica o un alcance de una característica, por ejemplo:

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

//...other functionalities...
}

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

//...other functionalities...
}

Recomendaciones de directriz.

• Nombre de clase de sufijo con servicio .
• Solo defina los servicios para características o alcance de las características y nombrarlos así.
• Use los servicios para proporcionar funcionalidades necesarias para implementar una lógica comercial.
• Use fuentes de datos para acceder a los datos requeridos para implementar una lógica comercial de funcionalidad.
• No utilice herramientas, bibliotecas relacionadas con la plataforma ni realice la lógica de red en los servicios, implementanlo en fuentes de datos.
• Solo use fuentes de datos dentro de los servicios.
• Solo reciba como objeto primitivo o de dominio de entrada y objetos de dominio de salida.
• Las implementaciones de la API del servicio deben nombrarse con el nombre de la clase de servicio como sufijo.
• Evite los servicios de nombres con sufijo Impl , nombres con el nombre de prefijo predeterminado + Nombre del servicio base .
• Devuelve el tipo asíncrono para la API pública (futuro o transmisión).
• La implementación del servicio no debe cambiar su API pública (tipo de retorno, argumentos de método).
• Los archivos de clase de servicio deben estar en la carpeta de servicios de la función.

Fuentes de datos

Clases que implementan acceso a datos ubicados locales o remotamente. Ejemplo

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

//...other functionalities...
}

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

Recomendaciones de directriz:

• Mantenga el tipo base de fuentes de datos en local y remoto.
• Implementación de nombre después de la biblioteca o la herramienta utilizada y el nombre de la fuente de datos como sufijo, por ejemplo:

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

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

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

• Maneje los errores de biblioteca o herramienta en la fuente de datos y conviértalos en la excepción personalizada de la aplicación.
• Solo reciba como objeto primitivo o de dominio de entrada y objetos de dominio de salida o primitivos.
• Las implementaciones de la API de fuente de datos deben nombrarse con el nombre de la clase de origen de datos como sufijo.
• Devuelve el tipo asíncrono para la API pública (futuro o transmisión).
• La implementación de las fuentes de datos no debe cambiar su API pública (tipo de retorno, argumentos de método).
• Fuentes de datos Los archivos de clase deben estar en la carpeta DataSources de la función.

Objetos de transferencia de datos - DTO

Objetos de transferencia de datos: utilizados para transferir datos de un sistema a otro. Ejemplo

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

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

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

Pautas:

• Use DTO para representar tablas de bases de datos.
• Use DTO para representar la solicitud y la respuesta de API.
• Use DTO para implementar los datos requeridos de la biblioteca. Por ejemplo, para usar una biblioteca de persistencia, sus datos deben extender un objeto o agregar más campos, cree un DTO en su lugar.
• Implemente mapeadores en la clase DTO, por ejemplo.

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

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

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

• No implementa la lógica de ahorro o obteniendo en DTO, implementala en fuentes de datos.
• Los archivos de clase DTO deben estar debajo de la carpeta DTOS de la función.

Objeto de dominio

El objeto de dominio es la representación de clases de datos de una parte del negocio o un elemento dentro de él, se utilizan para ejecutar la lógica comercial independientemente de la plataforma, la biblioteca o las herramientas.

Un objeto de dominio puede representar, por ejemplo, una persona, lugar, evento, proceso comercial o concepto y factura, un producto, una transacción o incluso detalles de una persona .

Pauta:

• Clases de objetos de dominio El nombre debe sufrirse con DO.
• Las clases de objetos de dominio solo deben contener campos o método de datos para formatear campos de datos.
• Las clases de objetos de dominio deben implementar iguales y métodos de código hash, deJSON y TOJSON.
• Clases de objetos de dominio Tipo de campos solo debe ser primitivo u otro objeto de dominio.
• Los archivos de clase de objeto de dominio deben estar en la carpeta Domain_Objects de la función.

Cómo estructurar activos

Lo mismo que para la estructura del código de proyecto.

Primero primero el nombre de la función, luego la carpeta assets que contiene archivos.

Ejemplo:

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