FastStream 实战:在 NATS JetStream 上构建 Object Storage 文件流式存储与监听服务
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 交互的便捷能力:
broker.object_storage(bucket=...)—— 获取/创建对象存储桶句柄,用于写入对象;@broker.subscriber(bucket, obj_watch=True)—— 用普通订阅器语法监听桶内新对象;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是一个标准的 NATSObjectStore句柄,后续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,其工作流程是:
- 订阅建立时(
_create_subscription)通过os_declarer.create_object_store(bucket=..., declare=...)获取/创建桶; - 启动后台任务
__consume_watch,在其中调用bucket.watch(ignore_deletes, include_history, meta_only)创建原生对象监听器; - 循环调用
obj_watch.updates(timeout)拉取对象变更事件,将ObjectInfo交给解析器ObjParser处理后分发给你的处理器; - 每次消费都在
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 特性有完整的测试覆盖:
- tests/brokers/nats/test_os_declarer_cache.py —— 验证
object_storage()幂等缓存行为; - tests/brokers/nats/test_consume.py —— 验证
obj_watch订阅消费流程; - tests/asyncapi/nats/v3_0_0/test_obj_schema.py 与 tests/asyncapi/nats/v2_6_0/test_obj_schema.py —— 验证对象存储订阅在 AsyncAPI 文档中的 schema 生成;
- tests/examples/nats/test_e07_object_storage.py —— 直接对示例程序 examples/nats/e07_object_storage.py 做端到端验证。
这些测试同时印证了一个事实:Object Storage 订阅同样会参与 FastStream 的 AsyncAPI 文档生成,可以让 API 消费者看到"这个 bucket 上的对象变更事件"。
小结
FastStream 把 NATS Object Storage 的建桶、写入、监听、注入全链路做成了贴近普通 broker 用法的体验:
broker.object_storage(bucket)幂等获取桶句柄,支持description/ttl/max_bytes/replicas/declare等完整配置;@broker.subscriber(bucket, obj_watch=True)即可监听新对象,回调参数是文件名而非文件内容,天然规避内存风险;- 处理器中注入
ObjectStorage注解,按需storage.get(filename)拉取内容; - 需要精细控制时使用
ObjWatch(ignore_deletes=..., include_history=..., meta_only=..., timeout=..., declare=...)。
配合 FastStream 的 FastAPI 集成、可观测性与内存测试能力,你可以把"对象存储 + 事件驱动"快速接入现有服务,实现超大文件的高效流转与自动化处理。