Como escrever um bom plugin para Flutter

Aprenda boas práticas para projetar, implementar, documentar e manter um plugin Flutter de alta qualidade

Plugins são essenciais para o ecossistema Flutter. Eles permitem que pessoas desenvolvedoras Flutter interajam com a plataforma em que o app está rodando.

Em outubro de 2018, há centenas de plugins disponíveis no pub. É muito importante que os plugins tenham alta qualidade, independentemente de virem do Google ou de colaboradores externos. Este artigo explora o que torna um bom plugin e como escrever um.

Pense primeiro na funcionalidade, depois nas APIs

Muitas vezes, ao escrever um plugin, você está tentando usar uma biblioteca nativa existente. O natural é olhar a API dessa biblioteca e expor uma API equivalente em Dart. Os problemas surgem quando as APIs não coincidem entre as plataformas e você é forçado a expor a interseção das APIs, muitas vezes com consequências prejudiciais…

Ao escrever plugins, pense primeiro na funcionalidade, não nas APIs. Por exemplo, se você está escrevendo um plugin de armazenamento local, provavelmente precisa de APIs que suportem armazenar valores de vários tipos, além de uma forma de recuperá-los. Depois de definir qual tipo de funcionalidade você quer oferecer, pense no design da sua API em Dart:

dart
class StoragePlugin {
  /// Reads a string
  Future<String> getString(String key) async {}
​
  /// Writes a string
  Future<void> setString(String key, String value) async {}
}

Só depois de ter a API em Dart é que você deve começar a olhar a API pública e ver como as suas chamadas precisam ser adaptadas para as chamadas da API da biblioteca específica de cada plataforma:

dart
class StoragePlugin {
  Future<String> getString(String key) async {
    if (Platform.isIos) {
      return await callMethodChannel('fetchValue', {'id': base64encode(key)});
    } else if (Platform.isAndroid) {
      return await callMethodChannel('fetchValue', {'id': key});
    }
  }
​
  Future<void> setString(String key, String value) async {
    if (Platform.isIos) {
      await callMethodChannel('setValue', {'id': base64encode(key), 'value': value});
    } else if (Platform.isAndroid) {
      await callMethodChannel('setValue', {'id': key, 'value': value});
    }
  }
}

Se há uma funcionalidade que você gostaria de oferecer e que não é suportada por uma plataforma, é aceitável que essa API falhe de forma graciosa nessa plataforma. Você não deve derrubar o app, e o comportamento deve estar bem documentado. Você também deve solicitar à plataforma a funcionalidade que falta, para que o seu plugin possa ficar completo.

Evite métodos de API específicos de plataforma

O Flutter é agnóstico de plataforma, então não é adequado que apps Flutter sejam obrigados a escrever código específico de plataforma. Se quem usa o plugin estiver fazendo o seguinte no seu app:

dart
if (Platform.isIos) {
  myPlugin.doIOSThing();
} else if (Platform.isAndroid) {
  myPlugin.doAndroidThing();
}

considere mover a lógica específica de plataforma para o próprio plugin, para que essa pessoa possa escrever:

dart
myPlugin.doThing();

Evite suportar apenas uma plataforma

Você pode ser tentado a começar pequeno e escrever um plugin para uma funcionalidade que quer só para Android. Infelizmente, quando o plugin for publicado, isso cria confusão para quem usa o plugin quando o app se comporta mal em plataformas não suportadas.

Há exceções, como o Android Intent. Intents só se aplicam ao Android, então é aceitável expor um plugin apenas para Android para eles.

Faça seu plugin fácil de navegar e testar

Como regra geral, seu plugin deve conter principalmente código Dart.

  • A camada nativa é difícil de testar, já que normalmente lida com bibliotecas que não funcionam em emuladores.

  • O Flutter é escrito majoritariamente em Dart. Apps Flutter são inteiramente escritos em Dart. Ao rastrear o código, seria ótimo que a maior parte da lógica pudesse ser entendida a partir do Dart.

A única razão para você precisar de uma camada nativa é quando a implementação naquela plataforma exige manter estado e/ou fazer processamento. Um bom exemplo é a autenticação biométrica, que tem um ciclo de vida complexo próprio no Android e precisa ser gerenciado do lado nativo.

Se você precisar escrever muito código nativo, considere mover a funcionalidade para classes individuais que possam ser testadas com unit tests.

Idealmente, sua camada nativa simplesmente escuta chamadas de método, as encaminha para uma biblioteca existente e devolve os resultados para o Dart. Se você estiver fazendo algo além disso, veja se pode mover para o lado Dart. Você vai acabar escrevendo menos código dessa forma, já que a lógica provavelmente precisaria ser repetida em várias plataformas.

Evite escrever métodos estáticos (ou globais)

É tentador expor apenas:

dart
Future<User> authenticate() async {
  // Some code
}

No entanto, prefira:

dart
class AuthenticatePlugin {
  Future<User> authenticate() async {
    // Some code
  }
}

o que torna o plugin fácil de mockar ou simular. Quem usa pode trocar facilmente a implementação real, para que os apps funcionem em um emulador ou em um test harness.

Plugins são uma das melhores formas de ampliar a funcionalidade do Flutter. Se você tiver mais ideias sobre boas práticas para plugins, compartilhe nos comentários. Feliz programação!

Mais do Flutter