Spring Boot 返回 MP4 视频无法播放

Question

在使用Spring Boot提供MP4视频流时，常见问题是前端无法播放或播放卡顿。主要原因是直接通过`ResponseEntity`返回整个文件，导致内存占用高且不支持断点续传。正确做法应使用`StreamingResponseBody`实现分块传输，并设置正确的`Content-Type: video/mp4`及`Accept-Ranges`响应头，确保浏览器能按需加载视频片段，避免因响应体过大或缺少范围请求支持而导致播放失败。

Answer 1

一、问题背景与常见现象

在基于Spring Boot构建的Web应用中，提供MP4视频流服务是常见的需求。然而，许多开发者在实现过程中遇到前端无法播放或播放卡顿的问题。这类问题往往不是由于网络带宽不足或浏览器兼容性差引起，而是源于后端视频响应方式的不当设计。

典型错误做法是使用 ResponseEntity<byte[]> 将整个视频文件一次性读入内存并返回。这种方式在小文件场景下尚可运行，但面对大体积MP4文件时，极易引发以下问题：

• 高内存占用：整个视频被加载到JVM堆中，可能导致OutOfMemoryError
• 无断点续传支持：HTTP Range请求无法处理，用户拖动进度条时需重新加载整个文件
• 响应延迟明显：必须等待文件完全读取后才开始传输
• 不支持浏览器预加载机制（preload）
• CDN缓存效率低下
• 并发访问性能急剧下降
• 无法实现渐进式流媒体体验
• 移动端播放兼容性差
• 服务器GC压力增大
• 用户体验差，表现为“缓冲中”或直接报错

二、技术原理分析

现代浏览器在播放HTML5视频时依赖HTTP协议的Range Requests机制。当用户拖动播放进度条时，浏览器会发送带有 Range: bytes=1024-2048 的请求，要求获取指定字节范围的内容。若服务器未正确响应此类请求，则播放器只能从头开始加载，造成卡顿甚至失败。

请求类型	Header示例	服务器应答要求
完整请求	-	返回200，Content-Length
范围请求	Range: bytes=0-1023	返回206，Content-Range
多段请求	Range: bytes=0-10,20-30	极少使用，一般返回416
无效范围	Range: bytes=99999-	返回416 Requested Range Not Satisfiable

此外，正确的MIME类型设置至关重要。若返回 application/octet-stream 而非 video/mp4，部分浏览器将拒绝自动播放或无法识别为视频资源。

三、解决方案设计与实现

为解决上述问题，应采用 StreamingResponseBody 接口实现流式输出，并结合 HttpHeaders 设置必要的响应头信息。以下是核心实现步骤：

1. 接收视频路径参数
2. 校验文件存在性和合法性
3. <3>解析HTTP Range头
4. 计算起始位置、结束位置和内容长度
5. 设置状态码（200或206）
6. 添加Content-Type、Accept-Ranges、Content-Range等头部
7. 使用InputStream分块写入OutputStream
8. 控制缓冲区大小以平衡性能与内存
9. 处理异常并关闭资源
10. 支持条件请求（If-Range等）优化缓存

import org.springframework.core.io.Resource;
import org.springframework.http.*;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody;

import javax.servlet.http.HttpServletRequest;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardOpenOption;

@RestController
public class VideoStreamController {

    @GetMapping(value = "/video/{id}", produces = MediaType.VIDEO_MP4_VALUE)
    public ResponseEntity<StreamingResponseBody> streamVideo(
            @PathVariable String id,
            HttpServletRequest request) throws Exception {

        Path videoPath = resolveVideoPath(id); // 实现路径映射逻辑
        if (!Files.exists(videoPath)) {
            return ResponseEntity.notFound().build();
        }

        final long fileSize = Files.size(videoPath);
        HttpRange range = request.getRange().isEmpty() ? 
            null : request.getRange().get(0);

        long start = range == null ? 0 : range.getRangeStart(fileSize);
        long end = range == null ? fileSize - 1 : range.getRangeEnd(fileSize);
        long length = end - start + 1;

        HttpStatus status = range == null ? HttpStatus.OK : HttpStatus.PARTIAL_CONTENT;

        StreamingResponseBody body = outputStream -> {
            try (InputStream is = Files.newInputStream(videoPath, StandardOpenOption.READ)) {
                is.skip(start);
                byte[] buffer = new byte[8192];
                long remaining = length;
                int read;
                while (remaining > 0 && (read = is.read(buffer, 0, 
                    (int)Math.min(buffer.length, remaining))) != -1) {
                    outputStream.write(buffer, 0, read);
                    remaining -= read;
                }
            }
        };

        HttpHeaders headers = new HttpHeaders();
        headers.setAcceptRanges("bytes");
        headers.setContentType(MediaType.VIDEO_MP4);
        headers.setContentLength(length);
        if (range != null) {
            headers.setContentRange(start, end, fileSize);
        }

        return ResponseEntity.status(status)
                .headers(headers)
                .body(body);
    }
}

四、系统架构与流程图

完整的视频流服务涉及多个组件协同工作。以下为整体交互流程：

graph TD A[前端 <video src="/video/123">] --> B{浏览器发送请求} B --> C[Spring Boot Controller] C --> D{是否存在Range头?} D -- 是 --> E[解析Range范围] D -- 否 --> F[start=0, end=fileSize-1] E --> G[计算Content-Range] F --> G G --> H[设置206状态码] H --> I[创建StreamingResponseBody] I --> J[分块读取文件并写入输出流] J --> K[客户端逐步接收数据] K --> L[支持拖动、暂停、预加载] L --> M[良好播放体验]

五、性能优化建议

为进一步提升视频流服务质量，可考虑以下优化措施：

• 引入缓存层：对热门视频元数据进行Redis缓存
• 启用GZIP压缩（仅适用于非视频主体）
• 配置Tomcat最大连接数与线程池
• 使用Nginx作为反向代理处理静态资源
• 实现ETag与Last-Modified支持条件请求
• 监控流式传输耗时与错误率
• 限制单个IP的并发请求数防止滥用
• 日志记录关键指标如start time, transfer duration
• 异步预加载下一帧关键帧数据
• 结合CDN实现边缘节点缓存