firestore-serde

firestore-serde 是 Firestore Value 和 Document 的序列化/反序列化实现。

这允许你在 Firestore 数据库中存储任意的 Rust 值，但这个包不处理与 Firestore 服务的任何通信。相反，它旨在与其他包一起使用

• tonic 用于通过 gRPC 连接到 Firebase。
• googapis 用于 Firebase gRPC 消息定义，从 官方 API 定义 使用 prost 派生。
• google-authz 用于身份验证/凭证发现。

预备知识

Firestore 是由 Google 提供的一个基于云的、专有文档数据库（不要与 Firebase 或 Cloud Datastore 混淆，它们也是由 Google 提供的专有文档数据库）。

Google 没有提供官方的 Rust 绑定用于 Google Cloud Platform，但他们提供了 REST 和 gRPC API 的 API 规范。因此，出现了许多 Rust 项目，从这些规范生成 Rust 绑定

• Byron/google-apis-rs 生成 REST API 的绑定，在 hyper HTTP 库之上实现。
• mechiru/googapis 生成 gRPC API 的绑定，在 tonic gRPC 库之上实现。

REST API 调用和 gRPC API 调用之间存在一对一的映射。不幸的是，在 Firestore 的 REST API 规范中存在一个 已知问题，它破坏了查询，因此我建议不要使用 REST API。因此，这个包只支持 gRPC API。如果你确实想使用 REST API，请使用 firestore-db-and-auth-rs 包而不是这个包。

Firestore 中数据检索的单位是 Document，它是一个字符串字段到 Value 的映射。`Value` 本身是一种丰富的类型，可以表示由其他值组成的数组和映射。因此，我们可以以直观的方式将许多 Rust 类型表示为 `Value` 和 `Document`。此软件包提供了一个 serde 序列化和反序列化器来实现这一点。

用法

此软件包提供四个主要功能

// Conversions between Rust types and Value gRPC type.

pub fn to_grpc_value<T>(value: &T)
    -> Result<Value, SerializationError>
    where T: Serialize;

pub fn from_grpc_value<T>(value: &Value)
    -> Result<T, DeserializationError>
    where T: DeserializeOwned;

// Conversions between Rust types and Document gRPC type.

pub fn to_document<T>(value: &T)
    -> Result<Document, SerializationError>
    where T: Serialize;

pub fn from_document<T>(document: Document)
    -> Result<T, DeserializationError>
    where T: DeserializeOwned;

请注意，`from_document` 会获取其参数的所有权，因此如果您需要在转换后保留原始 `Document`，您必须对其进行克隆。

时间戳

chrono 软件包支持可序列化的时间戳，通过将时间戳转换为字符串或数字。如果不进行干预，`firestore-serde` 不区分这些与其他数字或字符串，因此它们分别转换为 `ValueType::IntegerValue` 和 `ValueType::StringValue`。

如果您总是将值反序列化为 Rust，这很好，但如果您想以其他方式访问数据（例如，基于 Web 的数据控制台），通常有用将时间数据存储在 Firestore 的 `ValueType::TimestampValue` 中。为此，请将 `firestore-serde-timestamp` 作为依赖项添加，并告诉 Serde 使用它进行编码

use serde::{Serialize, Deserialize};
use chrono::{DateTime, Utc};

#[derive(Serialize, Deserialize)]
struct MyStruct {
    #[serde(with="firestore_serde_timestamp::timestamp")]
    some_timestamp: DateTime<Utc>,
}

API 版本

目前有两个版本的 gRPC API，分别是 `google.firestore.v1.*` 和 `google.firestore.v1beta1.*`。每个版本都由一个不同的命名空间表示，该命名空间与其他命名空间隔离，因此即使是两个版本都共同使用的类型（例如 `Document` 和 `Value`）也由不同的协议缓冲区表示。

`firestore-serde` 默认使用 `v1` 命名空间，但您可以通过功能标志来更改它。在您的 `Cargo.toml` 中，指定依赖项如下

[dependencies]
firestore-serde = {version = "0.1.0", default-features=false, features=["google-firestore-v1beta1"]}

您必须禁用 `default-features`，因为如果同时启用了 `google-firestore-v1` 和 `google-firestore-v1beta1`，`firestore-serde` 将拒绝编译。