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

SDK ứng dụng Firebase Data Connect cho phép bạn gọi các truy vấn và sự thay đổi phía máy chủ trực tiếp từ ứng dụng Firebase. Bạn tạo một SDK ứng dụng tuỳ chỉnh song song khi thiết kế giản đồ, truy vấn và sự thay đổi 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 ứng dụng.

Như đã đề 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 Data Connect không được mã ứng dụng gửi và thực thi trên máy chủ. 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ư Chức năng trên đám mây. Đ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 và công cụ dành cho nhà phát triển, cho phép bạn tạo nguyên mẫu cho các giản đồ, truy vấn và đột biến được triển khai trên máy chủ. Công cụ này cũng tự động tạo SDK phía máy khách trong khi bạn tạo nguyên 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 ứng dụng khách đều sẵn sàng để triển khai.

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

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

Nếu bạn đang sử dụng React, 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ề cách tạo SDK React cho Data Connect.

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, công việc trên mã ứng dụng Firebase Data Connect diễn ra trong thư mục dự án cục bộ. Cả tiện ích Data Connect VS Code và CLI Firebase đều là các công cụ cục bộ quan trọng để tạo và quản lý mã ứng dụng.

Các tuỳ chọn tạo SDK được liên kết với 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

Trong connector.yaml, hãy thêm outputDir, package và (đối với SDK web) packageJsonDir. 
generate:
  javascriptSdk:
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

outputDir chỉ định vị trí xuất SDK đã tạo.

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 phần phụ thuộc ngang hàng này được thực hiện.

Khởi chạy SDK JavaScript

Khởi chạy thực thể Data Connect bằng thông tin bạn đã sử dụng để thiết lập tính năng Kết nối dữ liệu (tất cả đều có trong thẻ Kết nối dữ liệu của bảng điều khiển Firebase).

Đối tượng ConnectorConfig

SDK yêu cầu đố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 và connectorId trong connector.yaml.

Nhập thư viện

Có hai nhóm lệnh nhập cần thiết để khởi chạy mã ứng dụng: lệnh nhập Data Connect chung và lệnh nhập SDK được tạo, cụ thể.

Lưu ý đối tượng ConnectorConfig có trong các lệnh 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 Tham chiếu truy vấn được xác định trước. Bạn chỉ cần nhập và gọi lệnh 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

Dưới đây là ví dụ về cách sử dụng các hàm lối tắt 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 về các thay đổi

Bạn có thể đăng ký nhận thông báo về các thay đổi (sẽ cập nhật bất cứ khi nào bạn thực thi 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 giống 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, sau đó 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 chính thức, hãy chú thích các dòng để kết nối với trình mô phỏng.

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

Firebase Data Connect cung cấp một SDK được tạo có các trình nối cho React bằng cách sử dụng 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ộ lệnh gọi giúp bạn dễ dàng xử lý các tác vụ không đồng bộ bằng Firebase trong ứng dụng.

Khởi chạy ứng dụng

Trước tiên, như với 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 chuẩn.

initializeApp({...});

Cài đặt gói Firebase truy vấn TanStack

cài đặt các gói cho Truy vấn TanStack trong dự á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

Tạo SDK React

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

Để tạo SDK React 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: "../../"

Nhập thư viện

Có 4 nhóm lệnh nhập cần thiết để khởi chạy mã ứng dụng React: lệnh nhập Data Connect chung, lệnh nhập TanStack chung và lệnh nhập cụ thể cho các SDK do JS và React tạo.

Lưu ý loại ConnectorConfig có trong các lệnh 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";

Sử dụng truy vấn và đột biến trong ứng dụng React

Sau khi thiết lập xong, bạn có thể kết hợp các phương thức từ SDK React đã tạo.

Trong đoạn mã sau, hãy lưu ý phương thức có tiền tố use useListAllMovies từ SDK React đã tạo. Tất cả các thao tác use như vậy trong SDK được tạo, cả truy vấn và đột biến, đều gọi các liên kết Truy vấn TanStack:

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>
}

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, sau đó truyền thực thể Data Connect vào trình nối đã 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);

function App() {
  ...
  const { isLoading, data, error } = useListAllMovies(dc);
  ...
}

Để chuyển sang tài nguyên sản xuất, hãy chú thích 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 loại dữ liệu GraphQL phổ biến. Các giá trị này được trình bày trong SDK như sau.

Loại kết nối dữ liệu TypeScript
Dấu thời gian chuỗi
Ngày chuỗi
mã nhận dạng duy nhất (UUID) chuỗi
Int64 chuỗi
Giường đôi Số điện thoại
Nổi Số điện thoại

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

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

Đối với SDK JavaScript, vì Data Connect sử 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 đã tạo của bạn 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 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 monorepo lưu trữ các mô-đun ở thư mục gốc, bạn có thể đặt thư mục đầu ra vào bất kỳ thư mục nào trong monorepo.

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 khi tạo bản nguyên mẫu

Nếu bạn đang tạo bản minh hoạ tương tác bằng tiện ích Data Connect VS Code và trình mô phỏng Data Connect, 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 giản đồ, truy vấn và đột biến. Đây có thể là một tính năng hữu ích trong quy trình tải lại (nóng).

Trong các trường hợp khác, nếu đang sử dụng trình mô phỏng Data Connect từ CLI Firebase, bạn có thể đặt chế độ theo dõi các bản cập nhật .gql và cũng tự động cập nhật các nguồn SDK.

Ngoài ra, bạn có thể sử 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ị 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.

Các yếu tố khác cần cân nhắc về khung

Angular

Khi tạo mã, Angular CLI sẽ không nhận thấy các thay đổi mới do mã tối ưu hoá phần phụ thuộc. Để khắc phục vấn đề này, bạn cần sửa đổi angular.json.

  "projects": {
    "myproject": {
      "architect": {
        "serve:": {
          "prebundle": {
            "exclude": ["@movie-app/movies"]
          }
        }
      }
    }
  }