Usar os SDKs do Flutter gerados

Os SDKs de cliente Firebase SQL Connect permitem chamar consultas e mutações do lado do servidor diretamente de um app do Firebase. Você gera um SDK de cliente personalizado em paralelo ao criar os esquemas, consultas e mutações que implanta no seu SQL Connect serviço. Em seguida, integre métodos desse SDK à lógica do cliente.

Como já mencionamos, é importante observar que SQL Connect consultas e mutações não são enviadas pelo código do cliente e executadas no servidor. Em vez disso, quando implantadas, as SQL Connect operações são armazenadas no servidor, como as Cloud Functions. Isso significa que você precisa implantar as mudanças correspondentes no lado do cliente para evitar quebrar os usuários atuais (por exemplo, em versões mais antigas do app).

É por isso que SQL Connect oferece um ambiente de desenvolvimento e ferramentas que permitem criar protótipos de esquemas, consultas e mutações implantados no servidor. Ele também gera SDKs do lado do cliente automaticamente durante a criação do protótipo.

Quando você itera atualizações nos apps de serviço e cliente, as atualizações do servidor e do lado do cliente ficam prontas para implantação.

Qual é o fluxo de trabalho de desenvolvimento do cliente?

Se você seguiu o guia de introdução, já conhece o fluxo de desenvolvimento geral do SQL Connect. Neste guia, você vai encontrar informações mais detalhadas sobre como gerar SDKs do Flutter no seu esquema e trabalhar com consultas e mutações do cliente.

Para resumir, para usar os SDKs do Flutter gerados nos apps do cliente, siga estas etapas de pré-requisito:

1. Adicione o Firebase ao seu Flutter app.
2. Instale a CLI do FlutterFire dart pub global activate flutterfire_cli.
3. Execute flutterfire configure.

Em seguida:

1. Desenvolva o esquema do app.

2. Configure a geração do SDK:

   • Com o botão Adicionar SDK ao app na extensão do SQL Connect VS Code
   • Atualizando o seu connector.yaml.

3. Inicialize o código do cliente e importe bibliotecas.

4. Implemente chamadas para consultas e mutações.

5. Configure e use o emulador SQL Connect e faça iterações.

Gerar o SDK do Flutter

Use a CLI para configurar os SDKs gerados nos seus apps.FirebaseSQL Connect O comando init detecta todos os apps na pasta atual e instala os SDKs gerados automaticamente.

firebase init dataconnect:sdk

Atualizar SDKs durante a criação de protótipos

Se você tiver a extensão do SQL Connect VS Code instalada, ela sempre vai manter os SDKs gerados atualizados.

Se você não usa a extensão do SQL Connect VS Code, use a CLI do Firebase para manter os SDKs gerados atualizados.

firebase dataconnect:sdk:generate --watch

Gerar SDKs em pipelines de build

É possível usar a CLI do Firebase para gerar SQL Connect SDKs em processos de build de CI/CD.

firebase dataconnect:sdk:generate

Configurar o código do cliente

Inicializar o app SQL Connect

Primeiro, inicialize o app usando as instruções de configuração padrão do Firebase.

Em seguida, instale o plug-in SQL Connect:

flutter pub add firebase_data_connect

Inicializar o SDK do SQL Connect Flutter

Inicialize a instância do SQL Connect usando as informações que você usou para configurar o SQL Connect (tudo disponível na guia SQL Connect do console Firebase).

Importar bibliotecas

Há dois conjuntos de importações necessários para inicializar o código do cliente: importações gerais SQL Connect e importações específicas do SDK gerado.

// general imports
import 'package:firebase_data_connect/firebase_data_connect.dart';

// generated queries and mutations from SDK
import 'generated/movies.dart';

Usar consultas no lado do cliente

O código gerado já vem com referências de consulta predefinidas. Tudo o que você precisa fazer é importar e chamar execute nelas.

import 'generated/movies.dart';

await MoviesConnector.instance.listMovies().execute();

Chamar métodos de consulta do SDK

Confira um exemplo usando essas funções de atalho de ação:

import 'generated/movies.dart';

function onBtnClick() {
  // This will call the generated Dart from the CLI and then make an HTTP request to the server.
  MoviesConnector.instance.listMovies().execute().then(data => showInUI(data)); // == MoviesConnector.instance.listMovies().ref().execute();
}

Campos opcionais

Algumas consultas podem ter campos opcionais. Nesses casos, o SDK do Flutter expõe um método de builder e precisa ser definido separadamente.

Por exemplo, o campo rating é opcional ao chamar createMovie. Portanto, é necessário fornecê-lo na função do builder.

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi"}).rating(5).execute();

Inscrever-se em mudanças

É possível se inscrever em mudanças (que serão atualizadas sempre que você executar uma consulta).

QueryRef<ListMoviesData, void> listRef = MoviesConnector.instance.listMovies().ref();

// subscribe will immediately invoke the query if no execute was called on it previously.
listRef.subscribe().listen((data) {
  updateUIWithMovies(data.movies);
});

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();
await listRef.execute(); // will update the subscription above`

Processar mudanças em campos de enumeração

O esquema de um app pode conter enumerações, que podem ser acessadas pelas suas consultas do GraphQL.

À medida que o design de um app muda, você pode adicionar novos valores compatíveis com enumeração. Por exemplo, imagine que, mais tarde no ciclo de vida do aplicativo, você decida adicionar um valor FULLSCREEN à enumeração AspectRatio.

No fluxo de trabalho SQL Connect, é possível usar ferramentas de desenvolvimento local para atualizar consultas e SDKs.

No entanto, antes de lançar uma versão atualizada dos clientes, os clientes implantados mais antigos podem ser interrompidos.

Exemplo de implementação resiliente

O SDK gerado força o processamento de valores desconhecidos. Ou seja, o código do cliente precisa desembrulhar o objeto EnumValue em Known ou Unknown.

final result = await MoviesConnector.instance.listMovies().execute();

if (result.data != null && result.data!.isNotEmpty) {
  handleEnumValue(result.data![0].aspectratio);
}

void handleEnumValue(EnumValue<AspectRatio> aspectValue) {
  if (aspectValue.value != null) {
    switch(aspectValue.value!) {
      case AspectRatio.ACADEMY:
        print("This movie is in Academy aspect");
        break;
      case AspectRatio.WIDESCREEN:
        print("This movie is in Widescreen aspect");
        break;
      case AspectRatio.ANAMORPHIC:
        print("This movie is in Anamorphic aspect");
        break;
      case AspectRatio.IMAX:
        print("This movie is in IMAX aspect");
    }
  } else {
    print("Unknown aspect ratio detected: ${aspectValue.stringValue}");
  }
}

Ativar o armazenamento em cache do lado do cliente

SQL Connect tem um recurso opcional de armazenamento em cache do lado do cliente, que você pode ativar editando o arquivo connector.yaml. Quando esse recurso está ativado, os SDKs de cliente gerados armazenam em cache localmente as respostas de consulta, o que pode reduzir o número de solicitações de banco de dados feitas pelo app e permite que as partes dependentes do banco de dados do app funcionem quando a disponibilidade da rede é interrompida.

Para ativar o armazenamento em cache do lado do cliente, adicione uma configuração de armazenamento em cache do cliente à configuração do conector:

generate:
  javascriptSdk:
    outputDir: ../dart/
    package: "dataconnect_generated"
    clientCache:
      maxAge: 5s
      storage: memory

Essa configuração tem dois parâmetros, ambos opcionais:

• maxAge: a idade máxima que uma resposta armazenada em cache pode ter antes que o SDK do cliente busque novos valores. Exemplos: "0", "30s", "1h30m".

  O valor padrão de maxAge é 0, o que significa que as respostas são armazenadas em cache, mas o SDK do cliente sempre vai buscar novos valores. Os valores armazenados em cache só serão usados quando CACHE_ONLY for especificado para execute() e o resultado inicial retornado de subscribe().

• storage: o SDK do cliente pode ser configurado para armazenar respostas em cache no armazenamento persistent ou na memory. Os resultados armazenados em cache no armazenamento persistent vão persistir nas reinicializações do app. Ao segmentar o Android ou o iOS, o padrão é persistent. Ao segmentar navegadores da Web, apenas o armazenamento memory é compatível.

Depois de atualizar a configuração de armazenamento em cache do conector, regenere os SDKs de cliente e recrie o app. Depois disso, execute() e subscribe() vão armazenar respostas em cache e usar valores armazenados em cache de acordo com a política configurada. Isso geralmente acontece automaticamente, sem etapas adicionais da sua parte. No entanto, observe o seguinte:

• O comportamento padrão de execute() é descrito acima: se um resultado for armazenado em cache para uma consulta e o valor armazenado em cache não for mais antigo que maxAge, use o valor armazenado em cache. Esse comportamento padrão é chamado de política PREFER_CACHE.

  Também é possível especificar invocações individuais de execute() para veicular apenas valores armazenados em cache (CACHE_ONLY) ou para buscar incondicionalmente novos valores do servidor (SERVER_ONLY).

  await queryRef.execute(fetchPolicy: QueryFetchPolicy.cacheOnly);
  

  await queryRef.execute(fetchPolicy: QueryFetchPolicy.serverOnly);
  

• Ao chamar subscribe(), ele sempre vai retornar imediatamente o conteúdo armazenado em cache, se existir, independentemente da configuração maxAge. As chamadas subsequentes para execute() vão notificar os listeners de acordo com o maxAge configurado.

Usar mutações no lado do cliente

As mutações são acessíveis da mesma forma que as consultas.

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();

Criar protótipos e testar apps do Flutter

Instrumentar clientes para usar um emulador local

É possível usar o SQL Connect emulator, seja na extensão do SQL Connect VS Code ou na CLI.

A instrumentação do app para se conectar ao emulador é a mesma para os dois cenários.

import 'package:firebase_data_connect/firebase_data_connect.dart';
import 'generated/movies.dart';

MoviesConnector.instance.dataConnect
          .useDataConnectEmulator('127.0.0.1', 9399);

// Make calls from your app
QueryRef<ListMoviesData, void> ref = MoviesConnector.instance.listMovies.ref();

Para mudar para recursos de produção, comente as linhas de conexão com o emulador.

Tipos de dados no SDK do Dart

O servidor SQL Connect representa tipos de dados comuns do GraphQL. Eles são representados no SDK da seguinte maneira.