1. 概述
目標
在此 Codelab 中，您將使用 Swift 在 iOS 上構建一個由 Firestore 支持的餐廳推薦應用。你將學到如何：
- 從 iOS 應用讀取數據並將其寫入 Firestore
- 實時監聽 Firestore 數據的變化
- 使用 Firebase 身份驗證和安全規則來保護 Firestore 數據
- 編寫複雜的 Firestore 查詢
先決條件
在開始此 Codelab 之前，請確保您已安裝：
- Xcode 版本 14.0（或更高版本）
- CocoaPods 1.12.0（或更高版本）
2.創建Firebase控制台項目
將 Firebase 添加到項目中
- 轉到Firebase 控制台。
- 選擇“創建新項目”並將您的項目命名為“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中的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/project-id/database/firestore/indexes?create_composite=..."
UserInfo={NSLocalizedDescription=The query requires an index. You can create it here: https://console.firebase.google.com/project/project-id/database/firestore/indexes?create_composite=...}
這是因為 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條件將阻止提交任何評論。第二個匹配語句允許任何經過身份驗證的用戶在數據庫中讀取和寫入餐館。
這對於我們的評論非常有效，因為我們已經使用安全規則來明確聲明我們之前寫入應用程序的隱式保證 - 用戶只能撰寫自己的評論。如果我們要為評論添加編輯或刪除功能，這組完全相同的規則也會阻止用戶修改或刪除其他用戶的評論。但 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;
}
}
}
在這裡，我們將寫入權限分為創建和更新，以便我們可以更具體地了解應該允許哪些操作。任何用戶都可以將餐館寫入數據庫，保留我們在 Codelab 開始時創建的填充按鈕的功能，但是一旦寫入餐館，其名稱、位置、價格和類別就無法更改。更具體地說，最後一條規則要求任何餐廳更新操作都保持數據庫中現有字段的名稱、城市、價格和類別相同。
要詳細了解如何使用安全規則，請查看文檔。
9. 結論
在此 Codelab 中，您學習瞭如何使用 Firestore 進行基本和高級讀寫，以及如何使用安全規則保護數據訪問。您可以在codelab-complete分支上找到完整的解決方案。
要了解有關 Firestore 的更多信息，請訪問以下資源：