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

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

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

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

После внесения изменений в ваши сервисные и клиентские приложения, обновления как на стороне сервера, так и на стороне клиента готовы к развертыванию.

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

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

Вкратце, для использования сгенерированных Swift SDK в клиентских приложениях вам необходимо выполнить следующие предварительные шаги:

1. Добавьте Firebase в свое iOS- приложение.

2. Чтобы использовать сгенерированный SDK, настройте его как зависимость в Xcode.

   В верхней панели навигации Xcode выберите File > Add Package Dependencies > Add Local и выберите папку, содержащую сгенерированный Package.swift .

Затем:

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

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

   • С помощью кнопки «Добавить SDK в приложение» в нашем расширении SQL Connect для VS Code.
   • Обновите файл connector.yaml

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

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

5. Настройте и используйте эмулятор SQL Connect и выполните итерации.

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

Используйте Firebase CLI для настройки сгенерированных SQL Connect SDK в ваших приложениях. Команда init должна обнаружить все приложения в текущей папке и автоматически установить сгенерированные SDK.

firebase init dataconnect:sdk

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

Если у вас установлено расширение SQL Connect для VS Code, оно всегда будет поддерживать сгенерированные SDK в актуальном состоянии.

Если вы не используете расширение SQL Connect для VS Code, вы можете использовать Firebase CLI для обновления сгенерированных SDK.

firebase dataconnect:sdk:generate --watch

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

С помощью Firebase CLI можно генерировать SDK SQL Connect в процессах сборки CI/CD.

firebase dataconnect:sdk:generate

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

Инициализируйте свой экземпляр SQL Connect , используя информацию, которую вы использовали для настройки SQL Connect . Эту информацию можно найти на странице «Базы данных и хранилище > SQL Connect» в консоли Firebase .

Получить экземпляр коннектора

Код для вашего коннектора будет сгенерирован эмулятором SQL Connect . Если имя вашего коннектора — movies , а пакет — movies , как указано в connector.yaml , то получите объект коннектора, вызвав:

let connector = DataConnect.moviesConnector

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

С помощью объекта коннектора вы можете выполнять запросы и мутации, определенные в исходном коде GraphQL. Предположим, ваш коннектор имеет следующие определенные операции:

mutation createMovie($title: String!, $releaseYear: Int!, $genre: String!, $rating: Int!) {
  movie_insert(data: {
    title: $title
    releaseYear: $releaseYear
    genre: $genre
    rating: $rating
  })
}

query getMovieByKey($key: Movie_Key!) {
  movie(key: $key) { id title }
}

query listMoviesByGenre($genre: String!) {
  movies(where: {genre: {eq: $genre}}) {
    id
    title
  }
}

Затем вы можете создать фильм следующим образом:

let mutationResult = try await connector.createMovieMutation.execute(
  title: "Empire Strikes Back",
  releaseYear: 1980,
  genre: "Sci-Fi",
  rating: 5)

print("Movie ID: \(mutationResult.data.movie_insert.id)")

Для получения фильма используется ссылка на запрос. Все ссылки на запросы являются издателями Observable. В зависимости от настроенного издателя (см. connector.yaml) они либо поддерживают макрос @Observable (iOS 17+), либо реализуют протокол ObservableObject . По умолчанию, если ничего не указано, используется макрос @Observable поддерживаемый в iOS 17+.

В представлении SwiftUI вы можете привязать результаты запроса, используя опубликованную переменную data ссылки на запрос, и вызвать метод execute() запроса для обновления данных. Переменная data будет соответствовать структуре данных, определенной в определении вашего GQL-запроса.

Все полученные результаты соответствуют протоколу Decodable . Если вы включили первичный ключ объекта в запрос GQL, объекты также становятся Identifiable , что позволяет использовать их в итераторах.

struct ListMovieView: View {
    @StateObject private var queryRef = connector.listMoviesByGenreQuery.ref(genre: "Sci-Fi")
    var body: some View {
        VStack {
            Button {
                Task {
                    do {
                        try await refresh()
                    } catch {
                        print("Failed to refresh: \(error)")
                    }
                }
            } label: {
                Text("Refresh")
            }
                // use the query results in a view
            ForEach(queryRef.data?.movies ?? [], id: \.self.id) { movie in
                    Text(movie.title)
                }
            }
    }
    @MainActor
    func refresh() async throws {
        _ = try await queryRef.execute()
    }
}

Запросы также поддерживают однократное выполнение.

let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")

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

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

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

Схема приложения может содержать перечисления , к которым можно получить доступ с помощью запросов GraphQL .

По мере изменения дизайна приложения вы можете добавлять новые значения, поддерживаемые перечислениями. Например, представьте, что на более позднем этапе жизненного цикла вашего приложения вы решили добавить значение FULLSCREEN в перечисление AspectRatio .

В рабочем процессе SQL Connect вы можете использовать локальные инструменты разработки для обновления ваших запросов и SDK.

Однако, прежде чем вы выпустите обновленную версию своих клиентов, старые развернутые клиенты могут перестать работать.

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

Сгенерированный SDK принудительно обрабатывает неизвестные значения, поскольку сгенерированные перечисления содержат значение _UNKNOWN , а Swift обеспечивает исчерпывающий набор операторов switch.

do {
    let result = try await DataConnect.moviesConnector.listMovies.execute()
    if let data = result.data {
        for movie in data.movies {
            switch movie.aspectratio {
                case .ACADEMY: print("academy")
                case .WIDESCREEN: print("widescreen")
                case .ANAMORPHIC: print("anamorphic")
                case ._UNKNOWN(let unknownAspect): print(unknownAspect)
            }
        }
    }
} catch {
    // handle error
}

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

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

Чтобы включить кэширование на стороне клиента, добавьте конфигурацию кэширования клиента в конфигурацию коннектора:

generate:
  swiftSdk:
    outputDir: "../ios"
    package: "FirebaseDataConnectGenerated"
    clientCache:
      maxAge: 5s
      storage: persistent

Данная конфигурация имеет два параметра, оба необязательные:

• maxAge : Максимальный срок хранения кэшированного ответа до того, как клиентский SDK получит новые значения. Примеры: "0", "30 с", "1 ч 30 мин".

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

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

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

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

  Вы также можете указать отдельным вызовам функции execute() либо предоставлять только кэшированные значения ( CACHE_ONLY ), либо безусловно получать свежие значения с сервера ( SERVER_ONLY ).

  try await execute(fetchPolicy: .cacheOnly)
  

  try await execute(fetchPolicy: .serverOnly)
  

  Создайте прототип и протестируйте свое iOS-приложение.

  Вы можете использовать локальный эмулятор для тестирования и создания прототипов вашего приложения.

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

  Вы можете использовать эмулятор SQL Connect как через расширение SQL Connect для VS Code, так и через интерфейс командной строки.

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

  let connector = DataConnect.moviesConnector
  // Connect to the emulator on "127.0.0.1:9399"
  connector.useEmulator()
  
  // (alternatively) if you're running your emulator on non-default port:
  connector.useEmulator(port: 9999)
  
  // Make calls from your app
  

  Типы данных в SDK SQL Connect

  Сервер SQL Connect представляет собой стандартные и пользовательские типы данных GraphQL. В SDK они представлены следующим образом.

  Тип SQL Connect	Быстрый
  Нить	Нить
  Интерн.	Интерн.
  Плавать	Двойной
  Логический	Логический
  UUID	UUID
  Дата	FirebaseDataConnect.LocalDate
  Отметка времени	FirebaseCore.Timestamp
  Int64	Int64
  Любой	FirebaseDataConnect.AnyValue