EventStoreDB 持久化订阅 HTTP API 详解

EventStoreDB 持久化订阅 HTTP API 详解

EventStore The stream database optimised for event sourcing 项目地址: https://gitcode.com/gh_mirrors/ev/EventStore

什么是持久化订阅

持久化订阅（Persistent Subscriptions）是 EventStoreDB 中一种强大的消息消费模式，它允许多个消费者以"竞争消费者"模式共同处理来自同一个流的事件。这种模式特别适合需要负载均衡和高可用性的场景。

与普通订阅不同，持久化订阅具有以下特点：

• 消息处理状态会被持久化存储
• 支持消息重试机制
• 允许多个消费者协同工作
• 提供消息确认机制

创建持久化订阅

在开始消费消息前，需要先创建订阅组。创建操作需要管理员权限。

创建请求格式

PUT /subscriptions/{stream}/{subscription_name}
Content-Type: application/json

路径参数：

• stream：要订阅的流名称
• subscription_name：订阅组名称

请求体参数：

• resolveLinktos：是否解析链接事件
• startFrom：从流中哪个位置开始订阅
• extraStatistics：是否收集客户端统计信息
• checkPointAfterMilliseconds：检查点间隔时间(毫秒)
• liveBufferSize：内存中实时缓冲区大小
• readBatchSize：分页模式下的读取批次大小
• bufferSize：分页模式下的缓冲区大小
• maxCheckPointCount：强制创建检查点的最大未确认消息数
• maxRetryCount：消息最大重试次数
• maxSubscriberCount：最大TCP订阅者数量
• messageTimeoutMilliseconds：客户端超时时间
• minCheckPointCount：创建检查点的最小消息数
• namedConsumerStrategy：消费者策略(RoundRobin/DispatchToSingle/Pinned/PinnedByCorrelation)

注意事项：

1. 不能重复创建同名订阅组
2. HTTP API不支持对$all流的持久化订阅

更新持久化订阅

可以动态修改订阅组的配置，修改会断开当前所有连接并重置订阅状态。

POST /subscriptions/{stream}/{subscription_name}
Content-Type: application/json

参数与创建订阅相同。

删除持久化订阅

DELETE /subscriptions/{stream}/{subscription_name}

通过订阅读取事件

默认情况下，每次请求返回一个事件，且不包含事件属性的完整信息。

GET /subscriptions/{stream}/{subscription_name}[?count=N&embed=level]

查询参数：

• count：要返回的事件数量
• embed：嵌入级别(None/Content/Rich/Body/PrettyBody/TryHarder)

消息确认机制

消费者必须对处理的消息进行确认(Ack)或否定确认(Nack)。

确认单个消息

POST /subscriptions/{stream}/{subscription_name}/ack/{messageid}

批量确认消息

POST /subscriptions/{stream}/{subscription_name}/ack?ids=id1,id2,id3

否定确认单个消息

POST /subscriptions/{stream}/{subscription_name}/nack/{messageid}?action=action

批量否定确认消息

POST /subscriptions/{stream}/{subscription_name}/nack?ids=id1,id2,id3&action=action

action可选值：

• Park：停放消息，稍后重放
• Retry：立即重试
• Skip：跳过该消息
• Stop：停止订阅

重放停放的消息

POST /subscriptions/{stream}/{subscription_name}/replayParked

查询订阅信息

获取所有订阅信息

GET /subscriptions

获取特定流的订阅信息

GET /subscriptions/{stream}

获取特定订阅的详细信息

GET /subscriptions/{stream}/{subscription_name}/info

最佳实践

1. 合理设置超时时间：根据业务处理时间设置合适的messageTimeoutMilliseconds
2. 检查点配置：根据吞吐量调整minCheckPointCount和maxCheckPointCount
3. 消费者策略选择：
   • RoundRobin：均匀分配消息
   • DispatchToSingle：单消费者模式
   • Pinned：固定消费者处理特定消息
4. 错误处理：合理使用Nack的action参数处理失败消息
5. 监控：定期检查订阅状态和积压消息数

通过合理配置和使用持久化订阅，可以构建出高可靠、高可用的消息处理系统。

EventStore The stream database optimised for event sourcing 项目地址: https://gitcode.com/gh_mirrors/ev/EventStore