一、概述
目標
在本 Codelab 中，您將使用 Swift 在 iOS 上構建一個 Firestore 支持的餐廳推薦應用。你將學到如何：
- 從 iOS 應用讀取數據並將數據寫入 Firestore
- 實時監聽 Firestore 數據的變化
- 使用 Firebase 身份驗證和安全規則來保護 Firestore 數據
- 編寫複雜的 Firestore 查詢
先決條件
在開始此 Codelab 之前，請確保您已安裝：
- Xcode 版本 13.0（或更高）
- CocoaPods 1.11.0（或更高版本）
2. 創建 Firebase 控制台項目
將 Firebase 添加到項目中
- 轉到Firebase 控制台。
- 選擇Create New Project並將您的項目命名為“Firestore iOS Codelab”。
3. 獲取示例項目
下載代碼
首先克隆示例項目並在項目目錄中運行pod update ：
git clone https://github.com/firebase/friendlyeats-ios cd friendlyeats-ios pod update
在 Xcode 中打開FriendlyEats.xcworkspace並運行它 (Cmd+R)。該應用程序應該正確編譯並在啟動時立即崩潰，因為它缺少GoogleService-Info.plist文件。我們將在下一步中糾正它。
設置 Firebase
按照文檔創建一個新的 Firestore 項目。獲得項目後，從Firebase 控制台下載項目的GoogleService-Info.plist文件並將其拖到 Xcode 項目的根目錄。再次運行項目以確保應用程序配置正確並且在啟動時不再崩潰。登錄後，您應該會看到一個空白屏幕，如下例所示。如果您無法登錄，請確保您已在 Firebase 控制台中的身份驗證下啟用電子郵件/密碼登錄方法。
4. 將數據寫入 Firestore
在本節中，我們將向 Firestore 寫入一些數據，以便我們可以填充應用程序 UI。這可以通過Firebase 控制台手動完成，但我們將在應用程序本身中執行此操作以演示基本的 Firestore 寫入。
我們應用程序中的主要模型對像是餐廳。 Firestore 數據分為文檔、集合和子集合。我們將把每家餐館作為一個文檔存儲在一個名為restaurants的頂級集合中。如果您想了解有關 Firestore 數據模型的更多信息，請閱讀文檔中的文檔和集合。
在將數據添加到 Firestore 之前，我們需要獲取餐廳集合的引用。將以下內容添加到RestaurantsTableViewController.didTapPopulateButton(_:)方法的內部 for 循環中。
let collection = Firestore.firestore().collection("restaurants")
現在我們有了一個集合引用，我們可以寫入一些數據。在我們添加的最後一行代碼之後添加以下內容：
let collection = Firestore.firestore().collection("restaurants")
// ====== ADD THIS ======
let restaurant = Restaurant(
name: name,
category: category,
city: city,
price: price,
ratingCount: 0,
averageRating: 0
)
collection.addDocument(data: restaurant.dictionary)
上面的代碼向餐館集合添加了一個新文檔。文檔數據來自字典，我們從 Restaurant 結構中獲取。
我們快到了——在我們可以將文檔寫入 Firestore 之前，我們需要打開 Firestore 的安全規則並描述我們數據庫的哪些部分應該由哪些用戶寫入。目前，我們將只允許經過身份驗證的用戶讀取和寫入整個數據庫。這對於生產應用程序來說有點過於寬鬆了，但是在應用程序構建過程中，我們想要一些足夠放鬆的東西，這樣我們就不會在試驗時經常遇到身份驗證問題。在本 Codelab 的最後，我們將討論如何強化您的安全規則並限制意外讀取和寫入的可能性。
在 Firebase 控制台的規則選項卡中添加以下規則，然後單擊發布。
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /{document=**} {
//
// WARNING: These rules are insecure! We will replace them with
// more secure rules later in the codelab
//
allow read, write: if request.auth != null;
}
}
}
稍後我們將詳細討論安全規則，但如果您趕時間，請查看安全規則文檔。
運行應用程序並登錄。然後點擊左上角的“填充”按鈕，這將創建一批餐廳文檔，儘管您還不會在應用程序中看到它。
接下來，導航到 Firebase 控制台中的Firestore 數據選項卡。您現在應該會在餐館集合中看到新條目：
恭喜，您剛剛將數據從 iOS 應用程序寫入 Firestore！在下一部分中，您將學習如何從 Firestore 中檢索數據並將其顯示在應用程序中。
5. 顯示 Firestore 中的數據
在本節中，您將學習如何從 Firestore 中檢索數據並將其顯示在應用程序中。兩個關鍵步驟是創建查詢和添加快照偵聽器。此偵聽器將收到與查詢匹配的所有現有數據的通知，並實時接收更新。
首先，讓我們構建將提供默認的、未過濾的餐館列表的查詢。看一下RestaurantsTableViewController.baseQuery()的實現：
return Firestore.firestore().collection("restaurants").limit(to: 50)
此查詢檢索名為“restaurants”的頂級集合中最多 50 家餐館。現在我們有了一個查詢，我們需要附加一個快照監聽器來將數據從 Firestore 加載到我們的應用程序中。在調用stopObserving()之後，將以下代碼添加到RestaurantsTableViewController.observeQuery()方法。
listener = query.addSnapshotListener { [unowned self] (snapshot, error) in
guard let snapshot = snapshot else {
print("Error fetching snapshot results: \(error!)")
return
}
let models = snapshot.documents.map { (document) -> Restaurant in
if let model = Restaurant(dictionary: document.data()) {
return model
} else {
// Don't use fatalError here in a real app.
fatalError("Unable to initialize type \(Restaurant.self) with dictionary \(document.data())")
}
}
self.restaurants = models
self.documents = snapshot.documents
if self.documents.count > 0 {
self.tableView.backgroundView = nil
} else {
self.tableView.backgroundView = self.backgroundView
}
self.tableView.reloadData()
}
上面的代碼從 Firestore 下載集合併將其存儲在本地數組中。 addSnapshotListener(_:)調用將快照偵聽器添加到查詢中，該偵聽器將在每次服務器上的數據更改時更新視圖控制器。我們自動獲取更新，無需手動推送更改。請記住，此快照偵聽器可以在服務器端更改的任何時候被調用，因此我們的應用程序可以處理更改非常重要。
在將我們的字典映射到結構之後（參見Restaurant.swift ），顯示數據只是分配一些視圖屬性的問題。將以下行添加到 RestaurantsTableViewController.swift 中的RestaurantsTableViewController.swift RestaurantTableViewCell.populate(restaurant:) 。
nameLabel.text = restaurant.name
cityLabel.text = restaurant.city
categoryLabel.text = restaurant.category
starsView.rating = Int(restaurant.averageRating.rounded())
priceLabel.text = priceString(from: restaurant.price)
這個填充方法是從表視圖數據源的tableView(_:cellForRowAtIndexPath:)方法調用的，該方法負責將值類型的集合從之前的映射到各個表視圖單元格。
再次運行應用程序並驗證我們之前在控制台中看到的餐館現在在模擬器或設備上可見。如果您成功完成本部分，您的應用現在正在使用 Cloud Firestore 讀取和寫入數據！
6. 排序和過濾數據
目前我們的應用程序顯示餐廳列表，但用戶無法根據自己的需求進行過濾。在本節中，您將使用 Firestore 的高級查詢來啟用過濾。
這是獲取所有點心餐廳的簡單查詢示例：
let filteredQuery = query.whereField("category", isEqualTo: "Dim Sum")
顧名思義， whereField(_:isEqualTo:)方法將使我們的查詢僅下載其字段滿足我們設置的限制的集合成員。在這種情況下，它只會下載category為"Dim Sum"的餐館。
在這個應用程序中，用戶可以鏈接多個過濾器來創建特定的查詢，例如“舊金山的披薩”或“洛杉磯的海鮮按人氣訂購”。
打開RestaurantsTableViewController.swift並將以下代碼塊添加到query(withCategory:city:price:sortBy:)的中間：
if let category = category, !category.isEmpty {
filtered = filtered.whereField("category", isEqualTo: category)
}
if let city = city, !city.isEmpty {
filtered = filtered.whereField("city", isEqualTo: city)
}
if let price = price {
filtered = filtered.whereField("price", isEqualTo: price)
}
if let sortBy = sortBy, !sortBy.isEmpty {
filtered = filtered.order(by: sortBy)
}
上面的代碼片段添加了多個whereField和order子句，以基於用戶輸入構建單個複合查詢。現在我們的查詢將只返回符合用戶要求的餐館。
運行您的項目並驗證您可以按價格、城市和類別進行過濾（確保准確輸入類別和城市名稱）。在測試時，您可能會在日誌中看到如下所示的錯誤：
Error fetching snapshot results: Error Domain=io.grpc Code=9
"The query requires an index. You can create it here: https://console.firebase.google.com/project/testapp-5d356/database/firestore/indexes?create_index=..."
UserInfo={NSLocalizedDescription=The query requires an index. You can create it here: https://console.firebase.google.com/project/project-id/database/firestore/indexes?create_index=...}
這是因為 Firestore 需要大多數複合查詢的索引。對查詢要求索引可以使 Firestore 保持快速的規模化。打開錯誤消息中的鏈接將自動在 Firebase 控制台中打開索引創建 UI，並填寫正確的參數。要了解有關 Firestore 中索引的更多信息，請訪問文檔。
7. 在事務中寫入數據
在本節中，我們將添加用戶向餐廳提交評論的功能。到目前為止，我們所有的寫入都是原子的並且相對簡單。如果其中任何一個出錯，我們可能會提示用戶重試或自動重試。
為了給餐廳添加評分，我們需要協調多次讀取和寫入。首先必須提交評論本身，然後需要更新餐廳的評分計數和平均評分。如果其中一個失敗但另一個失敗，我們將處於不一致的狀態，即我們數據庫的一部分中的數據與另一部分中的數據不匹配。
幸運的是，Firestore 提供了事務功能，讓我們可以在單個原子操作中執行多次讀取和寫入，確保我們的數據保持一致。
在RestaurantDetailViewController.reviewController(_:didSubmitFormWithReview:)中的所有 let 聲明下方添加以下代碼。
let firestore = Firestore.firestore()
firestore.runTransaction({ (transaction, errorPointer) -> Any? in
// Read data from Firestore inside the transaction, so we don't accidentally
// update using stale client data. Error if we're unable to read here.
let restaurantSnapshot: DocumentSnapshot
do {
try restaurantSnapshot = transaction.getDocument(reference)
} catch let error as NSError {
errorPointer?.pointee = error
return nil
}
// Error if the restaurant data in Firestore has somehow changed or is malformed.
guard let data = restaurantSnapshot.data(),
let restaurant = Restaurant(dictionary: data) else {
let error = NSError(domain: "FireEatsErrorDomain", code: 0, userInfo: [
NSLocalizedDescriptionKey: "Unable to write to restaurant at Firestore path: \(reference.path)"
])
errorPointer?.pointee = error
return nil
}
// Update the restaurant's rating and rating count and post the new review at the
// same time.
let newAverage = (Float(restaurant.ratingCount) * restaurant.averageRating + Float(review.rating))
/ Float(restaurant.ratingCount + 1)
transaction.setData(review.dictionary, forDocument: newReviewReference)
transaction.updateData([
"numRatings": restaurant.ratingCount + 1,
"avgRating": newAverage
], forDocument: reference)
return nil
}) { (object, error) in
if let error = error {
print(error)
} else {
// Pop the review controller on success
if self.navigationController?.topViewController?.isKind(of: NewReviewViewController.self) ?? false {
self.navigationController?.popViewController(animated: true)
}
}
}
在更新塊內部，我們使用事務對象進行的所有操作都將被 Firestore 視為單個原子更新。如果服務器上的更新失敗，Firestore 會自動重試幾次。這意味著我們的錯誤情況很可能是重複發生的單個錯誤，例如，如果設備完全離線或用戶無權寫入他們嘗試寫入的路徑。
8. 安全規則
我們應用程序的用戶不應該能夠讀取和寫入我們數據庫中的每條數據。例如，每個人都應該能夠看到餐廳的評分，但應該只允許經過身份驗證的用戶發布評分。在客戶端編寫好的代碼是不夠的，我們需要在後端指定我們的數據安全模型才能完全安全。在本節中，我們將學習如何使用 Firebase 安全規則來保護我們的數據。
首先，讓我們深入了解一下我們在 Codelab 開始時編寫的安全規則。打開 Firebase 控制台並導航到Firestore 選項卡中的數據庫 > 規則。
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /{document=**} {
// Only authenticated users can read or write data
allow read, write: if request.auth != null;
}
}
}
上述規則中的request變量是所有規則中都可用的全局變量，我們添加的條件確保請求在允許用戶做任何事情之前經過身份驗證。這可以防止未經身份驗證的用戶使用 Firestore API 對您的數據進行未經授權的更改。這是一個好的開始，但我們可以使用 Firestore 規則來做更強大的事情。
讓我們限制評論寫入，以便評論的用戶 ID 必須與經過身份驗證的用戶的 ID 匹配。這樣可以確保用戶不能互相冒充並留下欺詐性評論。將您的安全規則替換為以下內容：
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /restaurants/{any}/ratings/{rating} {
// Users can only write ratings with their user ID
allow read;
allow write: if request.auth != null
&& request.auth.uid == request.resource.data.userId;
}
match /restaurants/{any} {
// Only authenticated users can read or write data
allow read, write: if request.auth != null;
}
}
}
第一個匹配語句匹配屬於restaurants集合的任何文檔的名為ratings的子集合。如果評論的用戶 ID 與用戶的用戶 ID 不匹配，則allow write條件會阻止提交任何評論。第二個 match 語句允許任何經過身份驗證的用戶在數據庫中讀取和寫入餐廳。
這對我們的評論非常有效，因為我們使用安全規則明確聲明了我們之前寫入應用程序的隱含保證——用戶只能編寫自己的評論。如果我們要為評論添加編輯或刪除功能，這組完全相同的規則也會阻止用戶修改或刪除其他用戶的評論。但 Firestore 規則也可以以更精細的方式使用，以限制對文檔中單個字段的寫入，而不是整個文檔本身。我們可以使用它來允許用戶僅更新餐廳的評分、平均評分和評分數量，從而消除惡意用戶更改餐廳名稱或位置的可能性。
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /restaurants/{restaurant} {
match /ratings/{rating} {
allow read: if request.auth != null;
allow write: if request.auth != null
&& request.auth.uid == request.resource.data.userId;
}
allow read: if request.auth != null;
allow create: if request.auth != null;
allow update: if request.auth != null
&& request.resource.data.name == resource.data.name
&& request.resource.data.city == resource.data.city
&& request.resource.data.price == resource.data.price
&& request.resource.data.category == resource.data.category;
}
}
}
在這裡，我們將寫入權限拆分為創建和更新，以便我們可以更具體地確定應該允許哪些操作。任何用戶都可以將餐廳寫入數據庫，保留我們在代碼實驗室開始時創建的 Populate 按鈕的功能，但是一旦寫入餐廳，它的名稱、位置、價格和類別就無法更改。更具體地說，最後一條規則要求任何餐廳更新操作都必須與數據庫中已存在的字段保持相同的名稱、城市、價格和類別。
要了解有關您可以使用安全規則執行哪些操作的更多信息，請查看文檔。
9. 結論
在此 Codelab 中，您學習瞭如何使用 Firestore 進行基本和高級讀寫，以及如何使用安全規則保護數據訪問。您可以在codelab-complete分支上找到完整的解決方案。
要了解有關 Firestore 的更多信息，請訪問以下資源：