FastStream 实战:在 NATS JetStream 上构建 Object Storage 文件流式存储与监听服务

原创2026-09-17 16:37:481,870 阅读
文章标签:后端消息队列微服务

FastStream 实战:在 NATS JetStream 上构建 Object Storage 文件流式存储与监听服务

本指南围绕 FastStream 对 NATS JetStream Object Storage(对象存储) 的封装展开:从底层"对象即主题、分块存储"的架构原理,到 broker.object_storage() 的建桶写入、@broker.subscriber(..., obj_watch=True) 的对象监听、ObjectStorage 注解注入手动拉取,再到 ObjWatch 的精细化配置,并辅以仓库源码与测试用例佐证。读完本文,你将能够在自己的事件驱动服务中直接使用 NATS Object Storage 存储/传输超大文件,并在新对象出现时自动触发业务处理。

什么是 NATS Object Storage

Object Storage 存储几乎同构:KV 中每个 key 对应一个 JetStream subject,而 Object Storage 中每个 对象 key 同样对应一个 subject。从这个意义上讲,对象存储就是一类特殊的 JetStream——以对象名作为主题的流。

它和 KV 的核心区别在于对象大小:

  • KV 的单个值有 1MB 上限(max_value_size),适合存放小配置、状态快照;
  • Object Storage 没有最大对象大小限制,一个对象会被拆分为多个 chunk,每条消息即一个对象分块,因此可以"流式"地通过 NATS 传输超大文件。

正是这种分块 + 流式的设计,让 Object Storage 天然适合文件分发、模型权重同步、日志归档、媒体资源存储等场景。从 FastStream 源码看,其内部使用的正是 nats.js.object_store.ObjectStore 接口,即对官方客户端能力的一层薄封装,完整保留了底层所有原生能力。

FastStream 对 Object Storage 的封装

FastStream 为开发者提供了三类与 Object Storage 交互的便捷能力:

  1. broker.object_storage(bucket=...) —— 获取/创建对象存储桶句柄,用于写入对象;
  2. @broker.subscriber(bucket, obj_watch=True) —— 用普通订阅器语法监听桶内新对象;
  3. faststream.nats.annotations.ObjectStorage —— 在处理器函数中直接注入当前桶,无需手动维护上下文。

下面逐一展开。

创建对象存储桶并写入对象

参考官方示例 docs_src/nats/js/object.py(另有完整可运行版本 examples/nats/e07_object_storage.py):

from io import BytesIO

from faststream import FastStream
from faststream.nats import NatsBroker

broker = NatsBroker()
app = FastStream(broker)


@app.after_startup
async def test_send():
    object_storage = await broker.object_storage("example-bucket")
    await object_storage.put("file.txt", BytesIO(b"File mock"))

要点说明:

  • broker.object_storage("example-bucket") 会先尝试创建(declare)名为 example-bucket 的对象存储桶,返回的 object_storage 是一个标准的 NATS ObjectStore 句柄,后续 put、get、delete 等操作与原生 NATS API 完全一致;
  • BytesIO(b"File mock") 是 Python 标准库的 io.BytesIO,一个可读的二进制流对象,用来模拟"以读模式打开的文件"。实际使用中也可以直接传入真实的文件句柄(如 open("big.bin", "rb")),NATS 客户端会按块读取并写入桶中。

object_storage() 是一个幂等方法:它在内存中缓存所有已创建的桶,对同一个 bucket 重复调用不会向 NATS 发出新的创建请求,而是直接返回缓存的句柄。这一行为有专门的测试用例背书——tests/brokers/nats/test_os_declarer_cache.py 中连续两次调用 broker.object_storage("test"),并断言 create_object_store 只被调用一次:

with patch.object(
    JetStreamContext,
    "create_object_store",
    spy_decorator(JetStreamContext.create_object_store),
) as m:
    await broker.object_storage("test")
    await broker.object_storage("test")
    assert broker.config.os_declarer.buckets["test"]
    m.mock.assert_called_once()

object_storage 方法签名与参数说明

从 NatsBroker.object_storage 的签名可以看到,它直接透传给了底层声明器 OSBucketDeclarer.create_object_store:

参数 类型 默认值 说明
bucket str 必填 对象存储桶名称,即对应 JetStream 的主题名
description str | None None 桶的描述信息
ttl float | None None 对象存活时间(秒),过期后自动清理
max_bytes int | None None 桶的总容量上限(字节)
storage StorageType | None None 存储介质类型(如内存/文件)
replicas int 1 副本数,用于高可用冗余
placement Placement | None None 放置策略(如指定集群)
declare bool True 桶不存在时是否自动创建;False 则只连接已存在的桶

declare 的语义在 obj_storage_declarer.py 中体现得很清楚:为 True 时调用 JetStreamContext.create_object_store(...) 并携带完整的 ObjectStoreConfig;为 False 时仅调用 object_store(bucket) 连接已有桶,两者结果都会写入 self.buckets 缓存。

监听桶内新对象:obj_watch 订阅

拿到桶之后,除了用原生句柄主动读写,FastStream 还允许你用普通的订阅器接口监听桶内新出现的对象:

@broker.subscriber("example-bucket", obj_watch=True)
async def handler(filename: str):
    assert filename == "file.txt"

这里 "example-bucket" 直接作为 subject 传入,obj_watch=True 开启对象监听模式。NATS 只会投递对象文件名(以及可通过 message.raw_message 访问的元信息),而不会投递文件内容——因为文件可能任意大,框架必须保护服务避免内存溢出,所以不会把整个文件内容载入内存。

要实现"拿到文件名后按需拉取内容",可以结合注解注入手动获取。完整示例:

from io import BytesIO

from faststream import FastStream, Logger
from faststream.nats import NatsBroker
from faststream.nats.annotations import ObjectStorage

broker = NatsBroker()
app = FastStream(broker)


@broker.subscriber("example-bucket", obj_watch=True)
async def handler(
    filename: str,
    storage: ObjectStorage,
    logger: Logger,
):
    assert filename == "file.txt"
    file = await storage.get(filename)
    logger.info(file.data)


@app.after_startup
async def test_send():
    object_storage = await broker.object_storage("example-bucket")
    await object_storage.put("file.txt", BytesIO(b"File mock"))

ObjectStorage 注解注入

faststream.nats.annotations.ObjectStorage 是一个带上下文作用域的注解类型(定义见 annotations.py):

ObjectStorage = Annotated[_ObjectStore, Context(OBJECT_STORAGE_CONTEXT_KEY)]

它指向当前订阅对应的桶实例,因此你不需要手动把桶放入 context。框架在 ObjStoreWatchSubscriber.__consume_watch 消费循环中会把当前桶以 OBJECT_STORAGE_CONTEXT_KEY 为键放入上下文作用域(见 object_storage_subscriber.py),你的处理器函数声明 storage: ObjectStorage 参数即可自动获得桶句柄,随后 await storage.get(filename) 拉取对象内容、读取 file.data。

底层实现:ObjStoreWatchSubscriber

obj_watch=True 在注册时会被解析为 ObjStoreWatchSubscriber,其工作流程是:

  1. 订阅建立时(_create_subscription)通过 os_declarer.create_object_store(bucket=..., declare=...) 获取/创建桶;
  2. 启动后台任务 __consume_watch,在其中调用 bucket.watch(ignore_deletes, include_history, meta_only) 创建原生对象监听器;
  3. 循环调用 obj_watch.updates(timeout) 拉取对象变更事件,将 ObjectInfo 交给解析器 ObjParser 处理后分发给你的处理器;
  4. 每次消费都在 context.scope(OBJECT_STORAGE_CONTEXT_KEY, self.bucket) 作用域内进行,从而支撑上面的 ObjectStorage 注入。

该订阅器还支持 get_one() 与 __aiter__() 两种手动消费方式(见 object_storage_subscriber.py),说明同一个订阅器既可以注册处理器自动消费,也可以在测试或脚本中逐条拉取。

精细化控制:ObjWatch 配置对象

当你需要对监听行为做更细的控制时,可以传入 ObjWatch 配置对象而非布尔值。ObjWatch 的完整定义见 faststream/nats/schemas/obj_watch.py,其参数如下:

参数 类型 默认值 说明
ignore_deletes bool False 是否忽略对象删除事件
include_history bool False 是否包含历史记录(订阅时回放已有对象)
meta_only bool False 是否只返回元数据
timeout float 5.0 watch 轮询超时(秒)
declare bool True 桶不存在时是否自动创建

使用示例:

from faststream.nats import NatsBroker, ObjWatch

broker = NatsBroker()

@broker.subscriber(
    "example-bucket",
    obj_watch=ObjWatch(declare=False),
)
async def handler(filename: str):
    ...

这里 declare=False 表示订阅时不自动创建桶,而是只连接已存在的桶——适合桶已由运维或其它服务预先创建好的生产场景,避免订阅器意外创建资源。

ObjWatch 还提供了 validate 类方法用于类型归一化:True → 默认配置的 ObjWatch()、False → None、传入对象则原样返回(见 obj_watch.py)。这也是 obj_watch=True 与 obj_watch=ObjWatch(...) 两种写法可以混用的原因。上面表格中的参数会一一映射到原生 bucket.watch(...) 调用(见 object_storage_subscriber.py)。

与 Key-Value 存储的关系

Object Storage 与 Key-Value 存储 是姊妹特性,二者都构建在 JetStream 之上,且 FastStream 对它们的封装模式完全一致:

  • 通过 broker.object_storage(bucket=...) / broker.key_value(bucket=...) 幂等地获取存储句柄(对应两个独立的声明器缓存 obj_storage_declarer.py 与 bucket_declarer.py);
  • 都支持用 @broker.subscriber 监听变化,分别由 obj_watch / kv_watch 开关控制;
  • 都提供了 ObjWatch / KvWatch 配置对象来做细粒度控制。

选型上只需记住一条:值可能超过 1MB 或需要流式处理大文件时选 Object Storage,否则选 KV。

测试验证

仓库对 Object Storage 特性有完整的测试覆盖:

这些测试同时印证了一个事实:Object Storage 订阅同样会参与 FastStream 的 AsyncAPI 文档生成,可以让 API 消费者看到"这个 bucket 上的对象变更事件"。

小结

FastStream 把 NATS Object Storage 的建桶、写入、监听、注入全链路做成了贴近普通 broker 用法的体验:

  1. broker.object_storage(bucket) 幂等获取桶句柄,支持 description/ttl/max_bytes/replicas/declare 等完整配置;
  2. @broker.subscriber(bucket, obj_watch=True) 即可监听新对象,回调参数是文件名而非文件内容,天然规避内存风险;
  3. 处理器中注入 ObjectStorage 注解,按需 storage.get(filename) 拉取内容;
  4. 需要精细控制时使用 ObjWatch(ignore_deletes=..., include_history=..., meta_only=..., timeout=..., declare=...)。

配合 FastStream 的 FastAPI 集成、可观测性与内存测试能力,你可以把"对象存储 + 事件驱动"快速接入现有服务,实现超大文件的高效流转与自动化处理。

登录后查看全文
faststream