Django流式响应

使用 StreamingHttpResponse 来实现流式响应，也就是将数据分块返回给客户端，而不是一次性返回全部内容。这在处理大文件下载、实时数据推送等场景中非常实用。

一、基本原理与使用场景

StreamingHttpResponse 是 Django 提供的用于流式传输响应的类，它不会一次性将所有响应数据加载到内存中，而是通过迭代器逐块发送数据，适合：

大文件下载（避免内存溢出）
实时生成并返回数据（如实时日志、进度条更新）
服务器推送事件（SSE）等实时通信场景

二、基础使用示例

1. 最简单的流式响应

先写一个基础示例，逐行返回文本数据：

python 复制代码

from django.http import StreamingHttpResponse
from django.views import View
import time

# 定义生成器函数，用于逐块生成数据
def stream_generator():
    """生成器函数，逐行返回数据（模拟实时生成内容）"""
    for i in range(5):
        # 模拟耗时操作（如读取大文件、实时计算）
        time.sleep(1)
        # 每块数据末尾加换行符，让客户端能实时看到
        yield f"这是第 {i+1} 块数据\n"

class StreamView(View):
    def get(self, request):
        # 创建 StreamingHttpResponse，传入生成器
        response = StreamingHttpResponse(stream_generator())
        # 设置响应头，确保客户端按流处理（可选但推荐）
        response['Content-Type'] = 'text/plain; charset=utf-8'
        # 禁用缓存，确保数据实时推送
        response['Cache-Control'] = 'no-cache'
        # 添加流式传输 headers，禁用缓冲
        # 注意：Transfer-Encoding 和 Connection 是 hop-by-hop headers，由 WSGI 服务器自动处理，不能在应用层设置
        # response['Cache-Control'] = 'no-cache, no-store, must-revalidate'
        # response['Pragma'] = 'no-cache'
        # response['Expires'] = '0'
        # response['X-Accel-Buffering'] = 'no'  # 禁用 Nginx 缓冲

        # logger.info(f"[StreamingView] StreamingHttpResponse 已创建，headers 已配置用于流式传输")
        return response

2. 大文件流式下载

这是更实用的场景，避免一次性读取大文件到内存：

python 复制代码

from django.http import StreamingHttpResponse
from django.views import View
import os

def file_stream_generator(file_path, chunk_size=8192):
    """读取文件并逐块生成数据"""
    with open(file_path, 'rb') as f:
        while chunk := f.read(chunk_size):
            yield chunk

class LargeFileDownloadView(View):
    def get(self, request):
        # 替换为你的大文件路径
        file_path = "/path/to/your/large_file.zip"
        if not os.path.exists(file_path):
            return HttpResponse("文件不存在", status=404)
        
        # 获取文件名
        file_name = os.path.basename(file_path)
        # 创建流式响应
        response = StreamingHttpResponse(
            file_stream_generator(file_path),
            content_type='application/octet-stream'  # 二进制文件类型
        )
        # 设置下载头，指定文件名
        response['Content-Disposition'] = f'attachment; filename="{file_name}"'
        # 设置分块传输编码
        response['Transfer-Encoding'] = 'chunked'
        return response

3. 实时 SSE（服务器推送事件）

适用于实时通知、进度展示等场景：

python 复制代码

from django.http import StreamingHttpResponse
from django.views import View
import time
import json

def sse_generator():
    """生成 SSE 格式的实时数据"""
    for i in range(10):
        time.sleep(1)
        # SSE 格式要求：data: 内容\n\n
        data = json.dumps({"progress": i * 10, "message": f"处理中 {i*10}%"})
        yield f"data: {data}\n\n"

class SSEView(View):
    def get(self, request):
        response = StreamingHttpResponse(sse_generator())
        # SSE 专用 Content-Type
        response['Content-Type'] = 'text/event-stream'
        # 禁用缓存和超时
        response['Cache-Control'] = 'no-cache'
        response['X-Accel-Buffering'] = 'no'  # 禁用 nginx 缓冲（关键）
        return response

三、关键注意事项

生成器必须是迭代器 ：StreamingHttpResponse 的参数必须是可迭代对象（如生成器函数），不能是普通列表（否则会一次性加载）。
禁用缓冲 ：
- 对于 Nginx 反向代理，需添加 response['X-Accel-Buffering'] = 'no'，否则 Nginx 会缓冲数据直到生成器结束才推送。
- 对于 Apache，需配置 SetEnv no-gzip 1 禁用压缩缓冲。

异常处理 ：生成器中如果出现异常，响应会中断，建议添加 try-except：

python 复制代码

def stream_generator():
    try:
        for i in range(5):
            time.sleep(1)
            yield f"第 {i+1} 块数据\n"
    except Exception as e:
        yield f"出错了：{str(e)}\n"

不支持某些中间件 ：部分 Django 中间件（如 GZipMiddleware）会缓冲响应，导致流式失效，需排除这些中间件。

总结

StreamingHttpResponse 核心是通过生成器逐块返回数据，避免一次性加载大量数据到内存，适合大文件、实时数据场景。
使用时需注意禁用缓冲（尤其是反向代理层），否则流式效果会失效。
不同场景需配置对应的 Content-Type（如文件下载用 application/octet-stream，SSE 用 text/event-stream）。

补充：URL 配置（确保视图可访问）

在 urls.py 中添加路由：

python 复制代码

from django.urls import path
from .views import StreamView, LargeFileDownloadView, SSEView

urlpatterns = [
    path('stream/', StreamView.as_view(), name='stream'),
    path('download-large-file/', LargeFileDownloadView.as_view(), name='download'),
    path('sse/', SSEView.as_view(), name='sse'),
]