Используйте сгенерированные SDK Flutter.

SDK клиента Firebase SQL Connect позволяют вызывать серверные запросы и мутации непосредственно из приложения Firebase. Вы генерируете пользовательский SDK параллельно с проектированием схем, запросов и мутаций, которые развертываете в своей службе SQL Connect . Затем вы интегрируете методы из этого SDK в свою клиентскую логику.

Как мы уже упоминали ранее, важно отметить, что запросы и мутации SQL Connect не отправляются клиентским кодом и не выполняются на сервере. Вместо этого, при развертывании операции SQL Connect хранятся на сервере, как и в Cloud Functions. Это означает, что вам необходимо развернуть соответствующие изменения на стороне клиента, чтобы избежать нарушения работы существующих пользователей (например, в старых версиях приложения).

Именно поэтому SQL Connect предоставляет вам среду разработки и инструменты, позволяющие создавать прототипы развернутых на сервере схем, запросов и мутаций. Он также автоматически генерирует SDK для клиентской части во время создания прототипов.

When you've iterated updates to your service and client apps, both server- and client-side updates are ready to deploy.

Каков рабочий процесс разработки клиентской части?

Если вы следовали инструкциям в разделе «Начало работы» , вы познакомились с общим процессом разработки SQL Connect . В этом руководстве вы найдете более подробную информацию о генерации Flutter SDK из вашей схемы и работе с клиентскими запросами и мутациями.

To summarize, to use generated Flutter SDKs in your client apps, you'll follow these prerequisite steps:

1. Добавьте Firebase в ваше Flutter- приложение.
2. Install the flutterfire CLI dart pub global activate flutterfire_cli .
3. Запустите команду flutterfire configure .

Затем:

1. Разработайте схему вашего приложения.

2. Настройка генерации SDK:

   • With the Add SDK to app button in our SQL Connect VS Code extension
   • Обновите файл connector.yaml .

3. Initialize your client code and import libraries .

4. Реализуйте вызовы запросов и мутаций .

5. Set up and use the SQL Connect emulator and iterate.

Сгенерируйте свой Flutter SDK

Use the Firebase CLI to set up SQL Connect generated SDKs in your apps. The init command should detect all apps in the current folder and install generated SDKs automatically.

firebase init dataconnect:sdk

Обновляйте SDK во время прототипирования.

If you have SQL Connect VS Code extension installed, it will always keep generated SDKs up to date.

If you don't use SQL Connect VS Code extension, you can use Firebase CLI to keep generated SDKs up to date.

firebase dataconnect:sdk:generate --watch

Генерация SDK в конвейерах сборки

You can use the Firebase CLI to generate SQL Connect SDKs in CI/CD build processes.

firebase dataconnect:sdk:generate

Настройка клиентского кода

Инициализируйте приложение SQL Connect .

First, initialize your app using the standard Firebase setup instructions .

Затем установите плагин SQL Connect :

flutter pub add firebase_data_connect

Инициализируйте SDK SQL Connect Flutter.

Initialize your SQL Connect instance using the information you used to set up SQL Connect . Find this information in the Databases & Storage > SQL Connect page of the Firebase console.

Импорт библиотек

There are two sets of imports needed to initialize your client code, general SQL Connect imports and specific, generated SDK imports.

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

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

Используйте запросы на стороне клиента.

The generated code will already come with predefined Query Refs. All you need to do is import and call execute on them.

import 'generated/movies.dart';

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

Вызов методов запроса SDK

Here's an example using these action shortcut functions:

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

Необязательные поля

В некоторых запросах могут быть необязательные поля. В таких случаях Flutter SDK предоставляет метод-конструктор, и их необходимо будет задать отдельно.

For example, the field rating is optional when calling createMovie , so you need to provide it in the builder function.

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

Подписаться на изменения

См. раздел «Получение обновлений в режиме реального времени из SQL Connect .

Обработка изменений в полях перечисления

An app's schema can contain enumerations , which can be accessed by your GraphQL queries .

As an app's design changes, you may add new enum supported values. For example, imagine that later in your application's lifecycle you decide to add a FULLSCREEN value to the AspectRatio enum.

In the SQL Connect workflow, you can use local development tooling to update your queries and SDKs.

However, before you release an updated version of your clients, older deployed clients may break.

Пример отказоустойчивой реализации

The generated SDK forces handling of unknown values. That is, client code must unwrap the EnumValue object into either Known or 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}');
  }
}

Включите кэширование на стороне клиента.

SQL Connect имеет дополнительную функцию кэширования на стороне клиента, которую можно включить, отредактировав файл connector.yaml . При включении этой функции сгенерированные клиентские SDK будут локально кэшировать ответы на запросы, что может уменьшить количество запросов к базе данных, выполняемых вашим приложением, и позволит зависимым от базы данных частям вашего приложения работать даже при перебоях в сети.

To enable client-side caching, add a client caching configuration to your connector configuration:

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

This configuration has two parameters, both optional:

• maxAge : The maximum age a cached response can be before the client SDK fetches fresh values. Examples: "0", "30s", "1h30m".

  Значение по умолчанию для maxAge равно 0 , что означает, что ответы кэшируются, но клиентский SDK всегда будет получать актуальные значения. Кэшированные значения будут использоваться только в том случае, если для execute() указан параметр CACHE_ONLY и начальный результат возвращается из subscribe() .

• storage : Клиентский SDK можно настроить для кэширования ответов либо в persistent хранилище, либо в memory . Результаты, кэшированные в persistent хранилище, сохраняются после перезапуска приложения. При разработке для Android или iOS по умолчанию используется persistent . При разработке для веб-браузеров поддерживается только хранилище memory .

После обновления конфигурации кэширования вашего коннектора перегенерируйте клиентские SDK и пересоберите приложение. После этого функции execute() и subscribe() будут кэшировать ответы и использовать кэшированные значения в соответствии с настроенной вами политикой. Обычно это происходит автоматически, без каких-либо дополнительных действий с вашей стороны; однако обратите внимание на следующее:

• Поведение функции execute() по умолчанию описано выше: если результат запроса кэширован и кэшированное значение не старше значения maxAge , то используется кэшированное значение. Это поведение по умолчанию называется политикой PREFER_CACHE .

  You can also specify to individual invocations of execute() to either only serve cached values ( CACHE_ONLY ) or to unconditionally fetch fresh values from the server ( SERVER_ONLY ).

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

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

• При вызове метода subscribe() всегда немедленно возвращается кэшированное содержимое, если оно существует, независимо от значения параметра maxAge . Последующие вызовы метода execute() будут уведомлять слушателей в соответствии с настроенным maxAge .

Используйте мутации на стороне клиента.

Mutations are accessible in the same way as queries.

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

Создавайте прототипы и тестируйте свои приложения на Flutter.

Для обеспечения возможности использования локального эмулятора клиенты должны быть оснащены соответствующими инструментами.

You can use the SQL Connect emulator, whether from the SQL Connect VS Code extension or from the CLI.

Процесс подключения приложения к эмулятору одинаков в обоих случаях.

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();

To switch to production resources, comment out lines for connecting to the emulator.

Типы данных в Dart SDK

The SQL Connect server represents common GraphQL data types. These are represented in the SDK as follows.