Python tempfile.SpooledTemporaryFile 怎样控制内存与磁盘切换

我第一次把上传中间结果从普通临时文件换成 tempfile.SpooledTemporaryFile 时，误以为它只是“带缓存的文件对象”。真正需要先做的判断是：这段数据大多数时候是否应该留在内存，什么时候必须得到真实磁盘后端，以及谁负责最后关闭临时资源。

这篇只讨论 Python 标准库里的内存缓冲与磁盘切换边界：用 max_size 控制阈值，用 rollover() 主动落盘，理解 fileno() 可能触发落盘，并用 with 让关闭动作有明确归属。

官方文档：https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile

SpooledTemporaryFile 适合“通常较小、偶尔变大”的临时数据：小数据先使用内存缓冲，超过明确阈值或需要文件描述符时再切换到磁盘；如果业务本来就需要稳定文件路径或长期复用，应该重新评估是否适合它。

先区分内存缓冲与磁盘后端

SpooledTemporaryFile 的行为和 TemporaryFile 相似，但数据默认先放在内存中。官方文档说明，数据大小超过 max_size，或者调用 fileno() 时，内容会写入磁盘，后续操作转为普通临时文件语义。

这意味着它不是“永远不落盘”的内存文件，也不是“创建后立刻有路径”的普通文件。实现内部的 _file 可能是二进制模式的 io.BytesIO、文本模式的 io.TextIOWrapper，也可能已经是真实文件对象。这个属性适合帮助理解后端边界，不应被当成跨版本的业务接口。

用 max_size 设定可解释的阈值

实际使用时不要把默认值当成业务策略。构造函数的 max_size 默认是 0，而“超过阈值才切换”的语义会让默认值缺乏清晰的内存预算。对于上传片段、导出中间结果或序列化缓存，最好根据单个对象允许占用的内存写出明确数值。

from tempfile import SpooledTemporaryFile

def build_payload(data: bytes, memory_limit: int = 512 * 1024) -> bytes:
    # 用明确的 max_size 表示单个临时对象的内存预算
    with SpooledTemporaryFile(max_size=memory_limit, mode="w+b") as spool:
        # 小数据先进入内存；超过阈值后由对象负责切换到磁盘
        spool.write(data)
        spool.seek(0)
        # 读取接口保持一致，调用方不需要区分当前后端
        return spool.read()

上面的选择重点不在“512 KB 一定正确”，而在于把阈值作为调用方的参数。阈值太小，会频繁获得磁盘文件；阈值太大，又可能让多个并发请求共同占用过多内存。应把单个对象上限与并发量一起估算，而不是只看一个文件。

fileno() 和 rollover() 都能强制落盘

需要文件描述符的底层库经常会调用 fileno()。对 SpooledTemporaryFile 来说，这个调用不是无副作用的查询：官方文档明确指出，它会促使缓冲内容写入磁盘。若业务只是读取或写回数据，不要为了“检查一下”而调用它。

rollover() 则是主动表达“现在就需要磁盘后端”。例如后续函数只接受真实文件描述符，或者希望把落盘时机固定在业务边界，可以显式调用它：

from tempfile import SpooledTemporaryFile

def prepare_for_native_io(data: bytes, consume_fd) -> None:
    # 使用 with 保证显式落盘后仍然能按同一生命周期关闭资源
    with SpooledTemporaryFile(max_size=2 * 1024 * 1024, mode="w+b") as spool:
        # 写入阶段可以继续使用统一的文件对象接口
        spool.write(data)
        # 这里主动切换后端，避免把落盘时机交给后续库的隐式调用
        spool.rollover()
        # fileno() 在此处只负责取得已落盘后端的描述符
        consume_fd(spool.fileno())

这个例子只用于说明调用关系。若外部代码还要继续使用描述符，必须重新设计资源所有权：with 结束会关闭 spool，描述符也不能再被当成长期有效的句柄。更稳妥的做法是让使用描述符的动作发生在同一个上下文内部。

别把 _file 当成稳定的 file API

有些排查代码会读取 spool._file，判断它当前是内存对象还是真实文件对象。这有助于理解切换，但下划线已经说明它是实现细节。业务代码应依赖 read()、write()、seek()、fileno() 和 rollover() 这些对象能力，而不是根据私有属性类型分支。

如果确实需要判断落盘状态，可以把判断封装在自己的适配层中，并给出清楚的目的：是为了调用原生库，还是为了记录资源诊断。不要把“当前恰好是 BytesIO”写成序列化协议，也不要假定不同 Python 版本的内部对象名称完全不变。

用 with 管理 close 和自动清理

SpooledTemporaryFile 可以作为上下文管理器使用。把它放在 with 中，既能覆盖仍在内存中的对象，也能覆盖已经通过阈值、fileno() 或 rollover() 转为磁盘后端的对象。离开上下文时，关闭动作有确定的时间点，不必等待垃圾回收。

from tempfile import SpooledTemporaryFile

def copy_to_sink(source, sink) -> None:
    # 临时对象只在本次处理范围内存在
    with SpooledTemporaryFile(max_size=1024 * 1024, mode="w+b") as spool:
        # 分块写入，避免一次性复制超大输入到内存
        while (chunk := source.read(64 * 1024)):
            spool.write(chunk)
        # 统一从开头读取，sink 不需要知道 spool 的后端类型
        spool.seek(0)
        while (chunk := spool.read(64 * 1024)):
            sink.write(chunk)
    # 离开 with 后由临时文件对象完成关闭与清理

这里的 source 和 sink 只是具有读写能力的对象，示例没有假定它们来自某个具体框架。真正需要注意的是两个资源边界：临时对象在上下文内部完成读写，调用方不应把离开上下文后的 spool 或其描述符继续传出去。

按场景选择阈值和切换方式

常见相关问题

max_size 是内存绝对上限吗？

它是触发切换的阈值，不等同于进程整体内存上限。并发创建多个 spool 时，应把每个对象阈值、并发数量和其他缓存一起纳入预算。

调用 fileno() 后还能继续 read 和 write 吗？

可以继续使用文件对象提供的读写能力，但后端已经转为磁盘文件；调用方应按真实文件资源处理，并让同一个上下文负责关闭。

为什么不直接检查 _file 的类型？

_file 是帮助理解实现的私有属性，版本或模式变化可能影响它。业务判断应围绕公开方法和自己的资源所有权设计。

对我来说，SpooledTemporaryFile 最实用的地方不是“自动帮你省内存”，而是让同一套读写代码跨过内存和磁盘两个后端。只要先写清 max_size，把 fileno() 与 rollover() 当成切换边界，再用 with 固定清理责任，这个对象就能在小数据效率和大数据安全之间保持清晰的取舍。