Các ứng dụng hiện đang sử dụng bất kỳ API Web Firebase nào có không gian tên, trong thư viện compat
từ phiên bản 8 trở về trước, bạn nên cân nhắc
di chuyển sang API mô-đun theo hướng dẫn này.
Hướng dẫn này giả định bạn đã quen thuộc với API không gian tên và bạn sẽ tận dụng được một gói mô-đun như webpack hoặc Tổng hợp để nâng cấp và liên tục phát triển ứng dụng theo mô-đun.
Bạn nên sử dụng trình gói mô-đun trong môi trường phát triển được đề xuất. Nếu không sử dụng, bạn sẽ không thể tận dụng những lợi ích chính của API mô-đun trong việc giảm kích thước ứng dụng. Bạn sẽ cần npm hoặc sợi để cài đặt SDK.
Các bước nâng cấp trong hướng dẫn này sẽ dựa trên một ứng dụng web tưởng tượng sử dụng SDK Authentication và Cloud Firestore. Bằng cách xem qua các ví dụ, bạn có thể nắm vững các khái niệm và các bước thực tế cần thiết để nâng cấp tất cả các tính năng được hỗ trợ Firebase Web SDK.
Giới thiệu về các thư viện (compat) có không gian tên
Hiện có hai loại thư viện cho Firebase Web SDK:
- Mô-đun – một giao diện API mới được thiết kế để hỗ trợ việc rung cây (xoá mã không dùng đến) để giúp ứng dụng web của bạn nhỏ và nhanh nhất có thể.
- Không gian tên (
compat) – một giao diện API quen thuộc, có đầy đủ tương thích với các phiên bản SDK cũ hơn, cho phép bạn nâng cấp mà không phải thay đổi tất cả mã Firebase của bạn cùng một lúc. Thư viện tương thích có ít không có kích thước hoặc hiệu suất có nhiều lợi thế hơn so với các đối tác có không gian tên.
Hướng dẫn này giả định rằng bạn sẽ tận dụng được khả năng tương thích để hỗ trợ nâng cấp. Các thư viện này cho phép bạn tiếp tục bằng cách sử dụng mã không gian tên cùng với mã được tái cấu trúc cho API mô-đun. Điều này có nghĩa là bạn có thể biên dịch và gỡ lỗi ứng dụng dễ dàng hơn khi bạn tiến hành nâng cấp của chúng tôi.
Đối với các ứng dụng có mức độ tiếp xúc rất nhỏ với SDK Web Firebase, ví dụ: một ứng dụng chỉ thực hiện một lệnh gọi đơn giản đến các API Authentication—ứng dụng này có thể thiết thực để tái cấu trúc mã không gian tên cũ hơn mà không cần sử dụng các thư viện khả năng tương thích. Nếu đang nâng cấp một ứng dụng như vậy, bạn có thể làm theo chỉ dẫn trong hướng dẫn này cho "API mô-đun" mà không cần sử dụng thư viện khả năng tương thích.
Giới thiệu về quá trình nâng cấp
Mỗi bước của quá trình nâng cấp đều được xác định phạm vi để bạn có thể hoàn tất việc chỉnh sửa nguồn cho ứng dụng của bạn, sau đó biên dịch và chạy ứng dụng mà không gặp sự cố. Tóm lại, dưới đây là những gì bạn sẽ làm để nâng cấp ứng dụng:
- Thêm thư viện mô-đun và thư viện khả năng tương thích vào ứng dụng.
- Cập nhật các câu lệnh nhập trong mã của bạn để tương thích.
- Tái cấu trúc mã cho một sản phẩm (ví dụ: Authentication) thành kiểu mô-đun.
- Không bắt buộc: tại thời điểm này, hãy xoá thư viện khả năng tương thích Authentication và mã tương thích cho Authentication để nhận ra lợi ích của kích thước ứng dụng đối với Authentication trước khi tiếp tục.
- Tái cấu trúc hàm cho từng sản phẩm (ví dụ: Cloud Firestore, FCM, v.v.) thành kiểu mô-đun, biên dịch và thử nghiệm cho đến khi hoàn tất mọi khía cạnh.
- Cập nhật mã khởi chạy thành kiểu mô-đun.
- Xoá tất cả các câu lệnh tương thích và mã tương thích còn lại khỏi ứng dụng của bạn.
Tải SDK phiên bản mới nhất
Để bắt đầu, hãy tải thư viện mô-đun và thư viện khả năng tương thích bằng npm:
npm i firebase@10.13.1 # OR yarn add firebase@10.13.1
Cập nhật dữ liệu nhập để tương thích
Để mã của bạn tiếp tục hoạt động sau khi cập nhật các phần phụ thuộc, thay đổi câu lệnh nhập của bạn để sử dụng tính năng "tương thích" phiên bản của mỗi lần nhập. Ví dụ:
Trước: phiên bản 8 trở xuống
import firebase from 'firebase/app';
import 'firebase/auth';
import 'firebase/firestore';
Sau: khả năng tương thích
// compat packages are API compatible with namespaced code
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
import 'firebase/compat/firestore';
Tái cấu trúc theo kiểu mô-đun
Mặc dù các API có không gian tên đều dựa trên một không gian tên và dịch vụ theo chuỗi dấu chấm
thì cách tiếp cận mô-đun có nghĩa là mã của bạn sẽ được sắp xếp
chủ yếu xoay quanh các hàm. Trong API mô-đun, gói firebase/app và
các gói khác không trả về tệp xuất toàn diện chứa tất cả
phương thức từ gói. Thay vào đó, các gói này sẽ xuất các hàm riêng lẻ.
Trong API mô-đun, các dịch vụ được truyền dưới dạng đối số đầu tiên, sau đó hàm này sử dụng thông tin chi tiết của dịch vụ để thực hiện phần còn lại. Hãy xem xét cách hoạt động của tính năng này trong 2 ví dụ về việc tái cấu trúc lệnh gọi đến API Authentication và Cloud Firestore.
Ví dụ 1: tái cấu trúc hàm Authentication
Trước: khả năng tương thích
Mã khả năng tương thích giống hệt với mã không gian tên, nhưng quy tắc nhập đã thay đổi.
import firebase from "firebase/compat/app";
import "firebase/compat/auth";
const auth = firebase.auth();
auth.onAuthStateChanged(user => {
// Check for user status
});
Sau: Mô-đun
Hàm getAuth lấy firebaseApp làm tham số đầu tiên.
onAuthStateChanged
hàm không được xâu chuỗi từ thực thể auth như thường lệ
trong API không gian tên; đây là một phiên bản miễn phí
hàm này lấy auth làm tham số đầu tiên.
import { getAuth, onAuthStateChanged } from "firebase/auth";
const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
// Check for user status
});
Cập nhật hoạt động xử lý của phương thức xác thực getRedirectResult
API mô-đun gây ra một thay đổi có thể gây lỗi trong getRedirectResult. Khi không có hoạt động chuyển hướng nào được gọi, API mô-đun sẽ trả về null trái ngược với API không gian tên (đã trả về một UserCredential với một người dùng null).
Trước: khả năng tương thích
const result = await auth.getRedirectResult()
if (result.user === null && result.credential === null) {
return null;
}
return result;
Sau: Mô-đun
const result = await getRedirectResult(auth);
// Provider of the access token could be Facebook, Github, etc.
if (result === null || provider.credentialFromResult(result) === null) {
return null;
}
return result;
Ví dụ 2: tái cấu trúc hàm Cloud Firestore
Trước: khả năng tương thích
import "firebase/compat/firestore"
const db = firebase.firestore();
db.collection("cities").where("capital", "==", true)
.get()
.then((querySnapshot) => {
querySnapshot.forEach((doc) => {
// doc.data() is never undefined for query doc snapshots
console.log(doc.id, " => ", doc.data());
});
})
.catch((error) => {
console.log("Error getting documents: ", error);
});
Sau: Mô-đun
Hàm getFirestore lấy firebaseApp làm tham số đầu tiên, tham số này
được trả về từ initializeApp trong ví dụ trước. Lưu ý cách
mã để tạo truy vấn rất khác trong API mô-đun; không tạo ra chuỗi
các phương thức như query hoặc where hiện được biểu thị dưới dạng hàm miễn phí.
import { getFirestore, collection, query, where, getDocs } from "firebase/firestore";
const db = getFirestore(firebaseApp);
const q = query(collection(db, "cities"), where("capital", "==", true));
const querySnapshot = await getDocs(q);
querySnapshot.forEach((doc) => {
// doc.data() is never undefined for query doc snapshots
console.log(doc.id, " => ", doc.data());
});
Cập nhật các tham chiếu đến DocumentSnapshot.exists của Firestore
API mô-đun đưa ra một thay đổi có thể gây lỗi trong đó thuộc tính
firestore.DocumentSnapshot.exists đã được thay đổi thành một phương thức. Chiến lược phát hành đĩa đơn
chức năng về cơ bản là giống nhau (kiểm tra xem tài liệu có tồn tại hay không)
nhưng bạn phải tái cấu trúc mã của mình để sử dụng phương thức mới hơn như sau:
Trước:khả năng tương thích
if (snapshot.exists) {
console.log("the document exists");
}
Sau: Mô-đun
if (snapshot.exists()) {
console.log("the document exists");
}
Ví dụ 3: kết hợp kiểu mã không gian tên và kiểu mã mô-đun
Việc sử dụng thư viện khả năng tương thích trong quá trình nâng cấp cho phép bạn tiếp tục sử dụng không gian tên cùng với mã được tái cấu trúc cho API mô-đun. Điều này có nghĩa là bạn có thể mã không gian tên hiện có cho Cloud Firestore trong khi bạn tái cấu trúc Authentication hoặc mã Firebase SDK khác để kiểu mô-đun mà vẫn biên dịch thành công ứng dụng của bạn bằng cả hai mã kiểu. Điều này cũng đúng đối với mã API mô-đun và không gian tên bên trong một sản phẩm như dưới dạng Cloud Firestore; kiểu mã mới và cũ có thể cùng tồn tại, miễn là bạn nhập các gói tương thích:
import firebase from 'firebase/compat/app';
import 'firebase/compat/firestore';
import { getDoc } from 'firebase/firestore'
const docRef = firebase.firestore().doc();
getDoc(docRef);
Xin lưu ý rằng mặc dù ứng dụng sẽ được biên dịch, nhưng bạn sẽ không nhận được kích thước ứng dụng của mã mô-đun cho đến khi bạn xoá hoàn toàn các câu lệnh tương thích và mã khỏi ứng dụng của bạn.
Cập nhật mã khởi chạy
Cập nhật mã khởi tạo của ứng dụng để sử dụng cú pháp mô-đun. Đó là
bạn phải cập nhật mã này sau khi bạn đã hoàn tất việc tái cấu trúc tất cả
mã trong ứng dụng của bạn; là vì firebase.initializeApp() khởi chạy toàn cục
trạng thái cho cả API tương thích và API mô-đun, trong khi API mô-đun
Hàm initializeApp() chỉ khởi tạo trạng thái cho mô-đun.
Trước: khả năng tương thích
import firebase from "firebase/compat/app"
firebase.initializeApp({ /* config */ });
Sau: Mô-đun
import { initializeApp } from "firebase/app"
const firebaseApp = initializeApp({ /* config */ });
Xoá mã tương thích
Để nhận thấy lợi ích về kích thước của API mô-đun, rốt cuộc bạn nên
chuyển đổi tất cả lệnh gọi sang kiểu mô-đun như trên và xoá tất cả
Các câu lệnh import "firebase/compat/* trong mã của bạn. Khi bạn hoàn tất, sẽ có
không được tham chiếu đến không gian tên chung firebase.* hay bất kỳ không gian tên nào khác
trong kiểu API không gian tên.
Sử dụng thư viện khả năng tương thích từ cửa sổ
API mô-đun được tối ưu hoá để hoạt động với các mô-đun thay vì
Đối tượng window. Các phiên bản trước đó của thư viện cho phép tải và
quản lý Firebase bằng cách sử dụng không gian tên window.firebase. Đây không phải là
bạn nên áp dụng từ nay về sau vì chế độ này không cho phép loại bỏ đoạn mã không sử dụng.
Tuy nhiên, phiên bản khả năng tương thích của SDK JavaScript vẫn hoạt động với window
dành cho những nhà phát triển không muốn bắt đầu lộ trình nâng cấp mô-đun ngay lập tức.
<script src="https://www.gstatic.com/firebasejs/10.13.1/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/10.13.1/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/10.13.1/firebase-auth-compat.js"></script>
<script>
const firebaseApp = firebase.initializeApp({ /* Firebase config */ });
const db = firebaseApp.firestore();
const auth = firebaseApp.auth();
</script>
Thư viện tương thích sử dụng mã mô-đun nâng cao và cung cấp API tương tự như API không gian tên; điều này có nghĩa là bạn có thể tham chiếu đến tài liệu tham khảo API không có tên và các đoạn mã không gian tên để biết chi tiết. Phương pháp này không được đề xuất để sử dụng lâu dài, nhưng là khi bắt đầu nâng cấp lên mô-đun hoàn chỉnh thư viện của bạn.
Lợi ích và hạn chế của SDK mô-đun
So với các phiên bản trước đó, SDK được mô-đun hoá hoàn toàn có những ưu điểm sau:
- SDK mô-đun cho phép giảm đáng kể kích thước ứng dụng. Chiến dịch này sử dụng JavaScript hiện đại Định dạng mô-đun, cho phép "rung cây" mà bạn nhập chỉ những cấu phần phần mềm mà ứng dụng của bạn cần. Tuỳ thuộc vào ứng dụng, hiệu ứng rung cây bằng SDK mô-đun có thể giảm 80% số kilobyte so với ứng dụng tương đương được tạo bằng API không gian tên.
- SDK mô-đun sẽ tiếp tục hưởng lợi từ quá trình phát triển tính năng liên tục, còn API không gian tên thì không.