let mut transaction = db.begin_transaction().await?;

db.fluent()
  .update()
  .fields(paths!(MyTestStructure::{
       some_string
     }))
  .in_col(TEST_COLLECTION_NAME)
  .document_id("test-0")
  .object( & MyTestStructure {
    some_id: format!("test-0"),
    some_string: "UpdatedTest".to_string(),
  })
  .add_to_transaction( & mut transaction) ?;

db.fluent()
  .delete()
  .from(TEST_COLLECTION_NAME)
  .document_id("test-5")
  .add_to_transaction( & mut transaction) ?;

transaction.commit().await?;

您还可以使用 run_transaction 执行自动以指数退避重试的事务。

    db.run_transaction( | db, transaction| {
      Box::pin(async move {
      let mut test_structure: MyTestStructure = db
        .fluent()
        .select()
        .by_id_in(TEST_COLLECTION_NAME)
        .obj()
        .one(TEST_DOCUMENT_ID)
        .await?
        .expect("Missing document");

      // Perform some kind of operation that depends on the state of the document
      test_structure.test_string += "a";

      db.fluent()
        .update()
        .fields(paths!(MyTestStructure::{
          test_string
         }))
        .in_col(TEST_COLLECTION_NAME)
        .document_id(TEST_DOCUMENT_ID)
        .object(&test_structure)
        .add_to_transaction(transaction) ?;

        Ok(())
      })
})
  .await?;

请参阅可用的完整示例 此处。

请注意，Firestore不支持在事务中创建文档（自动生成文档ID），因此您需要使用update()来隐式创建文档并指定您自己的ID。

将Firestore文档元数据作为结构字段读取

Firestore为每个创建的文档提供额外的生成字段

• _firestore_id：生成的文档ID（当客户端未指定时）；
• _firestore_created：文档创建的时间；
• _firestore_updated：文档最后更改的时间；

为了能够读取它们，库将它们作为系统字段提供给Serde反序列化器，具有保留名称，因此您可以在您的结构中指定它们

#[derive(Debug, Clone, Deserialize, Serialize)]
struct MyTestStructure {
    #[serde(alias = "_firestore_id")]
    id: Option<String>,
    #[serde(alias = "_firestore_created")]
    created_at: Option<DateTime<Utc>>,
    #[serde(alias = "_firestore_updated")]
    updated_at: Option<DateTime<Utc>>,
    some_string: String,
    one_more_string: String,
    some_num: u64,
}

完整示例请见此处。

在动态/文档级别上工作

有时静态结构可能会限制您处理动态数据，因此可以使用Fluent API来处理文档，而无需引入任何结构。

let object_returned = db
.fluent()
.insert()
.into(TEST_COLLECTION_NAME)
.document_id("test-1")
.document(FirestoreDb::serialize_map_to_doc("",
    [
      ("some_id", "test-id".into()),
      ("some_string", "test-value".into()),
      ("some_num", 42.into()),
      (
      "embedded_obj",
        FirestoreValue::from_map([
          ("inner_some_id", "inner-id-value".into()),
          ("inner_some_string", "inner-some-value".into()),
        ]),
      ),
      ("created_at", FirestoreTimestamp(Utc::now()).into()),
    ])?
)
.execute()
.await?;

完整示例请见此处。

文档转换

库支持事务和批量写入中的服务器端文档转换

// Only transformation
db.fluent()
.update()
.in_col(TEST_COLLECTION_NAME)
.document_id("test-4")
.transforms(|t| { // Transformations
    t.fields([
      t.field(path!(MyTestStructure::some_num)).increment(10),
      t.field(path!(MyTestStructure::some_array)).append_missing_elements([4, 5]),
      t.field(path!(MyTestStructure::some_array)).remove_all_from_array([3]),
    ])
})
.only_transform()
.add_to_transaction( & mut transaction) ?; // or add_to_batch

// Update and transform (in this order and atomically):
db.fluent()
.update()
.in_col(TEST_COLLECTION_NAME)
.document_id("test-5")
.object(&my_obj) // Updating the objects with the fields here
.transforms(|t| { // Transformations after the update
    t.fields([
      t.field(path!(MyTestStructure::some_num)).increment(10),
    ])
})
.add_to_transaction(&mut transaction) ?; // or add_to_batch

在Firestore上监听文档更改

为了帮助处理异步事件监听器，库支持高级API，以在单独的线程上监听Firestore的事件

监听器实现需要提供用于存储指定目标的最后接收令牌的存储，以便能够从最后处理的令牌恢复监听更改，并避免接收所有之前的变化。

库提供了基本的令牌存储实现，但如果需要，您可以实现自己的更复杂的存储

• FirestoreTempFilesListenStateStorage - 将令牌作为本地文件系统上的临时文件存储；
• FirestoreMemListenStateStorage - 由HashMap支持的内存存储（使用此实现，如果您重新启动应用程序，您将再次收到所有通知）；

let mut listener = db.create_listener(
    FirestoreTempFilesListenStateStorage::new() // or FirestoreMemListenStateStorage or your own implementation 
).await?;

// Adding query listener
db.fluent()
.select()
.from(TEST_COLLECTION_NAME)
.listen()
.add_target(TEST_TARGET_ID_BY_QUERY, &mut listener) ?;

// Adding docs listener by IDs
db.fluent()
.select()
.by_id_in(TEST_COLLECTION_NAME)
.batch_listen([doc_id1, doc_id2])
.add_target(TEST_TARGET_ID_BY_DOC_IDS, &mut listener) ?;

listener
.start( | event| async move {
    match event {
        FirestoreListenEvent::DocumentChange( ref doc_change) => {
            println ! ("Doc changed: {:?}", doc_change);
            
            if let Some(doc) = & doc_change.document {
              let obj: MyTestStructure =
              FirestoreDb::deserialize_doc_to::<MyTestStructure > (doc)
              .expect("Deserialized object");
              println ! ("As object: {:?}", obj);
            }
        }
        _ => {
          println ! ("Received a listen response event to handle: {:?}", event);
        }
    }

  Ok(())
})
.await?;

// Wait some events like Ctrl-C, signals, etc
// <put-your-implementation-for-wait-here>

// and then shutdown
listener.shutdown().await?;

在示例目录中查看完整示例。

显式空值序列化

默认情况下，所有Option<>都序列化为空字段，这在许多情况下很方便。然而，有时您需要显式空值。

为此，为serde(with)实现了附加属性

• 对于任何类型

#[serde(default)]
#[serde(with = "firestore::serialize_as_null")]
test_null: Option<String>,

• 对于Firestore时间戳属性

#[serde(default)]
#[serde(with = "firestore::serialize_as_null_timestamp")]
test_null: Option<DateTime<Utc> >,

选择聚合函数

库支持查询的聚合函数

db.fluent()
  .select()
  .from(TEST_COLLECTION_NAME)
  .aggregate(|a| a.fields([a.field(path!(MyAggTestStructure::counter)).count()]))
  .obj()
  .query()
  .await?;

更新/删除预条件

库支持预条件

  .precondition(FirestoreWritePrecondition::Exists(true))

解释查询

库支持查询解释

db.fluent()
  .select()
  .from(TEST_COLLECTION_NAME)
  .explain()
  // or use explain_with_options if you want to provide additional options like analyze which run query to gather additional statistics 
  // .explain_with_options(FirestoreExplainOptions::new().with_analyze(true))
  .stream_query_with_metadata()
  .await?;

Google身份验证

在以下位置查找凭据，首选找到的第一个位置

• 一个路径由GOOGLE_APPLICATION_CREDENTIALS环境变量指定的JSON文件。
• 在gcloud命令行工具已知的位置的JSON文件，使用gcloud auth application-default login。
• 在Google Compute Engine上，它从元数据服务器获取凭据。

本地开发

不要混淆gcloud auth login与gcloud auth application-default login用于本地开发，因为第一个授权仅授权gcloud工具访问云平台。

后者通过Web流程获取用户访问凭证，并将它们放在应用程序默认凭证（ADC）的已知位置。此命令在您正在开发通常使用服务账户但需要在本地开发环境中运行代码的代码时很有用，在这种环境中提供用户凭证更容易。因此，为了在本地开发中使用，您需要使用 gcloud auth application-default login。

与Docker镜像一起工作

在设计Dockerfile时，请确保您已安装根CA证书或使用已包含它们的基镜像。如果没有安装证书，您通常会观察到以下错误：

SystemError(FirestoreSystemError { public: FirestoreErrorPublicGenericDetails { code: "GrpcStatus(tonic::transport::Error(Transport, hyper::Error(Connect, Custom { kind: InvalidData, error: InvalidCertificateData(\"invalid peer certificate: UnknownIssuer\") })))" }, message: "GCloud system error: Tonic/gRPC error: transport error" })

例如，对于基于Debian的镜像，这通常可以使用此包修复：

RUN apt-get install -y ca-certificates

此外，我建议考虑使用Google Distroless镜像，因为它们是安全的，已包含根CA证书，并且已针对大小优化。

Firestore模拟器

要使用Google Firestore模拟器，您可以使用环境变量

export FIRESTORE_EMULATOR_HOST="localhost:8080"

或者使用以下方式指定它：FirestoreDb::with_options()

缓存

该库支持集合和文档的缓存。缓存是利用Firestore监听器在文档更改时更新缓存，这意味着更新将自动跨分布式实例传播。

这有助于避免多次从Firestore读取并付费相同的文档。特别是对于一些数据，如字典、配置和其他不经常更改的信息。实际上，这可以真正帮助降低应用程序的成本和延迟。

缓存在文档级别上工作。缓存将用于以下操作：

• 通过ID读取文档（获取和批量获取）；
• 列出集合中的所有文档；
• 对集合中的文档查询的部分支持
  • 过滤；
  • 排序；
  • 分页/游标；

（未来可能会扩展其他操作的缓存）。

该库提供了两种缓存实现

• 内存缓存，使用moka缓存库实现；
• 持久缓存，使用redb和protobuf实现；

缓存是可选的，您需要在需要时使用cargo功能启用它

• caching-memory用于内存缓存；
• caching-persistent用于持久/磁盘后缓存的缓存；

加载模式

缓存支持不同的初始化/加载模式

• PreloadNone：不预加载任何内容，只需在工作时填充缓存；
• PreloadAllDocs：将集合中的所有文档预加载到缓存中；
• PreloadAllIfEmpty：仅在缓存为空时将集合中的所有文档预加载到缓存中（这对于持久缓存很有用，对于内存缓存它和PreloadAllDocs相同）；

如何更新缓存

以下情况下将更新缓存：

• 当您通过缓存按ID读取文档但未在缓存中找到时，它将从Firestore加载并缓存；
• Firestore监听器在接收到有关文档更改的通知（外部或来自您的应用程序）时将更新缓存；
• 在启动时使用预加载；

使用方法

// Create an instance
let db = FirestoreDb::new( &config_env_var("PROJECT_ID") ? ).await?;

const TEST_COLLECTION_NAME: &'static str = "test-caching";

// Create a cache instance that also creates an internal Firestore listener
let mut cache = FirestoreCache::new(
"example-mem-cache".into(),
&db,
FirestoreMemoryCacheBackend::new(
  FirestoreCacheConfiguration::new().add_collection_config(
    &db,
    FirestoreCacheCollectionConfiguration::new(
      TEST_COLLECTION_NAME,
      FirestoreListenerTarget::new(1000),
      FirestoreCacheCollectionLoadMode::PreloadNone,
    )
  ),
)?,
  FirestoreMemListenStateStorage::new(),
)
.await?;

// Load and init cache
cache.load().await?; // Required even if you don't preload anything

// Read a document through the cache. If it is not found in the cache, it will be loaded from Firestore and cached.
let my_struct0: Option<MyTestStructure> = db.read_through_cache(&cache)
  .fluent()
  .select()
  .by_id_in(TEST_COLLECTION_NAME)
  .obj()
  .one("test-1")
  .await?;

// Read a document only from the cache. If it is not found in the cache, it will return None.
let my_struct0: Option<MyTestStructure> = db.read_cached_only(&cache)
  .fluent()
  .select()
  .by_id_in(TEST_COLLECTION_NAME)
  .obj()
  .one("test-1")
  .await?;

完整的示例在此处可用：这里 和 这里。

TLS相关功能

Cargo为依赖项提供了不同TLS功能的支持

• tls-roots：默认功能以支持本机TLS根
• tls-webpki-roots：切换到webpki crate根的功能

如何测试此库

测试目录中有集成测试，每次提交都会运行一次，针对为测试目的分配的真实Firestore实例。请注意，不要引入大量的文档读取/更新以及与其他测试的集合隔离。

许可证

Apache软件许可证（ASL）

作者

Abdulla Abdurakhmanov