Liên kết dữ liệu trên Cloud Firestore bằng Swift Codable

Codable API của Swift (được giới thiệu trong Swift 4) cho phép chúng ta tận dụng sức mạnh của trình biên dịch để dễ dàng liên kết dữ liệu từ các định dạng được chuyển đổi tuần tự với các loại Swift.

Bạn có thể đã sử dụng Codable để liên kết dữ liệu từ API web với mô hình dữ liệu của ứng dụng (và ngược lại), nhưng Codable linh hoạt hơn thế nhiều.

Trong hướng dẫn này, chúng ta sẽ xem xét cách sử dụng Codable để liên kết dữ liệu từ Cloud Firestore với các loại Swift và ngược lại.

Khi tìm nạp tài liệu từ Cloud Firestore, ứng dụng của bạn sẽ nhận được một từ điển gồm các cặp khoá/giá trị (hoặc một mảng từ điển, nếu bạn sử dụng một trong các thao tác trả về nhiều tài liệu).

Giờ đây, bạn chắc chắn có thể tiếp tục trực tiếp sử dụng từ điển trong Swift và chúng mang lại sự linh hoạt tuyệt vời, có thể chính xác là những gì trường hợp sử dụng của bạn yêu cầu. Tuy nhiên, phương pháp này không an toàn về kiểu và dễ gây ra lỗi khó theo dõi do viết sai chính tả tên thuộc tính hoặc quên liên kết thuộc tính mới mà nhóm của bạn đã thêm khi họ ra mắt tính năng mới thú vị vào tuần trước.

Trước đây, nhiều nhà phát triển đã khắc phục những thiếu sót này bằng cách triển khai một lớp ánh xạ đơn giản cho phép họ ánh xạ từ điển sang các loại Swift. Tuy nhiên, hầu hết các phương thức triển khai này đều dựa trên việc chỉ định theo cách thủ công mối liên kết giữa các tài liệu Cloud Firestore và các loại tương ứng của mô hình dữ liệu trong ứng dụng.

Nhờ khả năng hỗ trợ của Cloud Firestore cho API Codable của Swift, việc này trở nên dễ dàng hơn nhiều:

  • Bạn sẽ không còn phải triển khai bất kỳ mã liên kết nào theo cách thủ công nữa.
  • Bạn có thể dễ dàng xác định cách liên kết các thuộc tính có tên khác nhau.
  • Thư viện này có tính năng hỗ trợ tích hợp cho nhiều loại của Swift.
  • Ngoài ra, bạn có thể dễ dàng thêm tính năng hỗ trợ để liên kết các loại tuỳ chỉnh.
  • Điều tuyệt vời nhất là đối với các mô hình dữ liệu đơn giản, bạn sẽ không phải viết bất kỳ mã ánh xạ nào.

Dữ liệu liên kết

Cloud Firestore lưu trữ dữ liệu trong các tài liệu liên kết khoá với giá trị. Để tìm nạp dữ liệu từ một tài liệu riêng lẻ, chúng ta có thể gọi DocumentSnapshot.data(). Hàm này sẽ trả về một từ điển liên kết tên trường với Any: func data() -> [String : Any]?.

Điều này có nghĩa là chúng ta có thể sử dụng cú pháp chỉ số dưới của Swift để truy cập vào từng trường riêng lẻ.

import FirebaseFirestore

#warning("DO NOT MAP YOUR DOCUMENTS MANUALLY. USE CODABLE INSTEAD.")
func fetchBook(documentId: String) {
  let docRef = db.collection("books").document(documentId)

  docRef.getDocument { document, error in
    if let error = error as NSError? {
      self.errorMessage = "Error getting document: \(error.localizedDescription)"
    }
    else {
      if let document = document {
        let id = document.documentID
        let data = document.data()
        let title = data?["title"] as? String ?? ""
        let numberOfPages = data?["numberOfPages"] as? Int ?? 0
        let author = data?["author"] as? String ?? ""
        self.book = Book(id:id, title: title, numberOfPages: numberOfPages, author: author)
      }
    }
  }
}

Mặc dù có vẻ đơn giản và dễ triển khai, nhưng mã này không ổn định, khó duy trì và dễ xảy ra lỗi.

Như bạn có thể thấy, chúng tôi đang đưa ra giả định về các loại dữ liệu của trường tài liệu. Những thông tin này có thể đúng hoặc không.

Xin lưu ý rằng vì không có giản đồ nên bạn có thể dễ dàng thêm tài liệu mới vào bộ sưu tập và chọn một loại khác cho trường. Bạn có thể vô tình chọn chuỗi cho trường numberOfPages, dẫn đến vấn đề liên kết khó tìm. Ngoài ra, bạn sẽ phải cập nhật mã liên kết mỗi khi thêm một trường mới, việc này khá rườm rà.

Và đừng quên rằng chúng ta không tận dụng hệ thống kiểu mạnh của Swift, hệ thống này biết chính xác kiểu chính xác cho từng thuộc tính của Book.

Codable là gì?

Theo tài liệu của Apple, Codable là "một loại có thể tự chuyển đổi thành và từ một bản trình bày bên ngoài". Trên thực tế, Codable là một bí danh loại cho các giao thức Encodable và Decodable. Bằng cách điều chỉnh một loại Swift cho phù hợp với giao thức này, trình biên dịch sẽ tổng hợp mã cần thiết để mã hoá/giải mã một thực thể của loại này từ một định dạng được chuyển đổi tuần tự, chẳng hạn như JSON.

Một loại đơn giản để lưu trữ dữ liệu về một cuốn sách có thể có dạng như sau:

struct Book: Codable {
  var title: String
  var numberOfPages: Int
  var author: String
}

Như bạn có thể thấy, việc điều chỉnh kiểu thành Codable là cách ít gây ảnh hưởng nhất. Chúng ta chỉ cần thêm sự tuân thủ vào giao thức; không cần thay đổi gì khác.

Giờ đây, chúng ta có thể dễ dàng mã hoá một cuốn sách thành đối tượng JSON:

do {
  let book = Book(title: "The Hitchhiker's Guide to the Galaxy",
                  numberOfPages: 816,
                  author: "Douglas Adams")
  let encoder = JSONEncoder()
  let data = try encoder.encode(book)
}
catch {
  print("Error when trying to encode book: \(error)")
}

Việc giải mã một đối tượng JSON thành một thực thể Book sẽ hoạt động như sau:

let decoder = JSONDecoder()
let data = /* fetch data from the network */
let decodedBook = try decoder.decode(Book.self, from: data)

Ánh xạ đến và từ các loại đơn giản trong tài liệu Cloud Firestore bằng Codable

Cloud Firestore hỗ trợ nhiều loại dữ liệu, từ chuỗi đơn giản đến bản đồ lồng nhau. Hầu hết các loại này đều tương ứng trực tiếp với các loại tích hợp sẵn của Swift. Trước tiên, hãy xem cách liên kết một số loại dữ liệu đơn giản trước khi tìm hiểu sâu hơn về các loại dữ liệu phức tạp hơn.

Để liên kết tài liệu Cloud Firestore với các loại Swift, hãy làm theo các bước sau:

  1. Đảm bảo bạn đã thêm khung FirebaseFirestore vào dự án của mình. Bạn có thể sử dụng Trình quản lý gói Swift hoặc CocoaPods để làm việc này.
  2. Nhập FirebaseFirestore vào tệp Swift.
  3. Điều chỉnh loại của bạn cho phù hợp với Codable.
  4. (Không bắt buộc, nếu bạn muốn sử dụng loại này trong chế độ xem List) Thêm thuộc tính id vào loại của bạn và sử dụng @DocumentID để yêu cầu Cloud Firestore liên kết thuộc tính này với mã tài liệu. Chúng ta sẽ thảo luận chi tiết hơn về vấn đề này ở phần bên dưới.
  5. Sử dụng documentReference.data(as: ) để liên kết tệp tham chiếu tài liệu với một loại Swift.
  6. Sử dụng documentReference.setData(from: ) để liên kết dữ liệu từ các loại Swift với một tài liệu Cloud Firestore.
  7. (Không bắt buộc, nhưng bạn nên thực hiện) Triển khai biện pháp xử lý lỗi phù hợp.

Hãy cập nhật loại Book cho phù hợp:

struct Book: Codable {
  @DocumentID var id: String?
  var title: String
  var numberOfPages: Int
  var author: String
}

Vì loại này đã có thể lập trình nên chúng ta chỉ cần thêm thuộc tính id và chú thích thuộc tính đó bằng trình bao bọc thuộc tính @DocumentID.

Lấy đoạn mã trước đó để tìm nạp và liên kết tài liệu, chúng ta có thể thay thế tất cả mã liên kết thủ công bằng một dòng:

func fetchBook(documentId: String) {
  let docRef = db.collection("books").document(documentId)

  docRef.getDocument { document, error in
    if let error = error as NSError? {
      self.errorMessage = "Error getting document: \(error.localizedDescription)"
    }
    else {
      if let document = document {
        do {
          self.book = try document.data(as: Book.self)
        }
        catch {
          print(error)
        }
      }
    }
  }
}

Bạn có thể viết mã này ngắn gọn hơn nữa bằng cách chỉ định loại tài liệu khi gọi getDocument(as:). Thao tác này sẽ thực hiện việc liên kết cho bạn và trả về một loại Result chứa tài liệu được liên kết hoặc lỗi trong trường hợp không giải mã được:

private func fetchBook(documentId: String) {
  let docRef = db.collection("books").document(documentId)

  docRef.getDocument(as: Book.self) { result in
    switch result {
    case .success(let book):
      // A Book value was successfully initialized from the DocumentSnapshot.
      self.book = book
      self.errorMessage = nil
    case .failure(let error):
      // A Book value could not be initialized from the DocumentSnapshot.
      self.errorMessage = "Error decoding document: \(error.localizedDescription)"
    }
  }
}

Việc cập nhật tài liệu hiện có cũng đơn giản như việc gọi documentReference.setData(from: ). Dưới đây là mã để lưu một thực thể Book, bao gồm cả một số cách xử lý lỗi cơ bản:

func updateBook(book: Book) {
  if let id = book.id {
    let docRef = db.collection("books").document(id)
    do {
      try docRef.setData(from: book)
    }
    catch {
      print(error)
    }
  }
}

Khi thêm một tài liệu mới, Cloud Firestore sẽ tự động chỉ định một mã tài liệu mới cho tài liệu đó. Tính năng này hoạt động ngay cả khi ứng dụng đang không có mạng.

func addBook(book: Book) {
  let collectionRef = db.collection("books")
  do {
    let newDocReference = try collectionRef.addDocument(from: self.book)
    print("Book stored with new document reference: \(newDocReference)")
  }
  catch {
    print(error)
  }
}

Ngoài việc liên kết các loại dữ liệu đơn giản, Cloud Firestore còn hỗ trợ một số loại dữ liệu khác, trong đó có một số loại dữ liệu có cấu trúc mà bạn có thể dùng để tạo các đối tượng lồng nhau bên trong một tài liệu.

Kiểu tuỳ chỉnh lồng nhau

Hầu hết các thuộc tính mà chúng ta muốn liên kết trong tài liệu đều là các giá trị đơn giản, chẳng hạn như tiêu đề sách hoặc tên tác giả. Nhưng còn những trường hợp chúng ta cần lưu trữ một đối tượng phức tạp hơn thì sao? Ví dụ: chúng ta có thể muốn lưu trữ URL của bìa sách ở nhiều độ phân giải.

Cách dễ nhất để thực hiện việc này trong Cloud Firestore là sử dụng bản đồ:

Lưu trữ một loại tuỳ chỉnh lồng nhau trong tài liệu Firestore

Khi viết cấu trúc Swift tương ứng, chúng ta có thể tận dụng việc Cloud Firestore hỗ trợ URL – khi lưu trữ một trường chứa URL, trường đó sẽ được chuyển đổi thành chuỗi và ngược lại:

struct CoverImages: Codable {
  var small: URL
  var medium: URL
  var large: URL
}

struct BookWithCoverImages: Codable {
  @DocumentID var id: String?
  var title: String
  var numberOfPages: Int
  var author: String
  var cover: CoverImages?
}

Hãy lưu ý cách chúng ta xác định một cấu trúc, CoverImages, cho bản đồ bìa trong tài liệu Cloud Firestore. Bằng cách đánh dấu thuộc tính bìa trên BookWithCoverImages là không bắt buộc, chúng ta có thể xử lý trường hợp một số tài liệu có thể không chứa thuộc tính bìa.

Nếu bạn thắc mắc tại sao không có đoạn mã nào để tìm nạp hoặc cập nhật dữ liệu, bạn sẽ rất vui khi biết rằng không cần mã để đọc hoặc ghi từ/vào Cloud Firestore: tất cả những việc này đều hoạt động với mã mà chúng ta đã viết trong phần đầu.

Mảng

Đôi khi, chúng ta muốn lưu trữ một tập hợp các giá trị trong một tài liệu. Thể loại của một cuốn sách là một ví dụ điển hình: một cuốn sách như The Hitchhiker's Guide to the Galaxy (Bí kíp quá giang vào Ngân Hà) có thể thuộc nhiều danh mục, trong trường hợp này là "Khoa học viễn tưởng" và "Hài kịch":

Lưu trữ một mảng trong tài liệu Firestore

Trong Cloud Firestore, chúng ta có thể lập mô hình bằng cách sử dụng một mảng giá trị. Tính năng này được hỗ trợ cho mọi loại có thể lập trình (chẳng hạn như String, Int, v.v.). Ví dụ sau đây cho biết cách thêm một mảng thể loại vào mô hình Book:

public struct BookWithGenre: Codable {
  @DocumentID var id: String?
  var title: String
  var numberOfPages: Int
  var author: String
  var genres: [String]
}

Vì cách này áp dụng được cho mọi loại có thể lập trình, nên chúng ta cũng có thể sử dụng các loại tuỳ chỉnh. Giả sử chúng ta muốn lưu trữ danh sách thẻ cho mỗi cuốn sách. Cùng với tên của thẻ, chúng ta cũng muốn lưu trữ màu của thẻ, như sau:

Lưu trữ một mảng các loại tuỳ chỉnh trong tài liệu Firestore

Để lưu trữ thẻ theo cách này, tất cả những gì chúng ta cần làm là triển khai cấu trúc Tag để biểu thị một thẻ và làm cho thẻ đó có thể lập trình:

struct Tag: Codable, Hashable {
  var title: String
  var color: String
}

Và cứ như vậy, chúng ta có thể lưu trữ một mảng Tags trong tài liệu Book!

struct BookWithTags: Codable {
  @DocumentID var id: String?
  var title: String
  var numberOfPages: Int
  var author: String
  var tags: [Tag]
}

Giới thiệu nhanh về việc liên kết mã tài liệu

Trước khi chuyển sang liên kết các loại khác, hãy nói về việc liên kết mã tài liệu trong giây lát.

Chúng ta đã sử dụng trình bao bọc thuộc tính @DocumentID trong một số ví dụ trước để liên kết mã tài liệu của tài liệu Cloud Firestore với thuộc tính id của các loại Swift. Điều này rất quan trọng vì một số lý do:

  • Việc này giúp chúng ta biết tài liệu nào cần cập nhật trong trường hợp người dùng thực hiện các thay đổi cục bộ.
  • List của SwiftUI yêu cầu các phần tử của nó phải là Identifiable để ngăn các phần tử nhảy xung quanh khi được chèn.

Cần lưu ý rằng thuộc tính được đánh dấu là @DocumentID sẽ không được bộ mã hoá của Cloud Firestore mã hoá khi ghi lại tài liệu. Điều này là do mã tài liệu không phải là thuộc tính của chính tài liệu đó, vì vậy, việc ghi mã tài liệu vào tài liệu sẽ là một sai lầm.

Khi làm việc với các loại lồng nhau (chẳng hạn như mảng thẻ trên Book trong một ví dụ trước đó trong hướng dẫn này), bạn không cần thêm thuộc tính @DocumentID: các thuộc tính lồng nhau là một phần của tài liệu Cloud Firestore và không cấu thành một tài liệu riêng biệt. Do đó, các tài liệu này không cần mã tài liệu.

Ngày và giờ

Cloud Firestore có một kiểu dữ liệu tích hợp để xử lý ngày và giờ, đồng thời nhờ có tính năng hỗ trợ Codable của Cloud Firestore, bạn có thể dễ dàng sử dụng các kiểu dữ liệu này.

Hãy xem tài liệu này, đại diện cho mẹ của tất cả ngôn ngữ lập trình, Ada, được phát minh vào năm 1843:

Lưu trữ ngày trong tài liệu Firestore

Một loại Swift để liên kết tài liệu này có thể có dạng như sau:

struct ProgrammingLanguage: Codable {
  @DocumentID var id: String?
  var name: String
  var year: Date
}

Chúng ta không thể kết thúc phần này về ngày và giờ mà không nói về @ServerTimestamp. Trình bao bọc thuộc tính này là một công cụ mạnh mẽ khi xử lý dấu thời gian trong ứng dụng.

Trong bất kỳ hệ thống phân tán nào, có khả năng đồng hồ trên các hệ thống riêng lẻ không hoàn toàn đồng bộ mọi lúc. Bạn có thể nghĩ rằng đây không phải là vấn đề lớn, nhưng hãy tưởng tượng tác động của một chiếc đồng hồ chạy không đồng bộ một chút đối với hệ thống giao dịch chứng khoán: ngay cả độ lệch một mili giây cũng có thể dẫn đến chênh lệch hàng triệu đô la khi thực hiện giao dịch.

Cloud Firestore xử lý các thuộc tính được đánh dấu bằng @ServerTimestamp như sau: nếu thuộc tính là nil khi bạn lưu trữ (ví dụ: sử dụng addDocument()), thì Cloud Firestore sẽ điền dấu thời gian hiện tại của máy chủ vào trường tại thời điểm ghi vào cơ sở dữ liệu. Nếu trường không phải là nil khi bạn gọi addDocument() hoặc updateData(), thì Cloud Firestore sẽ giữ nguyên giá trị thuộc tính. Bằng cách này, bạn có thể dễ dàng triển khai các trường như createdAt và lastUpdatedAt.

Điểm địa lý

Vị trí địa lý có mặt ở khắp mọi nơi trong ứng dụng của chúng ta. Nhiều tính năng thú vị có thể hoạt động bằng cách lưu trữ các tính năng đó. Ví dụ: bạn nên lưu trữ vị trí cho một việc cần làm để ứng dụng có thể nhắc bạn về việc đó khi bạn đến một điểm đến.

Cloud Firestore có một kiểu dữ liệu tích hợp sẵn là GeoPoint, có thể lưu trữ kinh độ và vĩ độ của bất kỳ vị trí nào. Để liên kết các vị trí từ/đến một tài liệu Cloud Firestore, chúng ta có thể sử dụng loại GeoPoint:

struct Office: Codable {
  @DocumentID var id: String?
  var name: String
  var location: GeoPoint
}

Loại tương ứng trong Swift là CLLocationCoordinate2D và chúng ta có thể ánh xạ giữa hai loại đó bằng thao tác sau:

CLLocationCoordinate2D(latitude: office.location.latitude,
                      longitude: office.location.longitude)

Để tìm hiểu thêm về cách truy vấn tài liệu theo vị trí thực tế, hãy xem hướng dẫn về giải pháp này.

Enum

Enum có lẽ là một trong những tính năng ngôn ngữ bị đánh giá thấp nhất trong Swift; có nhiều điều về enum hơn là những gì bạn thấy. Một trường hợp sử dụng phổ biến cho enum là để lập mô hình các trạng thái riêng biệt của một đối tượng. Ví dụ: chúng ta có thể viết một ứng dụng để quản lý các bài viết. Để theo dõi trạng thái của một bài viết, chúng ta có thể sử dụng enum Status:

enum Status: String, Codable {
  case draft
  case inReview
  case approved
  case published
}

Cloud Firestore không hỗ trợ enum theo cách gốc (tức là không thể thực thi tập hợp giá trị), nhưng chúng ta vẫn có thể tận dụng thực tế là enum có thể được nhập và chọn một loại có thể lập trình. Trong ví dụ này, chúng ta đã chọn String, nghĩa là tất cả giá trị enum sẽ được liên kết đến/từ chuỗi khi được lưu trữ trong tài liệu Cloud Firestore.

Và vì Swift hỗ trợ các giá trị thô tuỳ chỉnh, nên chúng ta thậm chí có thể tuỳ chỉnh giá trị nào tham chiếu đến trường hợp enum nào. Ví dụ: nếu quyết định lưu trữ trường hợp Status.inReview là "đang xem xét", chúng ta chỉ cần cập nhật enum ở trên như sau:

enum Status: String, Codable {
  case draft
  case inReview = "in review"
  case approved
  case published
}

Tuỳ chỉnh mối liên kết

Đôi khi, tên thuộc tính của tài liệu Cloud Firestore mà chúng ta muốn liên kết không khớp với tên của các thuộc tính trong mô hình dữ liệu trong Swift. Ví dụ: một trong những đồng nghiệp của chúng ta có thể là nhà phát triển Python và quyết định chọn kiểu viết con rắn (snake_case) cho tất cả tên thuộc tính của họ.

Đừng lo: Codable sẽ giúp chúng ta!

Đối với những trường hợp như vậy, chúng ta có thể sử dụng CodingKeys. Đây là một enum mà chúng ta có thể thêm vào cấu trúc có thể lập trình để chỉ định cách ánh xạ một số thuộc tính nhất định.

Hãy xem xét tài liệu sau:

Tài liệu Firestore có tên thuộc tính theo kiểu viết con rắn (viết thường chữ cái đầu tiên và thay dấu cách bằng dấu gạch dưới)

Để liên kết tài liệu này với một cấu trúc có thuộc tính tên thuộc loại String, chúng ta cần thêm một enum CodingKeys vào cấu trúc ProgrammingLanguage và chỉ định tên của thuộc tính trong tài liệu:

struct ProgrammingLanguage: Codable {
  @DocumentID var id: String?
  var name: String
  var year: Date

  enum CodingKeys: String, CodingKey {
    case id
    case name = "language_name"
    case year
  }
}

Theo mặc định, Codable API sẽ sử dụng tên thuộc tính của các loại Swift để xác định tên thuộc tính trên tài liệu Cloud Firestore mà chúng ta đang cố gắng liên kết. Vì vậy, miễn là tên thuộc tính khớp, bạn không cần thêm CodingKeys vào các loại có thể lập trình. Tuy nhiên, khi sử dụng CodingKeys cho một loại cụ thể, chúng ta cần thêm tất cả tên thuộc tính mà chúng ta muốn liên kết.

Trong đoạn mã trên, chúng ta đã xác định một thuộc tính id mà chúng ta có thể muốn sử dụng làm giá trị nhận dạng trong khung hiển thị List của SwiftUI. Nếu chúng ta không chỉ định thuộc tính này trong CodingKeys, thì thuộc tính này sẽ không được liên kết khi tìm nạp dữ liệu và do đó sẽ trở thành nil. Thao tác này sẽ khiến chế độ xem List được lấp đầy bằng tài liệu đầu tiên.

Mọi thuộc tính không được liệt kê dưới dạng một trường hợp trên enum CodingKeys tương ứng sẽ bị bỏ qua trong quá trình liên kết. Điều này thực sự có thể thuận tiện nếu chúng ta muốn loại trừ một số thuộc tính khỏi việc được ánh xạ.

Ví dụ: nếu muốn loại trừ thuộc tính reasonWhyILoveThis khỏi việc liên kết, chúng ta chỉ cần xoá thuộc tính đó khỏi enum CodingKeys:

struct ProgrammingLanguage: Identifiable, Codable {
  @DocumentID var id: String?
  var name: String
  var year: Date
  var reasonWhyILoveThis: String = ""

  enum CodingKeys: String, CodingKey {
    case id
    case name = "language_name"
    case year
  }
}

Đôi khi, chúng ta có thể muốn ghi một thuộc tính trống vào tài liệu Cloud Firestore. Swift có khái niệm về các giá trị không bắt buộc để biểu thị việc không có giá trị và Cloud Firestore cũng hỗ trợ các giá trị null. Tuy nhiên, hành vi mặc định để mã hoá các giá trị không bắt buộc có giá trị nil là chỉ bỏ qua các giá trị đó. @ExplicitNull cho phép chúng ta kiểm soát cách xử lý các giá trị không bắt buộc trong Swift khi mã hoá: bằng cách gắn cờ một thuộc tính không bắt buộc là @ExplicitNull, chúng ta có thể yêu cầu Cloud Firestore ghi thuộc tính này vào tài liệu có giá trị rỗng nếu thuộc tính này chứa giá trị nil.

Sử dụng bộ mã hoá và bộ giải mã tuỳ chỉnh để liên kết màu

Chủ đề cuối cùng trong nội dung về việc liên kết dữ liệu với Codable là giới thiệu về bộ mã hoá và bộ giải mã tuỳ chỉnh. Phần này không đề cập đến kiểu dữ liệu Cloud Firestore gốc, nhưng bộ mã hoá và bộ giải mã tuỳ chỉnh rất hữu ích trong các ứng dụng Cloud Firestore của bạn.

"Làm cách nào để liên kết màu sắc" là một trong những câu hỏi thường gặp nhất của nhà phát triển, không chỉ đối với Cloud Firestore mà còn đối với việc liên kết giữa Swift và JSON. Có rất nhiều giải pháp, nhưng hầu hết đều tập trung vào JSON và hầu hết đều liên kết màu sắc dưới dạng từ điển lồng nhau bao gồm các thành phần RGB.

Có vẻ như cần có một giải pháp tốt hơn và đơn giản hơn. Tại sao chúng ta không sử dụng màu web (hay cụ thể hơn là ký hiệu mã màu hex CSS) — chúng rất dễ sử dụng (về cơ bản chỉ là một chuỗi) và thậm chí còn hỗ trợ độ trong suốt!

Để có thể liên kết Color Swift với giá trị thập lục phân, chúng ta cần tạo một tiện ích Swift để thêm Codable vào Color.

extension Color {

 init(hex: String) {
    let rgba = hex.toRGBA()

    self.init(.sRGB,
              red: Double(rgba.r),
              green: Double(rgba.g),
              blue: Double(rgba.b),
              opacity: Double(rgba.alpha))
    }

    //... (code for translating between hex and RGBA omitted for brevity)

}

extension Color: Codable {

  public init(from decoder: Decoder) throws {
    let container = try decoder.singleValueContainer()
    let hex = try container.decode(String.self)

    self.init(hex: hex)
  }

  public func encode(to encoder: Encoder) throws {
    var container = encoder.singleValueContainer()
    try container.encode(toHex)
  }

}

Bằng cách sử dụng decoder.singleValueContainer(), chúng ta có thể giải mã String thành giá trị tương đương Color mà không cần lồng các thành phần RGBA. Ngoài ra, bạn có thể sử dụng các giá trị này trong giao diện người dùng web của ứng dụng mà không cần phải chuyển đổi trước!

Nhờ đó, chúng ta có thể cập nhật mã để liên kết thẻ, giúp dễ dàng xử lý màu thẻ trực tiếp thay vì phải liên kết thẻ theo cách thủ công trong mã giao diện người dùng của ứng dụng:

struct Tag: Codable, Hashable {
  var title: String
  var color: Color
}

struct BookWithTags: Codable {
  @DocumentID var id: String?
  var title: String
  var numberOfPages: Int
  var author: String
  var tags: [Tag]
}

Xử lý lỗi

Trong các đoạn mã trên, chúng tôi cố ý giữ việc xử lý lỗi ở mức tối thiểu, nhưng trong ứng dụng chính thức, bạn cần đảm bảo xử lý mọi lỗi một cách linh hoạt.

Dưới đây là đoạn mã cho thấy cách xử lý mọi tình huống lỗi mà bạn có thể gặp phải:

class MappingSimpleTypesViewModel: ObservableObject {
  @Published var book: Book = .empty
  @Published var errorMessage: String?

  private var db = Firestore.firestore()

  func fetchAndMap() {
    fetchBook(documentId: "hitchhiker")
  }

  func fetchAndMapNonExisting() {
    fetchBook(documentId: "does-not-exist")
  }

  func fetchAndTryMappingInvalidData() {
    fetchBook(documentId: "invalid-data")
  }

  private func fetchBook(documentId: String) {
    let docRef = db.collection("books").document(documentId)

    docRef.getDocument(as: Book.self) { result in
      switch result {
      case .success(let book):
        // A Book value was successfully initialized from the DocumentSnapshot.
        self.book = book
        self.errorMessage = nil
      case .failure(let error):
        // A Book value could not be initialized from the DocumentSnapshot.
        switch error {
        case DecodingError.typeMismatch(_, let context):
          self.errorMessage = "\(error.localizedDescription): \(context.debugDescription)"
        case DecodingError.valueNotFound(_, let context):
          self.errorMessage = "\(error.localizedDescription): \(context.debugDescription)"
        case DecodingError.keyNotFound(_, let context):
          self.errorMessage = "\(error.localizedDescription): \(context.debugDescription)"
        case DecodingError.dataCorrupted(let key):
          self.errorMessage = "\(error.localizedDescription): \(key)"
        default:
          self.errorMessage = "Error decoding document: \(error.localizedDescription)"
        }
      }
    }
  }
}

Xử lý lỗi trong thông tin cập nhật trực tiếp

Đoạn mã trước minh hoạ cách xử lý lỗi khi tìm nạp một tài liệu. Ngoài việc tìm nạp dữ liệu một lần, Cloud Firestore cũng hỗ trợ cung cấp thông tin cập nhật cho ứng dụng của bạn khi chúng xảy ra, bằng cách sử dụng trình nghe ảnh chụp nhanh: chúng ta có thể đăng ký trình nghe ảnh chụp nhanh trên một tập hợp (hoặc truy vấn) và Cloud Firestore sẽ gọi trình nghe của chúng ta bất cứ khi nào có thông tin cập nhật.

Dưới đây là đoạn mã cho thấy cách đăng ký trình nghe ảnh chụp nhanh, liên kết dữ liệu bằng Codable và xử lý mọi lỗi có thể xảy ra. Video này cũng hướng dẫn cách thêm một tài liệu mới vào bộ sưu tập. Như bạn sẽ thấy, chúng ta không cần tự cập nhật mảng cục bộ chứa các tài liệu được liên kết, vì việc này đã được mã trong trình nghe tổng quan nhanh xử lý.

class MappingColorsViewModel: ObservableObject {
  @Published var colorEntries = [ColorEntry]()
  @Published var newColor = ColorEntry.empty
  @Published var errorMessage: String?

  private var db = Firestore.firestore()
  private var listenerRegistration: ListenerRegistration?

  public func unsubscribe() {
    if listenerRegistration != nil {
      listenerRegistration?.remove()
      listenerRegistration = nil
    }
  }

  func subscribe() {
    if listenerRegistration == nil {
      listenerRegistration = db.collection("colors")
        .addSnapshotListener { [weak self] (querySnapshot, error) in
          guard let documents = querySnapshot?.documents else {
            self?.errorMessage = "No documents in 'colors' collection"
            return
          }

          self?.colorEntries = documents.compactMap { queryDocumentSnapshot in
            let result = Result { try queryDocumentSnapshot.data(as: ColorEntry.self) }

            switch result {
            case .success(let colorEntry):
              if let colorEntry = colorEntry {
                // A ColorEntry value was successfully initialized from the DocumentSnapshot.
                self?.errorMessage = nil
                return colorEntry
              }
              else {
                // A nil value was successfully initialized from the DocumentSnapshot,
                // or the DocumentSnapshot was nil.
                self?.errorMessage = "Document doesn't exist."
                return nil
              }
            case .failure(let error):
              // A ColorEntry value could not be initialized from the DocumentSnapshot.
              switch error {
              case DecodingError.typeMismatch(_, let context):
                self?.errorMessage = "\(error.localizedDescription): \(context.debugDescription)"
              case DecodingError.valueNotFound(_, let context):
                self?.errorMessage = "\(error.localizedDescription): \(context.debugDescription)"
              case DecodingError.keyNotFound(_, let context):
                self?.errorMessage = "\(error.localizedDescription): \(context.debugDescription)"
              case DecodingError.dataCorrupted(let key):
                self?.errorMessage = "\(error.localizedDescription): \(key)"
              default:
                self?.errorMessage = "Error decoding document: \(error.localizedDescription)"
              }
              return nil
            }
          }
        }
    }
  }

  func addColorEntry() {
    let collectionRef = db.collection("colors")
    do {
      let newDocReference = try collectionRef.addDocument(from: newColor)
      print("ColorEntry stored with new document reference: \(newDocReference)")
    }
    catch {
      print(error)
    }
  }
}

Tất cả đoạn mã được sử dụng trong bài đăng này đều thuộc một ứng dụng mẫu mà bạn có thể tải xuống từ kho lưu trữ GitHub này.

Hãy tiếp tục và sử dụng Codable!

API Codable của Swift cung cấp một cách mạnh mẽ và linh hoạt để liên kết dữ liệu từ các định dạng được chuyển đổi tuần tự đến và từ mô hình dữ liệu của ứng dụng. Trong hướng dẫn này, bạn đã thấy việc sử dụng trong các ứng dụng dùng Cloud Firestore làm kho dữ liệu dễ dàng như thế nào.

Bắt đầu từ một ví dụ cơ bản với các kiểu dữ liệu đơn giản, chúng tôi dần tăng độ phức tạp của mô hình dữ liệu, đồng thời có thể dựa vào việc triển khai Codable và Firebase để thực hiện việc liên kết cho chúng tôi.

Để biết thêm thông tin chi tiết về Codable, bạn nên tham khảo các tài nguyên sau:

Mặc dù chúng tôi đã cố gắng hết sức để biên soạn một hướng dẫn toàn diện về việc liên kết tài liệu Cloud Firestore, nhưng hướng dẫn này chưa đầy đủ và bạn có thể đang sử dụng các chiến lược khác để liên kết các loại tài liệu của mình. Hãy sử dụng nút Gửi ý kiến phản hồi bên dưới để cho chúng tôi biết những chiến lược bạn sử dụng để liên kết các loại dữ liệu Cloud Firestore khác hoặc biểu thị dữ liệu trong Swift.

Thực sự không có lý do gì để không sử dụng tính năng hỗ trợ Codable của Cloud Firestore.