FastStream NATS JetStream Key-Value 存储实战:从写入、订阅监听到高级 KvWatch 配置
FastStream NATS JetStream Key-Value 存储实战:从写入、订阅监听到高级 KvWatch 配置
FastStream 将 NATS JetStream 的 Key-Value(KV)存储以高层接口形式内置集成:你可以像使用普通 KV 数据库一样读写数据,同时利用 JetStream 流式能力订阅键的变化、追溯历史修订。本指南围绕官方文档 docs/docs/en/nats/jetstream/key-value.md 展开,结合仓库源码与测试,讲透 broker.key_value() 的创建与幂等缓存、@broker.subscriber 的键监听,以及 KvWatch 的全部配置参数,读完即可在事件驱动服务中落地 KV 存储方案。
认识 NATS Key-Value:JetStream 之上的高层接口
在 NATS 生态中,Key-Value 存储并非独立组件,而是构建在 JetStream 之上的高层抽象:
- 一个 KV bucket 本质就是一个 JetStream Stream,KV 的 key 对应流中的 subject;
- 对某个 key 执行
Put/Update,等价于向对应 subject 发布一条新消息; - 因此
Get操作不仅能拿到当前值,还能拿到该 key 在流中的最新偏移量(offset),并支持按偏移量读取任意历史版本。
正是这种"消息流 + KV 语义"的双重特性,让同一个 KV 接口可以同时支持三种截然不同的用法:
- 当作普通 KV 存储:忽略偏移量,直接读写键值;
- 订阅键的变化:像订阅消息一样监听某个 key 的每次更新;
- 读取历史修订:按 offset 回溯 KV 的任意历史版本。
FastStream 完整保留了这些能力,并将其无缝接入自身的 Broker / Subscriber 编程模型。
第一步:创建 Key-Value 存储并写入数据
使用 FastStream 的 NATS 集成时,通过 NatsBroker 实例调用 key_value() 方法即可创建(或连接)一个 KV bucket。以下为文档配套的完整示例 docs/docs_src/nats/js/key_value.py:
from faststream import FastStream
from faststream.nats import NatsBroker
broker = NatsBroker()
app = FastStream(broker)
@broker.subscriber("key", kv_watch="bucket")
async def handler(msg: str):
assert msg == "Hello!"
@app.after_startup
async def setup_broker():
key_value = await broker.key_value(bucket="bucket")
await key_value.put("key", b"Hello!")
代码要点:
broker.key_value(bucket="bucket")返回原生 NATS 的KeyValue对象(nats.js.kv.KeyValue),可直接调用其put()、get()、update()、delete()、purge()等原生方法;- 示例在
after_startup钩子中写入key = "Hello!",随后由订阅了该 key 的 handler 消费,handler 中的assert msg == "Hello!"验证了整条链路; - 文档约定:
key_value的 bucket 名与订阅的 key 无强制绑定,你可以创建任意命名的 bucket,再按 key 精确或通配订阅。
幂等性:同 bucket 只向 NATS 请求一次
broker.key_value(bucket=...) 是**幂等(idempotent)**方法:所有已创建的 KV 存储对象都会缓存在内存中,对同一 bucket 重复调用不会向 NATS 发出新的创建请求,而是直接返回缓存对象。
该行为由 KVBucketDeclarer 实现——它内部维护一个 buckets: dict[str, KeyValue] 缓存,create_key_value() 首先检查缓存命中:
if (key_value := self.buckets.get(bucket)) is None:
if declare:
key_value = await self.__state.connection.create_key_value(...)
else:
key_value = await self.__state.connection.key_value(bucket)
self.buckets[bucket] = key_value
return key_value
测试 tests/brokers/nats/test_kv_declarer_cache.py 对这一行为做了显式验证:连续两次 await broker.key_value("test") 后,JetStreamContext.create_key_value 仅被调用一次,且缓存中已存在对应 bucket。
实践建议:因为方法幂等,你可以在
after_startup、路由初始化、甚至每个 handler 里安全地重复调用key_value(),不必担心重复建流或产生额外网络开销。
第二步:用 @broker.subscriber 监听 Key 变化
创建好 bucket 后,返回的 key_value 对象用法与原生 NATS 完全一致。而 FastStream 的独特之处在于:监听某个 key 的每次变更,不需要手写 watch() 循环,直接用常规的 @broker.subscriber 即可:
@broker.subscriber("key", kv_watch="bucket")
async def handler(msg: str):
...
kv_watch="bucket"接收字符串形式的 bucket 名,等价于kv_watch=KvWatch("bucket");- 订阅的 subject(此处为
"key")即你要监听的 KV key; - handler 参数类型标注为
str,框架会自动完成值解码,你拿到的是put()写入的原始值; - 监听是持续生效的:bucket 中该 key 的每次新增或更新(
put/update)都会触发 handler。
底层实现:KeyValueWatchSubscriber
当 kv_watch 参数非空时,订阅工厂会构造专门的 KeyValueWatchSubscriber 实例,其核心逻辑:
- 通过
kv_declarer.create_key_value(bucket=..., declare=...)获取 bucket 句柄; - 调用原生
bucket.watch(keys=...)建立 key watcher 订阅; - 在后台任务
__consume_watch中循环调用key_watcher.updates(timeout)拉取变更,一旦有更新即进入框架的consume流程(中间件、解码、handler 调用一应俱全)。
订阅分发逻辑见 faststream/nats/subscriber/factory.py#L197-L201:
if kv_watch is not None:
return KeyValueWatchSubscriber(
**(subscriber_options | {"specification": not_include_spec}),
kv_watch=kv_watch,
)
解析层同样独立:KV 消息使用 KvParser 处理,将 KeyValue.Entry 转换为 NatsKvMessage,消息体取 entry.value,路径匹配针对 entry.key,因此通配符订阅(如 "orders.*")同样可用。
集成测试 tests/brokers/nats/test_consume.py#L390-L417 完整验证了"订阅 → put → 收到值"的闭环:向 queue + "1" bucket 中 put(queue, b"world") 后,handler 收到并断言 b"world"。
第三步:用 KvWatch 精细控制 KV 监听
如果默认行为不够用,FastStream 提供了 KvWatch 配置对象,可对 KV 监听做细粒度控制。文档示例:
from faststream.nats import NatsBroker, KvWatch
@broker.subscriber(
"key",
kv_watch=KvWatch("bucket", declare=False),
)
async def handler(msg: str):
...
KvWatch 定义于 faststream/nats/schemas/kv_watch.py,全部参数如下:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
bucket |
str |
(必填) | KV bucket 名称 |
declare |
bool |
True |
是否自动创建 bucket;False 表示仅连接已存在的 bucket,bucket 不存在则报错 |
headers_only |
bool |
False |
只接收变更的头部元数据,不携带值 |
include_history |
bool |
False |
订阅建立时是否先回放该 key 的全部历史修订 |
ignore_deletes |
bool |
False |
是否忽略删除(delete/purge)事件,只关心写入与更新 |
meta_only |
bool |
False |
只接收元数据(不含值),适合仅需感知变更的场景 |
inactive_threshold |
float | None |
None |
非活跃阈值:超过该时长无更新的 key 会被标记为不活跃,由底层 watcher 决定是否推送对应状态 |
timeout |
float | None |
5.0 |
底层 updates() 轮询超时(秒),控制变更拉取的空转间隔 |
其中 bucket 必填、其余全部可选,参数一一透传给原生 bucket.watch(),见 key_value_subscriber.py#L66-L73。
declare=False 的典型场景:bucket 由外部运维预先创建(或由另一个服务创建),此时订阅方不应拥有建流权限,只需连接既有 bucket。代码路径上,declare=False 会走 connection.key_value(bucket) 而不是 create_key_value(...),见 bucket_declarer.py#L44-L64。
字符串与对象的互通
kv_watch 参数同时接受字符串与 KvWatch 实例。底层通过 NameRequired.validate 统一转换:字符串会被包装成 KvWatch(value),再经 registrator.py#L530 的 KvWatch.validate(kv_watch) 归一化。因此两种写法完全等价:
@broker.subscriber("key", kv_watch="bucket") # 简写
@broker.subscriber("key", kv_watch=KvWatch("bucket")) # 全量配置
深入:key_value() 与 KvWatch 的完整参数对照
broker.key_value() 本身也支持丰富的 bucket 配置参数(对应原生 KeyValueConfig),定义于 faststream/nats/broker/broker.py#L688-L719:
| 参数 | 默认值 | 说明 |
|---|---|---|
bucket |
必填 | 存储桶名称 |
description |
None |
bucket 描述信息 |
max_value_size |
None |
单条 value 最大字节数限制 |
history |
1 |
每个 key 保留的历史修订数 |
ttl |
None |
键值过期时间(秒) |
max_bytes |
None |
bucket 总存储上限(字节) |
storage |
None |
存储类型(StorageType,如 File / Memory) |
replicas |
1 |
副本数,用于高可用配置 |
placement |
None |
集群放置约束 |
republish |
None |
变更重发布配置 |
direct |
None |
是否启用 Direct Get 模式 |
declare |
True |
是否自动创建 bucket,False 仅连接已存在 bucket |
这些参数在 KVBucketDeclarer.create_key_value 中被组装为 KeyValueConfig 透传给 JetStream。实际生产中常见组合:
- 保留历史版本:
history=10,配合include_history=True的订阅实现变更回放; - 有界存储:
max_bytes+ttl组合控制容量与过期; - 多副本容灾:
replicas=3(需集群支持); - 只读接入:
declare=False防止误建 bucket。
常见使用模式与注意事项
模式一:KV 即配置中心
将运行时配置写入 KV bucket,服务启动后用 kv_watch 订阅配置 key,配置变更实时生效,无需重启;结合 history 保留可审计的变更轨迹。
模式二:事件溯源 / 状态机
把每个 key 的每次更新当作事件流,include_history=True 可让新加入的消费者回放全量历史,重建状态。
注意事项:
declare=False时若 bucket 不存在,底层会抛出错误——请确保 bucket 已由其他途径创建;include_history开启后,订阅建立时会立即收到历史修订,handler 需具备幂等性以应对重复值;meta_only/headers_only只携带元数据不携带值,适用于"只需感知变更、无需取数"的场景;- 幂等缓存按 bucket 名区分:同一进程内不同
KvWatch配置若指向同名 bucket,共享同一底层KeyValue对象,因此 bucket 级参数以首次创建为准。
小结
FastStream 的 NATS Key-Value 集成把 JetStream 的 KV 能力完整封装进框架生态:
broker.key_value()幂等创建/获取 bucket,支持完整的KeyValueConfig参数,底层由 KVBucketDeclarer 维护内存缓存;@broker.subscriber(key, kv_watch=bucket)让键监听与普通订阅统一,由 KeyValueWatchSubscriber 驱动原生watch()并接入中间件/解码链路;KvWatch提供declare、include_history、ignore_deletes、meta_only、timeout等细粒度控制,覆盖从"只连不建"到"历史回放"的各类需求。
结合文档示例 key_value.py、源码实现与集成测试,你已具备将 KV 存储作为配置中心、状态存储或变更通知通道融入 FastStream 服务的能力。