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

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

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

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

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

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

Если вы следовали Get started , вы познакомились с общим процессом разработки для Data Connect . В этом руководстве вы найдете более подробную информацию о создании Swift SDK из вашей схемы и работе с клиентскими запросами и мутациями.

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

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

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

    В верхней навигационной панели Xcode выберите Файл > Добавить зависимости пакета > Добавить локальный и выберите папку, содержащую сгенерированный Package.swift .

Затем:

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

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

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

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

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

Создайте свой Swift SDK

Как и в большинстве проектов Firebase, работа над клиентским кодом Firebase Data Connect происходит в локальном каталоге проекта. Как расширение Data Connect VS Code, так и Firebase CLI являются важными локальными инструментами для генерации и управления клиентским кодом.

Параметры генерации SDK привязаны к нескольким записям в файле dataconnect.yaml , созданном при инициализации проекта.

Инициализировать генерацию SDK

В файле connector.yaml добавьте outputDir , package и (для веб-SDK) packageJsonDir . 
connectorId: "movies"
generate:
  swiftSdk:
    outputDir: "../movies-generated"
    package: "Movies"

outputDir указывает, куда должен выводиться сгенерированный SDK. Если не указано, папка коннектора используется как выходной каталог по умолчанию.

package указывает имя пакета, который будет сгенерирован. Генератор создаст папку с именем пакета, содержащую Package.swift и сгенерированный код.

observablePublisher (необязательно) указывает Observable publisher для использования в ссылках запроса. Возможные значения: observableMacro (iOS 17+) и observableObject (до iOS 17). Значение по умолчанию, если не указано ни одного, — observableMacro .

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

Если вы создаете прототип интерактивно с помощью расширения Data Connect VS Code и его эмулятора Data Connect , исходные файлы SDK автоматически генерируются и обновляются, пока вы изменяете файлы .gql определяющие схемы, запросы и мутации. Это может быть полезной функцией в рабочих процессах горячей (пере)загрузки.

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

Кроме того, вы можете использовать CLI для повторной генерации SDK при каждом изменении файлов .gql:

firebase dataconnect:sdk:generate --watch

Создание SDK для интеграции и производственных выпусков

В некоторых сценариях, например при подготовке исходных кодов проекта к отправке на CI-тесты, можно вызвать Firebase CLI для пакетного обновления.

В этих случаях используйте firebase dataconnect:sdk:generate .

Инициализируйте Data Connect iOS SDK

Инициализируйте свой экземпляр 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 вы можете связать результаты запроса, используя переменную published data запроса ref и вызвать метод 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")

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

Инструмент клиентов для использования локального эмулятора

Вы можете использовать эмулятор Data Connect как из расширения Data Connect VS Code, так и из CLI.

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

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 следующим образом.

Тип подключения данных Быстрый
Нить Нить
Инт Инт
Плавать Двойной
Булев Бул
UUID UUID
Дата FirebaseDataConnect.LocalDate
Временная метка FirebaseCore.Временная метка
Int64 Int64
Любой FirebaseDataConnect.ЛюбоеЗначение
,

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

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

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

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

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

Если вы следовали Get started , вы познакомились с общим процессом разработки для Data Connect . В этом руководстве вы найдете более подробную информацию о создании Swift SDK из вашей схемы и работе с клиентскими запросами и мутациями.

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

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

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

    В верхней навигационной панели Xcode выберите Файл > Добавить зависимости пакета > Добавить локальный и выберите папку, содержащую сгенерированный Package.swift .

Затем:

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

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

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

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

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

Создайте свой Swift SDK

Как и в большинстве проектов Firebase, работа над клиентским кодом Firebase Data Connect происходит в локальном каталоге проекта. Как расширение Data Connect VS Code, так и Firebase CLI являются важными локальными инструментами для генерации и управления клиентским кодом.

Параметры генерации SDK привязаны к нескольким записям в файле dataconnect.yaml , созданном при инициализации проекта.

Инициализировать генерацию SDK

В файле connector.yaml добавьте outputDir , package и (для веб-SDK) packageJsonDir . 
connectorId: "movies"
generate:
  swiftSdk:
    outputDir: "../movies-generated"
    package: "Movies"

outputDir указывает, куда должен выводиться сгенерированный SDK. Если не указано, папка коннектора используется как выходной каталог по умолчанию.

package указывает имя пакета, который будет сгенерирован. Генератор создаст папку с именем пакета, содержащую Package.swift и сгенерированный код.

observablePublisher (необязательно) указывает Observable publisher для использования в ссылках запроса. Возможные значения: observableMacro (iOS 17+) и observableObject (до iOS 17). Значение по умолчанию, если не указано ни одного, — observableMacro .

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

Если вы создаете прототип интерактивно с помощью расширения Data Connect VS Code и его эмулятора Data Connect , исходные файлы SDK автоматически генерируются и обновляются, пока вы изменяете файлы .gql определяющие схемы, запросы и мутации. Это может быть полезной функцией в рабочих процессах горячей (пере)загрузки.

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

Кроме того, вы можете использовать CLI для повторной генерации SDK при каждом изменении файлов .gql:

firebase dataconnect:sdk:generate --watch

Создание SDK для интеграции и производственных выпусков

В некоторых сценариях, например при подготовке исходных кодов проекта к отправке на CI-тесты, можно вызвать Firebase CLI для пакетного обновления.

В этих случаях используйте firebase dataconnect:sdk:generate .

Инициализируйте Data Connect iOS SDK

Инициализируйте свой экземпляр 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 вы можете связать результаты запроса, используя переменную published data запроса ref и вызвать метод 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")

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

Инструмент клиентов для использования локального эмулятора

Вы можете использовать эмулятор Data Connect как из расширения Data Connect VS Code, так и из CLI.

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

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 следующим образом.

Тип подключения данных Быстрый
Нить Нить
Инт Инт
Плавать Двойной
Булев Бул
UUID UUID
Дата FirebaseDataConnect.LocalDate
Временная метка FirebaseCore.Временная метка
Int64 Int64
Любой FirebaseDataConnect.ЛюбоеЗначение