1. 问题现象与背景分析
最近在Spring Boot项目中遇到一个典型的技术冲突：当同一个Controller方法需要同时支持文件下载和JSON响应时，系统会出现难以预料的行为异常。具体表现为：
- 当请求头
Accept: application/json时，文件下载功能失效 - 当请求头
Accept: */*时，JSON响应格式错误 - 部分客户端（如Postman）能正常工作，但浏览器端出现乱码
这种问题在需要根据请求参数动态返回不同内容类型的API中尤为常见。例如电商平台的"导出订单"功能，可能需要在同一端点支持：
- 网页端查看订单详情（JSON格式）
- 导出Excel报表（文件下载）
2. 底层原理剖析
2.1 Spring MVC的内容协商机制
Spring Boot通过ContentNegotiationManager处理内容协商，其核心决策流程如下：
- 检查URL路径后缀（如
.json） - 解析
Accept请求头 - 使用默认配置（通常优先JSON）
关键问题在于：文件下载需要application/octet-stream类型，而REST API通常配置为优先返回JSON。
2.2 HttpMessageConverter的工作机制
Spring使用转换器链处理响应体，常见转换器优先级：
ByteArrayHttpMessageConverter（字节数组）StringHttpMessageConverter（字符串）MappingJackson2HttpMessageConverter（JSON）
当方法返回值为ResponseEntity<byte[]>时，可能被错误地交给JSON转换器处理。
3. 解决方案对比
3.1 方案一：强制响应类型
java复制@GetMapping("/download")
public ResponseEntity<?> download(@RequestParam String type) {
if ("file".equals(type)) {
return ResponseEntity.ok()
.contentType(MediaType.APPLICATION_OCTET_STREAM)
.header("Content-Disposition", "attachment")
.body(fileBytes);
} else {
return ResponseEntity.ok(jsonData);
}
}
优点：简单直接
缺点：违背RESTful设计原则，需手动维护类型判断
3.2 方案二：内容协商配置
java复制@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
configurer.strategies(List.of(
new HeaderContentNegotiationStrategy(),
new ParameterContentNegotiationStrategy(
Map.of("json", MediaType.APPLICATION_JSON,
"file", MediaType.APPLICATION_OCTET_STREAM))
));
}
}
优点：符合REST规范
缺点：客户端必须显式指定格式参数
3.3 方案三：双端点设计
java复制@GetMapping(value = "/data", produces = "application/json")
public Data getData() { /*...*/ }
@GetMapping("/data/file")
public ResponseEntity<byte[]> exportData() { /*...*/ }
最佳实践：推荐方案，符合单一职责原则
4. 生产环境解决方案
4.1 完整实现示例
java复制@RestController
@RequestMapping("/api/orders")
public class OrderController {
@GetMapping(produces = MediaType.APPLICATION_JSON_VALUE)
public Page<Order> listOrders(Pageable pageable) {
return orderService.findAll(pageable);
}
@GetMapping(path = "/export",
produces = MediaType.APPLICATION_OCTET_STREAM_VALUE)
public ResponseEntity<Resource> exportOrders(
@RequestParam String format,
HttpServletResponse response) {
ByteArrayResource resource = orderService.exportToExcel();
return ResponseEntity.ok()
.header(HttpHeaders.CONTENT_DISPOSITION,
"attachment; filename=orders.xlsx")
.contentLength(resource.contentLength())
.contentType(MediaType.parseMediaType(
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"))
.body(resource);
}
}
4.2 关键配置项
- 禁用默认后缀匹配：
properties复制spring.mvc.contentnegotiation.favor-path-extension=false
- 自定义消息转换器顺序：
java复制@Bean
public HttpMessageConverters customConverters() {
return new HttpMessageConverters(
false, Arrays.asList(
new ByteArrayHttpMessageConverter(),
new MappingJackson2HttpMessageConverter()
));
}
5. 常见问题排查
5.1 浏览器下载文件变成乱码
原因：缺少Content-Disposition头或MIME类型错误
解决方案：
java复制.headers()
.add("Content-Disposition", "attachment; filename=report.xlsx")
.contentType(MediaType.parseMediaType("application/vnd.ms-excel"))
5.2 Postman能下载但浏览器不行
诊断步骤：
- 检查响应头
Content-Type是否正确 - 验证
Accept请求头是否包含*/* - 测试禁用浏览器缓存（开发者工具Network面板勾选Disable cache）
5.3 大文件下载内存溢出
优化方案：
java复制@GetMapping("/large-file")
public StreamingResponseBody downloadLargeFile() {
return outputStream -> {
try (InputStream is = new FileInputStream(path)) {
IOUtils.copy(is, outputStream);
}
};
}
6. 性能优化建议
-
使用
ResponseEntity<Resource>替代byte[]：- 避免内存中保存完整文件
- 支持文件系统资源直接传输
-
分块传输编码配置：
properties复制server.servlet.encoding.chunked=true
- 异步处理大文件：
java复制@Async
public CompletableFuture<Resource> asyncExport() {
// 长时间运行的任务
}
7. 测试策略
7.1 单元测试示例
java复制@Test
void shouldReturnJsonWhenAcceptHeaderIsJson() throws Exception {
mockMvc.perform(get("/api/data")
.header("Accept", "application/json"))
.andExpect(status().isOk())
.andExpect(content().contentType(MediaType.APPLICATION_JSON));
}
@Test
void shouldReturnFileWhenQueryParamIsFile() throws Exception {
mockMvc.perform(get("/api/data?format=file"))
.andExpect(status().isOk())
.andExpect(content().contentType(MediaType.APPLICATION_OCTET_STREAM))
.andExpect(header().exists("Content-Disposition"));
}
7.2 集成测试要点
- 测试不同
Accept头组合 - 验证大文件传输的完整性（MD5校验）
- 模拟网络中断时的连接恢复
8. 高级场景处理
8.1 动态内容类型协商
实现ContentNegotiationStrategy自定义策略：
java复制public class CustomContentNegotiationStrategy implements ContentNegotiationStrategy {
@Override
public List<MediaType> resolveMediaTypes(NativeWebRequest request) {
if (request.getParameter("export") != null) {
return List.of(MediaType.APPLICATION_OCTET_STREAM);
}
return List.of(MediaType.APPLICATION_JSON);
}
}
8.2 多部分文件下载
处理ZIP打包下载：
java复制@GetMapping("/multi-export")
public ResponseEntity<Resource> exportMultiple(
@RequestParam List<Long> ids) throws IOException {
ByteArrayOutputStream baos = new ByteArrayOutputStream();
try (ZipOutputStream zos = new ZipOutputStream(baos)) {
for (Long id : ids) {
Resource file = generateFile(id);
zos.putNextEntry(new ZipEntry(id + ".pdf"));
StreamUtils.copy(file.getInputStream(), zos);
zos.closeEntry();
}
}
ByteArrayResource resource = new ByteArrayResource(baos.toByteArray());
return ResponseEntity.ok()
.header("Content-Disposition", "attachment; filename=export.zip")
.contentType(MediaType.parseMediaType("application/zip"))
.body(resource);
}
在实际项目中，我推荐采用方案三的双端点设计。这种方案虽然需要定义两个方法，但职责清晰，兼容性好，且易于扩展。特别是在微服务架构下，当需要为文件下载单独做负载均衡或CDN加速时，独立端点的优势会更加明显。