Sử dụng SDK web đã tạo

SDK phía máy khách Firebase Data Connect cho phép bạn gọi các truy vấn và đột biến phía máy chủ ngay từ một ứng dụng Firebase. Bạn tạo một SDK phía máy khách tuỳ chỉnh song song khi thiết kế các lược đồ, truy vấn và đột biến mà bạn triển khai cho dịch vụ Data Connect. Sau đó, bạn tích hợp các phương thức từ SDK này vào logic của ứng dụng.

Như chúng tôi đã đề cập ở nơi khác, điều quan trọng cần lưu ý là các truy vấn và đột biến không được mã ứng dụng gửi và thực thi trên máy chủ.Data Connect Thay vào đó, khi được triển khai, các thao tác Data Connect sẽ được lưu trữ trên máy chủ như Cloud Functions. Điều này có nghĩa là bạn cần triển khai các thay đổi tương ứng phía máy khách để tránh làm gián đoạn người dùng hiện tại (ví dụ: trên các phiên bản ứng dụng cũ).

Đó là lý do Data Connect cung cấp cho bạn một môi trường phát triển và công cụ cho phép bạn tạo mẫu các lược đồ, truy vấn và đột biến được triển khai trên máy chủ. Nền tảng này cũng tự động tạo SDK phía máy khách trong khi bạn tạo mẫu.

Khi bạn đã lặp lại các bản cập nhật cho dịch vụ và ứng dụng khách, cả bản cập nhật phía máy chủ và phía máy khách đều đã sẵn sàng triển khai.

Quy trình phát triển ứng dụng là gì?

Nếu đã làm theo hướng dẫn Bắt đầu, bạn sẽ được giới thiệu quy trình phát triển tổng thể cho Data Connect. Trong hướng dẫn này, bạn sẽ tìm thấy thông tin chi tiết hơn về cách tạo Web SDK từ giản đồ và cách xử lý các truy vấn và đột biến của ứng dụng.

Tóm lại, để sử dụng Web SDK được tạo trong các ứng dụng khách, bạn sẽ làm theo các bước tiên quyết sau:

1. Thêm Firebase vào ứng dụng web của bạn.

Sau đó:

1. Phát triển giản đồ ứng dụng.
2. Khởi chạy mã ứng dụng bằng JavaScript SDK hoặc các thư viện React hoặc Angular.
3. Đối với React và Angular, hãy cài đặt các gói Tanstack Query

4. Thiết lập quy trình tạo SDK:

   • Với nút Thêm SDK vào ứng dụng trong tiện ích Data Connect VS Code của chúng tôi
   • Bằng cách cập nhật connector.yaml cho JavaScript SDK hoặc React hoặc Angular.

5. Nhập thư viện và mã đã tạo bằng JavaScript SDK, hoặc React hoặc Angular.

6. Triển khai các lệnh gọi đến truy vấn và đột biến bằng JavaScript SDK, hoặc React hoặc Angular.

7. Kiểm thử bằng cách thiết lập trình mô phỏng Data Connect bằng JavaScript SDK, hoặc React hoặc Angular.

Triển khai mã ứng dụng bằng Firebase SDK JavaScript

Phần này trình bày cách bạn có thể triển khai các ứng dụng bằng SDK Firebase JavaScript.

Nếu bạn đang sử dụng React hoặc Angular, hãy xem hướng dẫn thiết lập thay thế và các đường liên kết đến tài liệu bổ sung về tạo SDK Data Connect cho các khung.

Khởi chạy ứng dụng

Trước tiên, hãy khởi chạy ứng dụng bằng trình tự Firebase tiêu chuẩn.

initializeApp({...});

Tạo SDK JavaScript

Giống như hầu hết các dự án Firebase, hoạt động trên mã ứng dụng Firebase Data Connect diễn ra trong một thư mục dự án cục bộ. Cả tiện ích Data Connect VS Code và Firebase CLI đều là những công cụ cục bộ quan trọng để tạo và quản lý mã ứng dụng.

Các lựa chọn tạo SDK được khoá cho một số mục trong tệp dataconnect.yaml được tạo khi bạn khởi chạy dự án.

Khởi chạy quá trình tạo SDK

generate:
  javascriptSdk:
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

outputDir chỉ định vị trí mà SDK đã tạo sẽ xuất ra.

package chỉ định tên gói.

packageJsonDir chỉ định vị trí cài đặt gói.

Trong trường hợp này, hãy cài đặt firebase@latest để đảm bảo rằng phần phụ thuộc ngang hàng này được đáp ứng.

Khởi chạy SDK JavaScript

Khởi chạy phiên bản Data Connect bằng thông tin bạn đã dùng để thiết lập Data Connect (tất cả đều có trong thẻ Data Connect của bảng điều khiển Firebase).

Đối tượng ConnectorConfig

SDK yêu cầu một đối tượng cấu hình trình kết nối.

Đối tượng này được tạo tự động từ serviceId và location trong dataconnect.yaml, cũng như connectorId trong connector.yaml.

Nhập thư viện

Bạn cần có 2 nhóm dữ liệu nhập để khởi chạy mã ứng dụng: dữ liệu nhập Data Connect chung và dữ liệu nhập SDK cụ thể, được tạo.

Lưu ý đối tượng ConnectorConfig có trong các lần nhập chung.

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// generated queries and mutations from SDK
import { listMovies, ListMoviesResponse, createMovie, connectorConfig } from '@myorg/myconnector';

Sử dụng các truy vấn từ SDK JavaScript

Mã được tạo sẽ đi kèm với các Query Ref được xác định trước. Bạn chỉ cần nhập và gọi thực thi trên các lớp đó.

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@movie-app/movies';

const ref = listMoviesRef();
const { data } = await executeQuery(ref);
console.log(data.movies);

Gọi phương thức truy vấn SDK

Sau đây là một ví dụ về cách sử dụng các hàm lối tắt cho thao tác này:

import { listMovies } from '@movie-app/movies';
function onBtnClick() {
// This will call the generated JS from the CLI and then make an HTTP request out
// to the server.
  listMovies().then(data => showInUI(data)); // == executeQuery(listMoviesRef);
}

Đăng ký nhận thông báo khi có thay đổi

Bạn có thể đăng ký nhận thông báo về các thay đổi (thông báo sẽ được cập nhật bất cứ khi nào bạn thực hiện một truy vấn).

const listRef = listAllMoviesRef();

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

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

Sử dụng các đột biến từ SDK JavaScript

Bạn có thể truy cập vào các đột biến theo cách tương tự như truy vấn.

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@movie-app/movies';

const { data } = await executeMutation(createMovieRef({ movie: 'Empire Strikes Back' }));

Kết nối với trình mô phỏng Data Connect

Bạn có thể kết nối với trình mô phỏng bằng cách gọi connectDataConnectEmulator rồi truyền vào thực thể Data Connect, như sau:

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@myorg/myconnector'; // Replace with your package name

const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);`

// Make calls from your app

Để chuyển sang tài nguyên phát hành công khai, hãy nhận xét các dòng để kết nối với trình mô phỏng.

Triển khai mã ứng dụng cho React và Angular

Firebase Data Connect cung cấp một SDK được tạo với các hook cho React và Angular bằng cách sử dụng các thư viện có sẵn từ các đối tác của chúng tôi tại Invertase, TanStack Query Firebase.

Thư viện này cung cấp một bộ các hook giúp bạn dễ dàng xử lý các tác vụ không đồng bộ với Firebase trong ứng dụng của mình.

Khởi chạy ứng dụng

Trước tiên, giống như mọi ứng dụng web Firebase, hãy khởi chạy ứng dụng của bạn bằng trình tự Firebase tiêu chuẩn.

initializeApp({...});

Cài đặt các gói TanStack Query Firebase

cài đặt các gói cho TanStack Query trong dự án của bạn.

npm i --save @tanstack/react-query @tanstack-query-firebase/react
npm i --save firebase@latest # Note: React has a peer dependency on ^11.3.0

ng add @angular/fire

Tạo SDK React hoặc Angular

Tương tự như SDK web tiêu chuẩn, như mô tả trước đó, công cụ Firebase xử lý việc tự động tạo SDK dựa trên giản đồ và các thao tác của bạn.

Để tạo một React SDK cho dự án, hãy thêm khoá react vào tệp cấu hình connector.yaml.

generate:
  javascriptSdk:
    react: true
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

generate:
  javascriptSdk:
    angular: true
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

Nhập thư viện

Bạn cần có 4 nhóm dữ liệu nhập để khởi động mã ứng dụng React hoặc Angular: dữ liệu nhập Data Connect chung, dữ liệu nhập TanStack chung và dữ liệu nhập cụ thể cho JS và SDK được tạo bằng React.

Lưu ý loại ConnectorConfig có trong các lượt nhập chung.

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@myorg/myconnector';

// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@myorg/connector/react";

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@myorg/myconnector';

// generated React hooks from SDK
import { injectListAllMovies, injectCreateMovie } from "@myorg/connector/angular";

Sử dụng các truy vấn và đột biến trong ứng dụng React hoặc Angular

Sau khi hoàn tất quá trình thiết lập, bạn có thể kết hợp các phương thức từ SDK đã tạo.

Trong đoạn mã sau, hãy lưu ý phương thức có tiền tố use useListAllMovies cho React và phương thức có tiền tố inject injectListAllMovies cho Angular, cả hai đều từ SDK đã tạo.

import { useListAllMovies } from '@movies-app/movies/react';

function MyComponent() {
  const { isLoading, data, error } = useListAllMovies();
  if(isLoading) {
    return <div>Loading...</div>
  }
  if(error) {
    return <div> An Error Occurred: {error} </div>
  }
}

// App.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import MyComponent from './my-component';

function App() {
  const queryClient = new QueryClient();
  return <QueryClientProvider client={queryClient}>
    <MyComponent />
  </QueryClientProvider>
}

import { injectAllMovies, connectorConfig } from '@movies-app/movies/angular';
import { provideDataConnect, getDataConnect } from '@angular/fire/data-connect';
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";
const queryClient = new QueryClient();
...
providers: [
  ...
  provideTanStackQuery(queryClient),
  provideDataConnect(() => {
    const dc = getDataConnect(connectorConfig);
    return dc;
  })
]

Sử dụng các truy vấn tải lại tự động bằng React và Angular

Bạn có thể định cấu hình các truy vấn để tự động tải lại khi dữ liệu thay đổi.

export class MovieListComponent {
  movies = useListAllMovies();
}

export class AddPostComponent {
  const mutation = useCreateMovie({ invalidate: [listAllMoviesRef()] });
  addMovie() {
    // The following will automatically cause Tanstack to reload its listAllMovies query
    mutation.mutate({ title: 'The Matrix });
  }
}

// class
export class MovieListComponent {
  movies = injectListAllMovies();
}

// template
@if (movies.isPending()) {
    Loading...
}
@if (movies.error()) {
    An error has occurred: {{  movies.error() }}
}
@if (movies.data(); as data) {
    @for (movie of data.movies; track movie.id) {
    <mat-card appearance="outlined">
        <mat-card-content>{{movie.description}}</mat-card-content>
    </mat-card>
    } @empty {
        <h2>No items!</h2>
    }
}

Kết nối với trình mô phỏng Data Connect

Bạn có thể kết nối với trình mô phỏng bằng cách gọi connectDataConnectEmulator rồi truyền phiên bản Data Connect vào hook đã tạo, như sau:

import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@movies-app/movies';
import { useListAllMovies } from '@movies-app/movies/react';

const dc = getDataConnect(connectorConfig);
connectDataConnectEmulator(dc, 'localhost', 9399);

class AppComponent() {
  ...
  const { isLoading, data, error } = useListAllMovies(dc);
  ...
}

// app.config.ts
import { provideDataConnect } from '@angular/fire/data-connect';
import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
provideDataConnect(() => {
  const dc = getDataConnect(connectorConfig);
  connectDataConnectEmulator(dc, 'localhost', 9399);
  return dc;
}),

Để chuyển sang tài nguyên phát hành công khai, hãy nhận xét các dòng để kết nối với trình mô phỏng.

Các loại dữ liệu trong SDK

Máy chủ Data Connect đại diện cho các kiểu dữ liệu GraphQL phổ biến. Các loại này được biểu thị trong SDK như sau.

Các điểm cần cân nhắc đặc biệt khi tạo SDK

Định cấu hình các đường dẫn tương đối với node_modules

Đối với JavaScript SDK, vì Data Connect dùng npm link để cài đặt SDK, nên SDK đã tạo cần được xuất ra một thư mục ở cùng cấp với đường dẫn node_modules hoặc trong một thư mục con có thể truy cập vào node_modules.

Nói cách khác, SDK mà bạn tạo cần có quyền truy cập vào mô-đun nút firebase để hoạt động chính xác.

Ví dụ: nếu bạn có node_modules trong my-app/, thì thư mục đầu ra của bạn phải là my-app/js-email-generated để js-email-generated có thể nhập từ thư mục mẹ node_modules.

my-app/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  js-email-generated/

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../js-email-generated"
    package: "@myapp/my-connector"

Hoặc nếu có một kho lưu trữ đơn nơi các mô-đun của bạn được lưu trữ ở thư mục gốc, bạn có thể đặt thư mục đầu ra ở bất kỳ thư mục nào trong kho lưu trữ đơn.

my-monorepo/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  my-app/
    js-email-generated/
  package.json

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../my-app/js-email-generated" # You can also output to ../../js-email-generated

Cập nhật SDK trong quá trình tạo mẫu

Nếu bạn đang tạo mẫu một cách tương tác bằng tiện ích Data Connect VS Code và trình mô phỏng Data Connect của tiện ích này, thì các tệp nguồn SDK sẽ tự động được tạo và cập nhật trong khi bạn sửa đổi các tệp .gql xác định lược đồ, truy vấn và đột biến. Đây có thể là một tính năng hữu ích trong quy trình làm việc tải lại (nóng).

Ngoài ra, bạn có thể dùng CLI để tạo lại SDK bất cứ khi nào tệp .gql thay đổi:

firebase dataconnect:sdk:generate --watch

Tạo SDK để tích hợp và phát hành chính thức

Trong một số trường hợp, chẳng hạn như chuẩn bị các nguồn dự án để gửi cho các kiểm thử CI, bạn có thể gọi CLI Firebase để cập nhật hàng loạt.

Trong những trường hợp này, hãy sử dụng firebase dataconnect:sdk:generate.