Firebase Data Connect client SDKs let you call your server-side queries and mutations directly from a Firebase app. You generate a custom client SDK in parallel as you design the schemas, queries and mutations you deploy to your Data Connect service. Then, you integrate methods from this SDK into your client logic.
Как мы уже упоминали ранее, важно отметить, что запросы и мутации Data Connect не отправляются клиентским кодом и не выполняются на сервере. Вместо этого, при развертывании операции Data Connect хранятся на сервере, как и в Cloud Functions. Это означает, что вам необходимо развернуть соответствующие изменения на стороне клиента, чтобы избежать проблем с существующими пользователями (например, в старых версиях приложения).
Именно поэтому Data Connect предоставляет вам среду разработки и инструменты, позволяющие создавать прототипы развернутых на сервере схем, запросов и мутаций. Кроме того, он автоматически генерирует SDK для клиентской части во время создания прототипов.
После внесения изменений в ваши сервисные и клиентские приложения, обновления как на стороне сервера, так и на стороне клиента готовы к развертыванию.
Каков рабочий процесс разработки клиентской части?
Если вы следовали инструкциям в разделе «Начало работы» , вы познакомились с общим процессом разработки Data Connect . В этом руководстве вы найдете более подробную информацию о генерации Swift SDK из вашей схемы, а также о работе с клиентскими запросами и мутациями.
Вкратце, для использования сгенерированных Swift SDK в клиентских приложениях вам необходимо выполнить следующие предварительные шаги:
- Добавьте Firebase в свое iOS- приложение.
Чтобы использовать сгенерированный SDK, настройте его как зависимость в Xcode.
В верхней панели навигации Xcode выберите File > Add Package Dependencies > Add Local и выберите папку, содержащую сгенерированный
Package.swift.
Затем:
- Разработайте схему вашего приложения.
Настройка генерации SDK:
- С помощью кнопки «Добавить SDK в приложение» в нашем расширении Data Connect для VS Code.
- Обновите файл
connector.yaml
Настройте и используйте эмулятор Data Connect и выполните итерации.
Сгенерируйте свой Swift SDK
Используйте Firebase CLI для настройки сгенерированных Data Connect SDK в ваших приложениях. Команда init должна обнаружить все приложения в текущей папке и автоматически установить сгенерированные SDK.
firebase init dataconnect:sdk
Обновляйте SDK во время прототипирования.
Если у вас установлено расширение Data Connect для VS Code, оно всегда будет поддерживать сгенерированные SDK в актуальном состоянии.
Если вы не используете расширение Data Connect для VS Code, вы можете использовать Firebase CLI для обновления сгенерированных SDK.
firebase dataconnect:sdk:generate --watchГенерация SDK в конвейерах сборки
С помощью Firebase CLI можно генерировать SDK Data Connect в процессах сборки CI/CD.
firebase dataconnect:sdk:generateИнициализируйте SDK Data Connect для iOS.
Инициализируйте свой экземпляр Data Connect , используя информацию, которую вы использовали для настройки Data Connect (вся информация доступна на вкладке Data Connect в консоли Firebase ).
Получение экземпляра коннектора
Код для вашего коннектора будет сгенерирован эмулятором Data 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")
Обработка изменений в полях перечисления
Схема приложения может содержать перечисления , к которым можно получить доступ с помощью запросов GraphQL .
По мере изменения дизайна приложения вы можете добавлять новые значения, поддерживаемые перечислениями. Например, представьте, что на более позднем этапе жизненного цикла вашего приложения вы решили добавить значение FULLSCREEN в перечисление AspectRatio .
В рабочем процессе Data 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
}
Включите кэширование на стороне клиента.
Data 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-приложение.
Для обеспечения возможности использования локального эмулятора клиенты должны быть оснащены соответствующими инструментами.
Вы можете использовать эмулятор Data Connect как через расширение Data 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 Data Connect
Сервер Data Connect представляет собой стандартные и пользовательские типы данных GraphQL. В SDK они представлены следующим образом.
Тип Data Connect Быстрый Нить Нить Интерн. Интерн. Плавать Двойной Логический Логический UUID UUID Дата FirebaseDataConnect.LocalDate Отметка времени FirebaseCore.Timestamp Int64 Int64 Любой FirebaseDataConnect.AnyValue