状态管理 on Dapr 文档库

状态管理概述

Mon, 01 Jan 0001 00:00:00 +0000

您的应用程序可以利用Dapr的状态管理API在支持的状态存储中保存、读取和查询键/值对。通过状态存储组件，您可以构建有状态且长时间运行的应用程序，例如购物车或游戏的会话状态。如下图所示：

使用HTTP POST来保存或查询键/值对。
使用HTTP GET来读取特定键并返回其值。

以下视频和演示概述了Dapr状态管理的工作原理。

功能

通过状态管理API模块，您的应用程序可以利用一些通常复杂且容易出错的功能，包括：

设置并发控制和数据一致性的选项。
执行批量更新操作CRUD，包括多个事务操作。
查询和过滤键/值数据。

以下是状态管理API的一些功能：

可插拔的状态存储

Dapr的数据存储被设计为组件，可以在不更改服务代码的情况下进行替换。查看支持的状态存储以获取更多信息。

可配置的状态存储行为

使用Dapr，您可以在状态操作请求中附加元数据，描述您期望请求如何被处理。您可以附加：

并发性要求
一致性要求

默认情况下，您的应用程序应假设数据存储是最终一致的，并使用最后写入胜出并发模式。

并非所有存储都是平等的。为了确保您的应用程序的可移植性，您可以查询存储的元数据能力，并使您的代码适应不同的存储能力。

并发

Dapr支持使用ETags的乐观并发控制（OCC）。当请求状态值时，Dapr总是将ETag属性附加到返回的状态中。当用户代码：

更新状态时，期望通过请求体附加ETag。
删除状态时，期望通过If-Match头附加ETag。

当提供的ETag与状态存储中的ETag匹配时，写入操作成功。

为什么Dapr选择乐观并发控制（OCC）

在许多应用程序中，数据更新冲突很少见，因为客户端通常根据业务上下文分区以操作不同的数据。然而，如果您的应用程序选择使用ETags，不匹配的ETags可能导致请求被拒绝。建议您在代码中使用重试策略，以在使用ETags时补偿冲突。

如果您的应用程序在写入请求中省略ETags，Dapr在处理请求时会跳过ETag检查。这使得最后写入胜出模式成为可能，与使用ETags的首次写入胜出模式相比。

关于ETags的注意事项

对于不原生支持ETags的存储，相应的Dapr状态存储实现应模拟ETags，并在处理状态时遵循Dapr状态管理API规范。由于Dapr状态存储实现技术上是底层数据存储的客户端，模拟应该是直接的，使用存储提供的并发控制机制。

阅读API参考以了解如何设置并发选项。

一致性

Dapr支持强一致性和最终一致性，最终一致性是默认行为。

强一致性：Dapr在确认写入请求之前等待所有副本（或指定的法定人数）确认。
最终一致性：Dapr在底层数据存储接受写入请求后立即返回，即使这只是一个副本。

阅读API参考以了解如何设置一致性选项。

设置内容类型

状态存储组件可能会根据内容类型不同地维护和操作数据。Dapr支持在状态管理API中作为请求元数据的一部分传递内容类型。

设置内容类型是_可选的_，组件决定是否使用它。Dapr仅提供将此信息传递给组件的手段。

使用HTTP API：通过URL查询参数metadata.contentType设置内容类型。例如，http://localhost:3500/v1.0/state/store?metadata.contentType=application/json。
使用gRPC API：通过在请求元数据中添加键/值对"contentType" : <content type>来设置内容类型。

多重操作

Dapr支持两种类型的多读或多写操作：批量或事务性。阅读API参考以了解如何使用批量和多选项。

批量读取操作

您可以将多个读取请求分组为批量（或批次）操作。在批量操作中，Dapr将读取请求作为单独的请求提交到底层数据存储，并将它们作为单个结果返回。

事务性操作

您可以将写入、更新和删除操作分组为一个请求，然后作为一个原子事务处理。请求将作为一组事务性操作成功或失败。

actor状态

事务性状态存储可用于存储actor状态。要指定用于actor的状态存储，请在状态存储组件的元数据部分中将属性actorStateStore的值指定为true。actor状态以特定方案存储在事务性状态存储中，允许进行一致的查询。所有actor只能使用一个状态存储组件作为状态存储。阅读state API参考和actors API参考以了解有关actor状态存储的更多信息。

actor状态的生存时间（TTL）

在保存actor状态时，您应始终设置TTL元数据字段（ttlInSeconds）或在您选择的SDK中使用等效的API调用，以确保状态最终被移除。阅读actors概述以获取更多信息。

状态加密

Dapr支持应用程序状态的自动客户端加密，并支持密钥轮换。这在所有Dapr状态存储上都支持。有关更多信息，请阅读如何：加密应用程序状态主题。

操作指南：保存和获取状态

Mon, 01 Jan 0001 00:00:00 +0000

状态管理是新应用程序、遗留应用程序、单体应用程序或微服务应用程序的常见需求之一。处理和测试不同的数据库库，以及处理重试和故障，可能既困难又耗时。

在本指南中，您将学习如何使用键/值状态API来保存、获取和删除应用程序的状态。

下面的代码示例描述了一个处理订单的应用程序，该应用程序使用Dapr sidecar。订单处理服务通过Dapr将状态存储在Redis状态存储中。

设置状态存储

状态存储组件是Dapr用于与数据库通信的资源。

在本指南中，我们将使用Redis状态存储，但您也可以选择支持列表中的其他状态存储。

当您在selfhost模式下运行dapr init时，Dapr会在您的本地机器上创建一个默认的Redis statestore.yaml并运行一个Redis状态存储，位置如下：

在Windows上，位于%UserProfile%\.dapr\components\statestore.yaml
在Linux/MacOS上，位于~/.dapr/components/statestore.yaml

通过使用statestore.yaml组件，您可以在不更改应用程序代码的情况下轻松更换底层组件。

要将其部署到Kubernetes集群中，请在下面的YAML中填写您的状态存储组件的metadata连接详细信息，保存为statestore.yaml，然后运行kubectl apply -f statestore.yaml。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: statestore
spec:
 type: state.redis
 version: v1
 metadata:
 - name: redisHost
 value: localhost:6379
 - name: redisPassword
 value: ""

请参阅如何在Kubernetes上设置不同的状态存储以获取更多信息。

操作指南：查询状态

Mon, 01 Jan 0001 00:00:00 +0000

alpha

状态查询API目前处于alpha阶段。

通过状态查询API，您可以从状态存储组件中检索、过滤和排序键/值数据。查询API并不是完整查询语言的替代品。

尽管状态存储是键/值存储，value可能是一个包含自身层次结构、键和值的JSON文档。查询API允许您使用这些键/值来检索相应的文档。

查询状态

您可以通过HTTP POST/PUT或gRPC提交查询请求。请求的主体是一个包含以下三个部分的JSON对象：

filter
sort
page

`filter`

filter用于指定查询条件，结构类似于树形，每个节点表示一个操作，可能是单一或多个操作数。

支持以下操作：

操作符	操作数	描述
`EQ`	key:value	key 等于 value
`NEQ`	key:value	key 不等于 value
`GT`	key:value	key 大于 value
`GTE`	key:value	key 大于等于 value
`LT`	key:value	key 小于 value
`LTE`	key:value	key 小于等于 value
`IN`	key:[]value	key 等于 value[0] 或 value[1] 或 … 或 value[n]
`AND`	[]operation	operation[0] 且 operation[1] 且 … 且 operation[n]
`OR`	[]operation	operation[0] 或 operation[1] 或 … 或 operation[n]

操作数中的key类似于JSONPath表示法。键中的每个点表示嵌套的JSON结构。例如，考虑以下结构：

操作指南：构建有状态服务

Mon, 01 Jan 0001 00:00:00 +0000

在本文中，您将学习如何创建一个可以水平扩展的有状态服务，选择性使用并发和一致性模型。状态管理API可以帮助开发者简化状态协调、冲突解决和故障处理的复杂性。

设置状态存储

状态存储组件是Dapr用来与数据库通信的资源。在本指南中，我们将使用默认的Redis状态存储。

使用Dapr CLI

当您在本地模式下运行dapr init时，Dapr会创建一个默认的Redis statestore.yaml并在您的本地机器上运行一个Redis状态存储，位置如下：

在Windows上，位于%UserProfile%\.dapr\components\statestore.yaml
在Linux/MacOS上，位于~/.dapr/components/statestore.yaml

通过statestore.yaml组件，您可以轻松替换底层组件而无需更改应用程序代码。

查看支持的状态存储列表。

Kubernetes

查看如何在Kubernetes上设置不同的状态存储。

强一致性和最终一致性

在强一致性模式下，Dapr确保底层状态存储：

在数据写入所有副本后才返回响应。
在写入或删除状态之前从法定人数接收确认。

对于读取请求，Dapr确保在副本之间一致地返回最新的数据。默认情况下是最终一致性，除非在请求状态API时另有指定。

以下示例展示了如何使用强一致性保存、获取和删除状态。示例用Python编写，但适用于任何编程语言。

保存状态

import requests
import json

store_name = "redis-store" # 在状态存储组件yaml文件中指定的状态存储名称
dapr_state_url = "http://localhost:3500/v1.0/state/{}".format(store_name)
stateReq = '[{ "key": "k1", "value": "Some Data", "options": { "consistency": "strong" }}]'
response = requests.post(dapr_state_url, json=stateReq)

获取状态

import requests
import json

store_name = "redis-store" # 在状态存储组件yaml文件中指定的状态存储名称
dapr_state_url = "http://localhost:3500/v1.0/state/{}".format(store_name)
response = requests.get(dapr_state_url + "/key1", headers={"consistency":"strong"})
print(response.headers['ETag'])

删除状态

import requests
import json

store_name = "redis-store" # 在状态存储组件yaml文件中指定的状态存储名称
dapr_state_url = "http://localhost:3500/v1.0/state/{}".format(store_name)
response = requests.delete(dapr_state_url + "/key1", headers={"consistency":"strong"})

如果没有指定concurrency选项，默认是后写胜出并发模式。

先写胜出和后写胜出

Dapr允许开发者在使用数据存储时选择两种常见的并发模式：

先写胜出：在应用程序的多个实例同时写入同一个键的情况下很有用。
后写胜出：Dapr的默认模式。

Dapr使用版本号来确定特定键是否已更新。您可以：

在读取键的数据时保留版本号。
在更新（如写入和删除）时使用版本号。

如果自从检索版本号以来版本信息已更改，将抛出错误，要求您执行另一次读取以获取最新的版本信息和状态。

Dapr利用ETags来确定状态的版本号。ETags从状态请求中以ETag头返回。使用ETags，您的应用程序知道自上次检查以来资源已更新，因为在ETag不匹配时会出错。

以下示例展示了如何：

获取ETag。
使用ETag保存状态。
删除状态。

以下示例用Python编写，但适用于任何编程语言。

操作指南：启用事务性 Outbox 模式

Mon, 01 Jan 0001 00:00:00 +0000

事务性 Outbox 模式是一种广为人知的设计模式，用于发送应用程序状态变化的通知。它通过一个跨越数据库和消息代理的单一事务来传递通知。

开发人员在尝试自行实现此模式时会遇到许多技术难题，通常需要编写复杂且容易出错的中央协调管理器，这些管理器最多支持一种或两种数据库和消息代理的组合。

例如，您可以使用 Outbox 模式来：

向账户数据库写入新的用户记录。
发送账户成功创建的通知消息。

通过 Dapr 的 Outbox 支持，您可以在调用 Dapr 的事务 API时通知订阅者应用程序的状态何时被创建或更新。

下图概述了 Outbox 功能的工作原理：

服务 A 使用事务将状态保存/更新到状态存储。
在同一事务下将消息写入消息代理。当消息成功传递到消息代理时，事务完成，确保状态和消息一起被事务化。
消息代理将消息主题传递给任何订阅者 - 在此情况下为服务 B。

要求

Outbox 功能可以与 Dapr 支持的任何事务性状态存储一起使用。所有发布/订阅代理都支持 Outbox 功能。

了解更多关于您可以使用的事务方法。

注意

建议与竞争消费者模式（例如，Apache Kafka）一起使用的消息代理减少重复事件的可能性。

启用 Outbox 模式

要启用 Outbox 功能，请在状态存储组件上添加以下必需和可选字段：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: mysql-outbox
spec:
 type: state.mysql
 version: v1
 metadata:
 - name: connectionString
 value: "<CONNECTION STRING>"
 - name: outboxPublishPubsub # 必需
 value: "mypubsub"
 - name: outboxPublishTopic # 必需
 value: "newOrder"
 - name: outboxPubsub # 可选
 value: "myOutboxPubsub"
 - name: outboxDiscardWhenMissingState # 可选，默认为 false
 value: false

元数据字段

名称	必需	默认值	描述
outboxPublishPubsub	是	N/A	设置发布状态更改时传递通知的发布/订阅组件的名称
outboxPublishTopic	是	N/A	设置接收在配置了 `outboxPublishPubsub` 的发布/订阅上的状态更改的主题。消息体将是 `insert` 或 `update` 操作的状态事务项
outboxPubsub	否	`outboxPublishPubsub`	设置 Dapr 用于协调状态和发布/订阅事务的发布/订阅组件。如果未设置，则使用配置了 `outboxPublishPubsub` 的发布/订阅组件。如果您希望将用于发送通知状态更改的发布/订阅组件与用于协调事务的组件分开，这将很有用
outboxDiscardWhenMissingState	否	`false`	通过将 `outboxDiscardWhenMissingState` 设置为 `true`，如果 Dapr 无法在数据库中找到状态且不重试，则 Dapr 将丢弃事务。如果在 Dapr 能够传递消息之前，状态存储数据因任何原因被删除，并且您希望 Dapr 从发布/订阅中删除项目并停止重试获取状态，此设置可能会很有用

其他配置

在同一状态存储上组合 Outbox 和非 Outbox 消息

如果您希望使用相同的状态存储来发送 Outbox 和非 Outbox 消息，只需定义两个连接到相同状态存储的状态存储组件，其中一个具有 Outbox 功能，另一个没有。

操作指南：在应用程序之间共享状态

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 提供了多种在应用程序之间共享状态的方法。

不同的架构在共享状态时可能有不同的需求。在某些情况下，您可能会希望：

在特定应用程序中封装所有状态
让 Dapr 为您管理状态访问

在其他情况下，您可能需要两个应用程序在同一状态上进行操作，以便获取和保存相同的键。

为了实现状态共享，Dapr 支持以下键前缀策略：

键前缀	描述
`appid`	默认策略，允许您仅通过指定 `appid` 的应用程序管理状态。所有状态键将以 `appid` 为前缀，并限定于该应用程序。
`name`	使用状态存储组件的名称作为前缀。多个应用程序可以共享同一状态存储中的相同状态。
`namespace`	如果设置了命名空间，此策略会将 `appid` 键前缀替换为配置的命名空间，生成一个限定于该命名空间的键。这允许在不同命名空间中具有相同 `appid` 的应用程序重用相同的状态存储。如果未配置命名空间，则会回退到 `appid` 策略。有关 Dapr 中命名空间的更多信息，请参见操作指南：将组件限定到一个或多个应用程序
`none`	不使用任何前缀。多个应用程序可以在不同的状态存储中共享状态，而不受特定前缀的限制。

指定状态前缀策略

要指定前缀策略，请在状态组件上添加名为 keyPrefix 的元数据键：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: statestore
 namespace: production
spec:
 type: state.redis
 version: v1
 metadata:
 - name: keyPrefix
 value: <key-prefix-strategy>

示例

以下示例演示了使用每种支持的前缀策略进行状态检索的情况。

`appid`（默认）

在下面的示例中，具有应用程序 ID myApp 的 Dapr 应用程序正在将状态保存到名为 redis 的状态存储中：

操作指南：加密应用程序状态

Mon, 01 Jan 0001 00:00:00 +0000

对静态应用程序状态进行加密，以在企业工作负载或受监管环境中提供更强的安全性。Dapr 提供基于 AES 的自动客户端加密，采用 Galois/Counter Mode (GCM)，支持 128、192 和 256 位的密钥。

除了自动加密，Dapr 还支持主加密密钥和次加密密钥，使开发人员和运维团队更容易启用密钥轮换策略。此功能由所有 Dapr 状态存储支持。

加密密钥始终从 secret 中获取，不能在 metadata 部分中以明文形式提供。

启用自动加密

将以下 metadata 部分添加到任何 Dapr 支持的状态存储中：

metadata:
- name: primaryEncryptionKey
 secretKeyRef:
 name: mysecret
 key: mykey # key 是可选的。

例如，这是一个 Redis 加密状态存储的完整 YAML：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: statestore
spec:
 type: state.redis
 version: v1
 metadata:
 - name: redisHost
 value: localhost:6379
 - name: redisPassword
 value: ""
 - name: primaryEncryptionKey
 secretKeyRef:
 name: mysecret
 key: mykey

现在，您已配置了一个 Dapr 状态存储，以从名为 mysecret 的 secret 中获取加密密钥，其中包含名为 mykey 的实际加密密钥。

状态生存时间 (TTL)

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 允许为每个状态设置生存时间 (TTL)。这意味着应用程序可以为存储的每个状态指定一个生存时间，过期后将无法检索这些状态。

对于支持的状态存储，只需在发布消息时设置 ttlInSeconds 元数据。其他状态存储将忽略此值。对于某些状态存储，您可以为每个表或容器指定默认的过期时间。

原生状态 TTL 支持

当状态存储组件原生支持状态 TTL 时，Dapr 会直接传递 TTL 配置，而不添加额外的逻辑，从而保持行为的一致性。这在组件以不同方式处理过期状态时尤为有用。

如果未指定 TTL，将保留状态存储的默认行为。

显式持久化绕过全局定义的 TTL

对于允许为所有数据指定默认 TTL 的状态存储，持久化状态的方式包括：

通过 Dapr 组件设置全局 TTL 值，或
在 Dapr 之外创建状态存储并设置全局 TTL 值。

如果未指定特定的 TTL，数据将在全局 TTL 时间段后过期，这不是由 Dapr 直接控制的。

此外，所有状态存储还支持显式持久化数据的选项。这意味着您可以忽略默认的数据库策略（可能是在 Dapr 之外或通过 Dapr 组件设置的），以无限期保留特定的数据库记录。您可以通过将 ttlInSeconds 设置为 -1 来实现，这表示忽略任何设置的 TTL 值。

支持的组件

请参阅状态存储组件指南中的 TTL 列。

示例

您可以在状态存储请求的元数据中设置状态 TTL：

# 依赖

from dapr.clients import DaprClient

# 代码

DAPR_STORE_NAME = "statestore"

with DaprClient() as client:
 client.save_state(DAPR_STORE_NAME, "order_1", str(orderId), state_metadata={
 'ttlInSeconds': '120'
 })

要启动 Dapr sidecar 并运行上述示例应用程序，您可以运行类似以下的命令：

状态管理 on Dapr 文档库

状态管理概述

功能

可插拔的状态存储

可配置的状态存储行为

并发

为什么Dapr选择乐观并发控制（OCC）

关于ETags的注意事项

一致性

设置内容类型

多重操作

批量读取操作

事务性操作

actor状态

actor状态的生存时间（TTL）

状态加密

操作指南：保存和获取状态

设置状态存储

操作指南：查询状态

alpha

查询状态

filter

操作指南：构建有状态服务

设置状态存储

使用Dapr CLI

Kubernetes

强一致性和最终一致性

保存状态

获取状态

删除状态

先写胜出和后写胜出

操作指南：启用事务性 Outbox 模式

要求

注意

启用 Outbox 模式

元数据字段

其他配置

在同一状态存储上组合 Outbox 和非 Outbox 消息

操作指南：在应用程序之间共享状态

指定状态前缀策略

示例

appid（默认）

操作指南：加密应用程序状态

启用自动加密

状态生存时间 (TTL)

原生状态 TTL 支持

显式持久化绕过全局定义的 TTL

支持的组件

示例

`filter`

`appid`（默认）