EventStore HTTP API 可选请求头详解

EventStore HTTP API 可选请求头详解

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

前言

EventStore 是一个高性能的事件溯源数据库，提供了丰富的 HTTP API 接口。在使用这些接口时，可以通过特定的可选请求头来控制请求的行为和返回结果。本文将详细介绍这些可选请求头的功能和使用场景。

核心可选请求头概览

EventStore 支持以下以 Kurrent- 为前缀的自定义 HTTP 请求头：

| 请求头名称 | 功能描述 | |------------|----------| | Kurrent-ExpectedVersion | 设置期望的流版本号（用于乐观并发控制） | | Kurrent-ResolveLinkTo | 控制是否解析流中的 linkTo 链接 | | Kurrent-RequireLeader | 指定操作必须在主节点上执行 | | Kurrent-TrustedAuth | 允许可信中介处理认证 | | Kurrent-LongPoll | 指示服务器在流读取时执行长轮询操作 | | Kurrent-HardDelete | 指示服务器执行硬删除而非默认的软删除 | | Kurrent-EventType | 指定与 POST 正文关联的事件类型 | | Kurrent-EventId | 指定与 POST 正文关联的事件 ID |

详细解析

事件标识相关头

Kurrent-EventId

当向流追加事件且不使用 application/vnd.kurrent.events+json 媒体类型时，必须为每个事件指定唯一标识符。

使用场景：

• 确保事件的幂等性
• 避免重复处理相同事件

示例：

curl -i "http://localhost:2113/streams/newstream" \
    -H "Content-Type: application/json" \
    -H "Kurrent-EventType: SomeEvent" \
    -H "Kurrent-EventId: 4d36b96a-4b5a-4f5e-9059-41e40a25dc4d" \
    -d "{\"a\":\"1\"}"

如果不提供事件ID，EventStore会生成一个唯一标识符并返回307重定向。

Kurrent-EventType

与EventId类似，当不使用特定媒体类型时，必须指定事件类型。

示例：

curl -i "http://localhost:2113/streams/newstream" \
    -H "Content-Type: application/json" \
    -H "Kurrent-EventType: UserRegistered" \
    -d "{\"username\":\"john\"}"

并发控制头

Kurrent-ExpectedVersion

用于实现乐观并发控制，确保在追加事件时流的版本符合预期。

特殊值：

• 0：流应存在但为空
• -1：流不应存在
• -2：写入不应与任何内容冲突，总是成功
• -4：流或元数据流应存在

示例：

# 期望流版本为0（即流存在但只有一个事件）
curl -i "http://localhost:2113/streams/newstream" \
    -H "Content-Type: application/json" \
    -H "Kurrent-EventType: SomeEvent" \
    -H "Kurrent-ExpectedVersion: 0" \
    -d "{\"a\":\"2\"}"

如果版本不匹配，将返回400错误并包含当前版本信息。

数据操作头

Kurrent-HardDelete

控制删除行为，默认为软删除（可恢复），设置为true时执行硬删除。

区别：

• 软删除：返回404，流可重新创建
• 硬删除：返回410，流永久删除

示例：

curl -i -X DELETE "http://localhost:2113/streams/newstream" \
    -H "Kurrent-HardDelete: true"

Kurrent-LongPoll

实现服务器推送模式，减少客户端轮询。

工作原理： 客户端指定等待时间（秒），服务器在有新事件时立即返回，否则在超时后返回空响应。

示例：

curl -i "http://localhost:2113/streams/newstream/head/backward/20" \
    -H "Kurrent-LongPoll: 15"

集群相关头

Kurrent-RequireLeader

在集群环境中，确保操作只在主节点执行。

行为：

• 当前节点是主节点：正常处理
• 当前节点不是主节点：返回307重定向到主节点

示例：

curl -i "http://localhost:2113/streams/newstream" \
    -H "Kurrent-RequireLeader: true"

投影相关头

Kurrent-ResolveLinkTo

控制是否解析投影生成的linkTo事件。

区别：

• true（默认）：返回链接指向的原始事件
• false：返回linkTo事件本身

示例：

# 不解析linkTo
curl -i "http://localhost:2113/streams/projection-stream" \
    -H "Kurrent-ResolveLinkTo: false"

最佳实践建议

1. 生产环境：始终指定EventId和EventType以确保数据一致性
2. 并发控制：关键业务操作使用ExpectedVersion避免并发冲突
3. 性能优化：考虑使用LongPoll减少不必要的轮询请求
4. 集群部署：对写操作使用RequireLeader确保数据一致性
5. 数据安全：谨慎使用HardDelete，确保数据可恢复性

总结

EventStore 的这些可选 HTTP 请求头提供了对数据操作的精细控制，理解并合理使用这些头可以显著提升应用的可靠性和性能。在实际开发中，应根据具体场景选择适当的请求头组合，以达到最佳效果。

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