Anunciando a interoperabilidade nativa direta estável

FFIgen para Objective-C e JNIgen para Java/Kotlin agora são estáveis, e o Pigeon coloca os dois para trabalhar, para que seus plugins chamem código nativo diretamente

Dash conectando Dart e código nativo

No ano passado, apresentamos nossa visão para a interoperabilidade nativa direta, com o objetivo de tornar o acesso às APIs da plataforma menos trabalhoso para os desenvolvedores Flutter. Nossa meta inicial era resolver o desafio fundamental de usar platform channels para chamar APIs nativas no Android e no iOS.

Hoje, damos um passo enorme nessa direção. Estamos animados para anunciar que o FFIgen para Objective-C e o JNIgen agora são estáveis, e que o Pigeon evoluiu para colocar essas ferramentas para trabalhar por baixo dos panos.

Isso é uma grande mudança na forma como criamos plugins. Estamos deixando para trás a serialização e a latência dos platform channels tradicionais e indo na direção de bindings gerados por código, diretos, com tipagem segura e incrivelmente rápidos.

Por que criamos algo novo

Se você já criou um plugin Flutter, provavelmente já lutou com os platform channels. Eles são a forma padrão de acessar APIs nativas há anos, mas trazem muito atrito.

Os platform channels dependem de troca de mensagens. Quando seu código Dart quer conversar com iOS ou Android, ele precisa serializar os dados em um buffer binário, enviá-los por uma ponte, desserializá-los do lado nativo, executar a API nativa e depois fazer todo o processo inverso para devolver o resultado.

Esse processo dá trabalho para escrever, é propenso a erros e pode levar a problemas de performance. Se uma API nativa muda, você precisa atualizar manualmente os handlers de mensagens baseados em string dos dois lados. Além disso, os platform channels são estritamente assíncronos para manter a UI responsiva, o que resulta em muito código assíncrono repetitivo e em uma latência potencial nas chamadas nativas que deveriam ser instantâneas.

O Pigeon resolveu parte disso. Você descreve sua API uma vez em um arquivo Dart, e o Pigeon gera código com tipagem segura para os dois lados, então um erro de digitação no nome de um método vira um erro de compilação em vez de um bug em tempo de execução. Mas, por baixo dos panos, o Pigeon ainda gerava código de platform channel, então cada chamada continuava passando pelo mesmo ciclo assíncrono e serializado.

Esse ciclo é o problema que quisemos resolver: queríamos que o Dart chamasse código nativo diretamente.

Construindo um caminho direto

Começamos construindo geradores de código, o FFIgen e o JNIgen, que criam bindings em Dart para APIs nativas. Em vez de passar mensagens, seu código Dart chama o código nativo diretamente via FFI (Foreign Function Interface) ou JNI (Java Native Interface):

  • FFIgen gera bindings para APIs em C e Objective-C. O FFIgen para C é estável há anos e, a partir de hoje, o FFIgen para Objective-C também é estável.
  • JNIgen gera bindings para APIs em Java e Kotlin, desde as APIs de sistema do Android até seus próprios JARs e AARs. A partir de hoje, o JNIgen é estável.

Chamadas diretas destravam coisas que eram muito difíceis com troca de mensagens, como fazer chamadas síncronas para APIs nativas, ou passar objetos nativos e grandes volumes de dados brutos entre Dart e código nativo sem uma etapa de serialização. Você pode até chamar APIs da plataforma direto do Dart, muitas vezes sem escrever nenhum código nativo. E, como o FFIgen e o JNIgen geram código Dart simples, eles funcionam em qualquer projeto Dart, com ou sem Flutter.

Comparação da arquitetura de runtime mostrando Method Channels (em cima) vs. Interop Direta (embaixo)

Os bindings puros do FFIgen e do JNIgen funcionam bem para código de uma única plataforma e para bibliotecas com C ABI. Seja chamando uma API exclusiva do Android, usando um framework do iOS ou encapsulando uma biblioteca C como o sqlite3, há uma única API nativa para vincular, e os bindings dão acesso direto a tudo isso.

Por design, o FFIgen e o JNIgen são de baixo nível e oferecem melhor performance com acesso direto à memória, mas, em alguns casos, a gestão de memória e de threads passa a ser responsabilidade do desenvolvedor que os usa.

Uma prévia: Pigeon com interop nativa

Muitos plugins Flutter abrangem várias plataformas (como Android + iOS). Isso também significa um conjunto separado de bindings para cada plataforma, mais sua própria camada Dart para mantê-las consistentes. Essa experiência de desenvolvimento não era tão fluida quanto gostaríamos.

Então decidimos juntar a ergonomia de desenvolvimento do Pigeon com a performance da interop nativa. O Pigeon v30.0+ já pode usar o FFIgen e o JNIgen por baixo dos panos.

O Pigeon com interop nativa está disponível hoje como prévia. Você tem a segurança de tipos de um contrato Pigeon com a velocidade das chamadas FFI e JNI diretas: sem a ida e volta da serialização, chamadas síncronas quando você precisar, e chamadas a partir de isolates em background. O Pigeon cuida da conversão de dados e do tempo de vida dos objetos nativos, e gera apenas os bindings de que você precisa, então você pula o trabalho de baixo nível.

O Pigeon com interop nativa atualmente funciona apenas em Android, iOS e macOS. No Windows e no Linux, o Pigeon com platform channels funciona como sempre funcionou, e você pode gerar os dois a partir do mesmo arquivo Pigeon. Antes de recomendarmos o Pigeon com interop nativa como forma padrão de criar plugins, queremos saber como ele funciona para você, especialmente se você tentar migrar um plugin existente que já usa Pigeon.

Como usar

O fluxo de trabalho é o mesmo do Pigeon com platform channels: defina sua API em um arquivo Pigeon, rode o Pigeon e implemente a interface gerada em Swift ou Kotlin. Essa implementação continua sendo o lugar onde você chama as APIs da plataforma de que precisa. O Pigeon cuida de tudo entre seu código Dart e essa interface.

Para ativar a interop nativa, defina algumas opções na anotação @ConfigurePigeon no topo desse mesmo arquivo Pigeon.

pigeons/messages.dart: (o mesmo arquivo de definição do Pigeon que você usa hoje)

dart
@ConfigurePigeon(
  PigeonOptions(
    // ...keep your existing input and output paths...
​
    // Tells FFIgen and JNIgen where your compiled app lives (for a plugin, its example app).
    appDirectory: 'example/',
    // iOS and macOS: call your Swift implementation directly through FFI.
    swiftOptions: SwiftOptions(useFfi: true),
    // Android: call your Kotlin implementation directly through JNI.
    kotlinOptions: KotlinOptions(useJni: true),
  ),
)

Atualizamos recentemente o shared_preferences, um dos plugins mais populares do pub.dev, para usar o Pigeon com interop nativa. Se você já tem um plugin Pigeon, o código-fonte do shared_preferences é um bom exemplo.

Migrar um plugin existente para o Pigeon é, em grande parte, configuração: adicione as dependências de interop, defina useFfi e useJni, e rode o Pigeon de novo. O guia de migração é baseado nos aprendizados da migração do shared_preferences, e guia você pelas atualizações restantes de build e registro. Se você trabalha com um agente de código de IA, também existe uma skill de migração para interop nativa que guia seu agente pelos mesmos passos.

Agentes de IA estão ficando melhores em gerar wrappers Dart idiomáticos a partir da saída bruta do FFIgen e do JNIgen, mas ainda se beneficiam do que o Pigeon oferece: uma API multiplataforma consistente, segurança de memória entre os runtimes Dart e nativo, código de plugin testável com unit tests, orquestração da toolchain de cada plataforma, e código gerado que continua determinístico e fácil de manter ao longo do tempo. Seu feedback sobre a prévia vai moldar o caminho até lá.

Experimente a interop nativa direta hoje

Este marco é o resultado de anos de design, iteração e feedback. Queremos agradecer muitíssimo a todos os autores de pacotes, colaboradores, desenvolvedores e participantes do Early Access Program (EAP), especialmente Jon Holtan, Rody Davis, Dominik Roszkowski, Alexander Thiele e Morgan McKenzie, que testaram as primeiras prévias, revisaram nossa nova documentação, reportaram bugs e ajudaram a moldar estas versões.

Se você está criando plugins ou precisa acessar APIs nativas, adoraríamos que você experimentasse a interop nativa direta. Acesse nossa documentação de interop reestruturada no flutter.dev para mais detalhes sobre cada ferramenta e como começar. E se você migrar um plugin para o Pigeon com interop nativa, nos conte se tiver quaisquer problemas.

Mal podemos esperar para ver o que você vai criar!

Mais do Flutter