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. 选择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 控制台中的身份验证下启用电子邮件/密码登录方法。

d5225270159c040b.png

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 数据选项卡。您现在应该会在餐馆集合中看到新条目:

屏幕截图 2017-07-06 在 12.45.38 PM.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 的高级查询来启用过滤。

这是获取所有点心餐厅的简单查询示例:

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/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 的更多信息,请访问以下资源: