FastStream NATS JetStream Key-Value 存储实战:从写入、订阅监听到高级 KvWatch 配置

原创2026-09-17 23:29:251,983 阅读
文章标签:后端消息队列微服务

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 接口可以同时支持三种截然不同的用法:

  1. 当作普通 KV 存储:忽略偏移量,直接读写键值;
  2. 订阅键的变化:像订阅消息一样监听某个 key 的每次更新;
  3. 读取历史修订:按 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 实例,其核心逻辑:

  1. 通过 kv_declarer.create_key_value(bucket=..., declare=...) 获取 bucket 句柄;
  2. 调用原生 bucket.watch(keys=...) 建立 key watcher 订阅;
  3. 在后台任务 __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 服务的能力。

登录后查看全文
faststream