Cloud Firestore iOS 代碼實驗室

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

一、概述

目標

在此 Codelab 中,您將使用 Swift 在 iOS 上構建一個由 Firestore 支持的餐廳推薦應用。你將學到如何:

  1. 從 iOS 應用程序讀取數據並將數據寫入 Firestore
  2. 實時監聽 Firestore 數據的變化
  3. 使用 Firebase 身份驗證和安全規則來保護 Firestore 數據
  4. 編寫複雜的 Firestore 查詢

先決條件

在開始此 Codelab 之前,請確保您已安裝:

  • Xcode 版本 13.0(或更高版本)
  • CocoaPods 1.11.0(或更高版本)

2.創建Firebase控制台項目

將 Firebase 添加到項目中

  1. 轉到Firebase 控制台
  2. 選擇創建新項目並將您的項目命名為“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文件。我們將在下一步中更正該問題。

設置火力地堡

按照文檔創建一個新的 Firestore 項目。獲得項目後,從Firebase 控制台下載項目的GoogleService-Info.plist文件並將其拖到 Xcode 項目的根目錄。再次運行項目以確保應用程序配置正確並且不再在啟動時崩潰。登錄後,您應該會看到如下例所示的空白屏幕。如果您無法登錄,請確保您已在身份驗證下的 Firebase 控制台中啟用電子郵件/密碼登錄方法。

d5225270159c040b.png

4. 將數據寫入 Firestore

在本節中,我們將向 Firestore 寫入一些數據,以便我們可以填充應用 UI。這可以通過Firebase 控制台手動完成,但我們將在應用程序本身中完成,以演示基本的 Firestore 寫入。

我們應用程序中的主要模型對像是餐廳。 Firestore 數據分為文檔、集合和子集合。我們會將每家餐廳作為文檔存儲在名為restaurants的頂級集合中。如果您想了解有關 Firestore 數據模型的更多信息,請閱讀文檔中文檔和集合。

在我們可以將數據添加到 Firestore 之前,我們需要獲得對 restaurants 集合的引用。將以下內容添加到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)

上面的代碼向 restaurants 集合添加了一個新文檔。文檔數據來自我們從 Restaurant 結構體中獲取的字典。

我們快完成了——在我們可以將文檔寫入 Firestore 之前,我們需要打開 Firestore 的安全規則並描述我們數據庫的哪些部分應該由哪些用戶寫入。現在,我們只允許經過身份驗證的用戶讀取和寫入整個數據庫。這對於生產應用程序來說有點過於寬鬆,但在應用程序構建過程中,我們希望有足夠寬鬆的東西,這樣我們就不會在試驗時經常遇到身份驗證問題。在此 Codelab 結束時,我們將討論如何強化安全規則並限制意外讀寫的可能性。

在 Firebase 控制台的Rules 選項卡中添加以下規則,然後單擊Publish

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 數據選項卡。您現在應該在 restaurants 集合中看到新條目:

屏幕截圖 2017-07-06 下午 12.45.38.png

恭喜,您剛剛將數據從 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 讀取和寫入數據!

391c0259bf05ac25.png

6.排序和過濾數據

目前我們的應用程序顯示了一個餐廳列表,但用戶無法根據自己的需要進行過濾。在本節中,您將使用 Firestore 的高級查詢來啟用過濾。

下面是一個獲取所有 Dim Sum 餐廳的簡單查詢示例:

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

上面的代碼片段添加了多個whereFieldorder子句以基於用戶輸入構建單個複合查詢。現在我們的查詢將只返回符合用戶要求的餐廳。

運行您的項目並驗證您可以按價格、城市和類別進行過濾(確保准確鍵入類別和城市名稱)。在測試時,您可能會在日誌中看到如下所示的錯誤:

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 會自動重試幾次。這意味著我們的錯誤條件很可能是重複發生的單個錯誤,例如,如果設備完全離線或用戶無權寫入他們嘗試寫入的路徑。

八、安全規則

我們應用程序的用戶不應該能夠讀取和寫入我們數據庫中的每條數據。例如,每個人都應該能夠看到餐廳的評級,但只有經過身份驗證的用戶才能發布評級。僅僅在客戶端編寫好的代碼是不夠的,我們需要在後端指定我們的數據安全模型才能完全安全。在本節中,我們將學習如何使用 Firebase 安全規則來保護我們的數據。

首先,讓我們更深入地了解一下我們在 Codelab 開始時編寫的安全規則。打開 Firebase 控制台並導航到Firestore 選項卡中的 Database > Rules

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 開始時創建的 Populate 按鈕的功能,但是一旦餐廳被寫入,其名稱、位置、價格和類別就無法更改。更具體地說,最後一條規則要求任何餐廳更新操作保持與數據庫中現有字段相同的名稱、城市、價格和類別。

要詳細了解您可以使用安全規則做什麼,請查看文檔

9.結論

在此 Codelab 中,您學習瞭如何使用 Firestore 進行基本和高級讀寫,以及如何使用安全規則保護數據訪問。您可以在codelab-complete分支上找到完整的解決方案。

要了解有關 Firestore 的更多信息,請訪問以下資源: