(可選)使用 Firebase Emulator Suite 進行原型設計和測試
在討論您的應用程式如何讀取和寫入即時資料庫之前,我們先介紹一組可用於原型設計和測試即時資料庫功能的工具:Firebase Emulator Suite。如果您正在嘗試不同的資料模型、優化安全規則或努力尋找與後端互動的最具成本效益的方式,那麼能夠在本地工作而不部署即時服務可能是一個好主意。
即時資料庫模擬器是模擬器套件的一部分,它使您的應用程式能夠與模擬資料庫內容和配置以及可選的模擬專案資源(函數、其他資料庫和安全規則)進行互動。emulator_suite_short
使用即時資料庫模擬器只需幾個步驟:
- 將一行程式碼新增至應用程式的測試配置以連接到模擬器。
- 從本地專案目錄的根目錄中,運行
firebase emulators:start
。 - 像往常一樣使用即時資料庫平台 SDK 或使用即時資料庫 REST API 從應用程式的原型程式碼進行呼叫。
提供了涉及即時資料庫和雲端功能的詳細演練。您還應該看看模擬器套件的介紹。
取得資料庫參考
若要從資料庫讀取或寫入數據,您需要一個DatabaseReference
實例:
DatabaseReference ref = FirebaseDatabase.instance.ref();
寫入數據
本文檔涵蓋了讀取和寫入 Firebase 資料的基礎知識。
Firebase 資料寫入DatabaseReference
並透過等待或偵聽該引用發出的事件來擷取。事件在資料的初始狀態下發出一次,並在資料發生變化時再次發出。
基本寫入操作
對於基本寫入操作,您可以使用set()
將資料儲存到指定的引用,替換該路徑上的任何現有資料。您可以設定以下類型的參考: String
、 boolean
、 int
、 double
、 Map
、 List
。
例如,您可以使用set()
新增用戶,如下所示:
DatabaseReference ref = FirebaseDatabase.instance.ref("users/123");
await ref.set({
"name": "John",
"age": 18,
"address": {
"line1": "100 Mountain View"
}
});
以這種方式使用set()
會覆寫指定位置的數據,包括任何子節點。但是,您仍然可以更新子物件而無需重寫整個物件。如果您想允許用戶更新他們的個人資料,您可以如下更新用戶名:
DatabaseReference ref = FirebaseDatabase.instance.ref("users/123");
// Only update the name, leave the age and address!
await ref.update({
"age": 19,
});
update()
方法接受節點的子路徑,允許您一次更新資料庫上的多個節點:
DatabaseReference ref = FirebaseDatabase.instance.ref("users");
await ref.update({
"123/age": 19,
"123/address/line1": "1 Mountain View",
});
讀取數據
透過監聽值事件來讀取數據
若要讀取路徑上的資料並偵聽更改,請使用DatabaseReference
的onValue
屬性來偵聽DatabaseEvent
。
您可以使用DatabaseEvent
讀取給定路徑上的數據,因為它在事件發生時存在。此事件在附加偵聽器時觸發一次,每次資料(包括任何子項目)發生變更時都會觸發一次。該事件具有一個snapshot
屬性,其中包含該位置的所有數據,包括子數據。如果沒有數據,快照的exists
屬性將為false
,其value
屬性將為 null。
以下範例示範了一個社交部落格應用程式從資料庫檢索貼文的詳細資訊:
DatabaseReference starCountRef =
FirebaseDatabase.instance.ref('posts/$postId/starCount');
starCountRef.onValue.listen((DatabaseEvent event) {
final data = event.snapshot.value;
updateStarCount(data);
});
偵聽器接收一個DataSnapshot
,該資料快照的value
屬性中包含事件發生時資料庫中指定位置的資料。
讀取一次數據
使用 get() 讀取一次
該 SDK 旨在管理與資料庫伺服器的交互,無論您的應用程式是在線還是離線。
通常,您應該使用上述值事件技術來讀取數據,以從後端獲取數據更新的通知。這些技術可以減少您的使用量和費用,並經過最佳化,可以為您的用戶提供線上和離線的最佳體驗。
如果您只需要一次數據,則可以使用get()
從資料庫中取得資料的快照。如果因任何原因get()
無法傳回伺服器值,用戶端將探測本機儲存緩存,如果仍未找到該值,則傳回錯誤。
以下範例示範了從資料庫中檢索使用者的面向公眾的使用者名稱一次:
final ref = FirebaseDatabase.instance.ref();
final snapshot = await ref.child('users/$userId').get();
if (snapshot.exists) {
print(snapshot.value);
} else {
print('No data available.');
}
不必要地使用get()
會增加頻寬的使用並導致效能損失,這可以透過使用即時偵聽器來防止,如上所示。
使用once()讀取一次數據
在某些情況下,您可能希望立即傳回本機快取中的值,而不是檢查伺服器上的更新值。在這些情況下,您可以使用once()
立即從本機磁碟快取中取得資料。
這對於只需要載入一次並且預計不會頻繁更改或需要主動偵聽的資料非常有用。例如,前面範例中的部落格應用程式在用戶開始創作新貼文時使用此方法載入用戶的個人資料:
final event = await ref.once(DatabaseEventType.value);
final username = event.snapshot.value?.username ?? 'Anonymous';
更新或刪除數據
更新特定字段
若要同時寫入節點的特定子節點而不覆寫其他子節點,請使用update()
方法。
當呼叫update()
時,您可以透過指定鍵的路徑來更新較低層級的子值。如果資料儲存在多個位置以更好地擴展,您可以使用資料扇出更新該資料的所有實例。例如,社交部落格應用程式可能想要建立貼文並同時將其更新為最近的活動來源和發文使用者的活動來源。為此,部落格應用程式使用以下程式碼:
void writeNewPost(String uid, String username, String picture, String title,
String body) async {
// A post entry.
final postData = {
'author': username,
'uid': uid,
'body': body,
'title': title,
'starCount': 0,
'authorPic': picture,
};
// Get a key for a new Post.
final newPostKey =
FirebaseDatabase.instance.ref().child('posts').push().key;
// Write the new post's data simultaneously in the posts list and the
// user's post list.
final Map<String, Map> updates = {};
updates['/posts/$newPostKey'] = postData;
updates['/user-posts/$uid/$newPostKey'] = postData;
return FirebaseDatabase.instance.ref().update(updates);
}
此範例使用push()
在包含/posts/$postid
處所有使用者的帖子的節點中建立帖子,並同時使用key
檢索金鑰。然後,該金鑰可用於在/user-posts/$userid/$postid
處的使用者貼文中建立第二個條目。
使用這些路徑,您可以透過一次呼叫update()
對 JSON 樹中的多個位置執行同步更新,例如本範例如何在兩個位置建立新貼文。以這種方式進行的同時更新是原子的:要么所有更新成功,要么所有更新失敗。
新增完成回調
如果您想知道資料何時提交,可以註冊完成回呼。 set()
和update()
都傳回Future
,您可以向其中附加成功和錯誤回調,這些回調在寫入已提交到資料庫以及呼叫不成功時呼叫。
FirebaseDatabase.instance
.ref('users/$userId/email')
.set(emailAddress)
.then((_) {
// Data saved successfully!
})
.catchError((error) {
// The write failed...
});
刪除數據
刪除資料最簡單的方法是在對該資料位置的參考上呼叫remove()
。
您也可以透過將 null 指定為另一個寫入操作(例如set()
或update()
的值來刪除。您可以將此技術與update()
結合使用,以在單一 API 呼叫中刪除多個子項。
將資料儲存為交易
當處理可能因並發修改而損壞的資料(例如增量計數器)時,您可以透過將事務處理程序傳遞給runTransaction()
來使用事務。事務處理程序將資料的目前狀態作為參數,並傳回您想要寫入的新所需的狀態。如果在成功寫入新值之前另一個用戶端寫入該位置,則會使用新的目前值再次呼叫您的更新函數,並重試寫入。
例如,在範例社交部落格應用程式中,您可以允許用戶對貼文加註星標和取消星標,並追蹤貼文收到的星數,如下所示:
void toggleStar(String uid) async {
DatabaseReference postRef =
FirebaseDatabase.instance.ref("posts/foo-bar-123");
TransactionResult result = await postRef.runTransaction((Object? post) {
// Ensure a post at the ref exists.
if (post == null) {
return Transaction.abort();
}
Map<String, dynamic> _post = Map<String, dynamic>.from(post as Map);
if (_post["stars"] is Map && _post["stars"][uid] != null) {
_post["starCount"] = (_post["starCount"] ?? 1) - 1;
_post["stars"][uid] = null;
} else {
_post["starCount"] = (_post["starCount"] ?? 0) + 1;
if (!_post.containsKey("stars")) {
_post["stars"] = {};
}
_post["stars"][uid] = true;
}
// Return the new data.
return Transaction.success(_post);
});
}
預設情況下,每次交易更新函數運行時都會引發事件,因此您多次執行函數,您可能會看到中間狀態。您可以將applyLocally
設定為false
以抑制這些中間狀態,而是等到交易完成後再引發事件:
await ref.runTransaction((Object? post) {
// ...
}, applyLocally: false);
交易的結果是TransactionResult
,其中包含交易是否已提交以及新快照等資訊:
DatabaseReference ref = FirebaseDatabase.instance.ref("posts/123");
TransactionResult result = await ref.runTransaction((Object? post) {
// ...
});
print('Committed? ${result.committed}'); // true / false
print('Snapshot? ${result.snapshot}'); // DataSnapshot
取消交易
如果您想要安全地取消事務,請呼叫Transaction.abort()
拋出AbortTransactionException
:
TransactionResult result = await ref.runTransaction((Object? user) {
if (user !== null) {
return Transaction.abort();
}
// ...
});
print(result.committed); // false
原子伺服器端增量
在上面的用例中,我們將兩個值寫入資料庫:為貼文加註星標/取消加註星標的使用者的 ID,以及增加的星數。如果我們已經知道用戶正在為帖子加註星標,我們可以使用原子增量操作而不是事務。
void addStar(uid, key) async {
Map<String, Object?> updates = {};
updates["posts/$key/stars/$uid"] = true;
updates["posts/$key/starCount"] = ServerValue.increment(1);
updates["user-posts/$key/stars/$uid"] = true;
updates["user-posts/$key/starCount"] = ServerValue.increment(1);
return FirebaseDatabase.instance.ref().update(updates);
}
此程式碼不使用事務操作,因此如果存在更新衝突,它不會自動重新運行。但是,由於增量操作直接發生在資料庫伺服器上,因此不會發生衝突。
如果您想要偵測並拒絕特定於應用程式的衝突,例如使用者為他們之前已經加註過星標的貼文加註星標,您應該為該用例編寫自訂安全規則。
離線處理數據
如果客戶端失去網路連接,您的應用程式將繼續正常運作。
連接到 Firebase 資料庫的每個用戶端都會維護自己的任何活動資料的內部版本。寫入資料時,請先寫入此本機版本。然後,Firebase 用戶端會「盡力」將該資料與遠端資料庫伺服器和其他用戶端同步。
因此,在將任何資料寫入伺服器之前,對資料庫的所有寫入都會立即觸發本機事件。這意味著無論網路延遲或連接如何,您的應用程式都保持回應。
重新建立連線後,您的應用程式會收到適當的事件集,以便用戶端與目前伺服器狀態同步,而無需編寫任何自訂程式碼。
我們將在了解有關線上和離線功能的更多資訊中詳細討論離線行為。