HttpServletResponse 这个东西我在实际项目里几乎天天都要碰。做 Java Web 后端这几年从最早把数据往浏览器页面上塞到后来做文件导出、断点续传、流式接口绕来绕去都绕不开它。很多人一开始学 Servlet 的时候只记住doGet和doPost里能拿到request和response但response到底能干什么、怎么干才是对的其实有不少讲究。这篇文章我就结合自己平时踩过的坑和常用的写法把用 HttpServletResponse 输出响应数据、实现文件下载这两块内容彻底讲透。先说清楚它解决什么问题。HttpServletResponse 是 Servlet 容器给我们封装好的一个响应对象它本质上代表“服务器要发回给客户端的那份 HTTP 报文”。不管你是想返回一段 JSON 给前端还是想返回一个 CSV/PDF/图片文件让用户下载也不管你是想设置状态码、加自定义响应头还是控制浏览器缓存最终都要通过这个对象去操作。换句话说它是整个请求响应链路的“出口”。所以这篇文章适合谁适合刚接触 Servlet 想搞明白 response 用法的初学者也适合写 Spring MVC 但遇到底层响应控制需求、写文件下载时总是中文乱码或文件名不对的开发者。把这套逻辑理清了后面再遇到响应相关的奇奇怪怪问题你至少知道该往哪个方向排查。1. 响应数据的整体设计与核心思路1.1 先理解 HTTP 响应报文的构成在写代码之前得先在脑子里建立一张 HTTP 响应的“地图”。HTTP 响应报文包三部分状态行、响应头、响应体。状态行里最重要的就是状态码比如 200 代表成功404 代表资源不存在500 代表服务器内部错误。响应头是一堆键值对用来告诉浏览器或其他客户端一些元信息常见的有Content-Type告诉对方响应体是什么类型、Content-Length响应体长度、Cache-Control缓存策略、Set-Cookie下发 Cookie。响应体才是真正给客户端消费的数据可以是一段 HTML、一串 JSON、一张图片的二进制内容也可以是一个文件的内容。HttpServletResponse 的操作逻辑和这个结构是严丝合缝对应的setStatus()设置状态码setHeader()设置响应头getWriter()或getOutputStream()获取输出流来写响应体。很多新手一看就懂但真正写起来才发现坑很多比如我在项目里就遇到过明明设置了响应头前端却拿不到明明写入了中文页面上一看全是问号明明是想下载文件结果浏览器直接在标签页里打开了文件内容。这些问题归根结底都是因为没有把 HTTP 响应报文的规则和 Servlet 容器的实现机制结合起来理解。1.2 为什么不直接用框架的封装还要自己操作它有人可能会问现在都用 Spring Boot返回数据直接用RestController 自定义对象框架自动帮你转 JSON文件下载也有各种现成工具为什么还要研究 HttpServletResponse我的看法是框架的封装解决的是 90% 的常规场景但总有一些场景得回到这个底层接口。比如你需要在同一个接口里同时输出多种类型的数据需要在响应过程中动态决定是否要改变状态码需要自己控制下载时的断点续传需要实现像 SSEServer-Sent Events那样边生成边推送的流式响应——这些场景下框架的封装反而成了阻碍你必须直接操作 HttpServletResponse 才能做到精确控制。更重要的是Spring MVC 的ResponseEntity、ResponseBody底层本质上还是把数据写入到了 HttpServletResponse只是帮你封装好了转换逻辑和状态码设置。理解了底层实现你在遇到“接口响应不对但就是找不到原因”的时候才能跳出框架层面的迷雾直接定位到 HTTP 协议层面的问题。2. 响应数据核心细节与实操要点2.1 状态码、响应头、响应体三件套操作 HttpServletResponse最基本的就是这三件事。状态码用setStatus(int)来设置比如response.setStatus(201)表示创建成功。但更多时候你可能要用sendError(int, String)这个方法比较特殊它不只是设置状态码还会生成一个默认的错误页面并且在调用后容器会清空当前缓冲区后续再往 response 里写内容通常也不再生效。我一开始没搞懂这个区别在代码里先sendError(400)然后又调用getWriter().write(错误信息)结果客户端只能看到容器默认的错误页我自己写的错误信息完全没输出。后来才明白如果只是想把状态码改掉、同时还要自己输出一段错误详情应该用setStatus而不是sendError。响应头是另一个高频操作点。setHeader(String name, String value)设置一个键值对如果这个头已经存在新值会覆盖旧值addHeader则是在原值后面追加适合Set-Cookie、Vary这类允许出现多次的响应头。还有几个便捷方法setContentType(String)实际上是在设置Content-Type头setCharacterEncoding(String)设置字符编码setContentLength(int)设置Content-Length头。我个人的使用习惯是能用专门方法就用专门方法语义更清晰也避免自己拼字符串出错。比如设置 JSON 响应就是response.setStatus(200); response.setContentType(application/json); response.setCharacterEncoding(UTF-8); response.getWriter().write({\name\:\张三\});这里有一个非常关键的点字符编码必须在获取 Writer 之前设置。因为getWriter()返回的 Writer 已经根据当时的字符编码创建了一旦拿到 Writer 再改编码之前已经编码的内容不会重来可能导致输出内容新旧编码混用。类似地setContentType也建议在获取输出流之前就调好。在项目里遇到“我用 UTF-8 设置编码了为什么还是乱码”十有八九是在getWriter()之后才去设置编码。2.2 getWriter() 和 getOutputStream() 到底选谁这是 HttpServletResponse 最容易踩坑的地方。Servlet 规范规定在同一个响应中getWriter()和getOutputStream()只能调用其中一个如果你先调用了getWriter()再去调getOutputStream()容器会抛出IllegalStateException反过来也一样。这两个方法的核心区别在数据类型getWriter()返回一个PrintWriter是字符流适合输出文本内容比如 HTML、JSON、XMLgetOutputStream()返回ServletOutputStream是字节流适合输出二进制内容比如图片、PDF、Excel 文件。那有人会问JSON 能用字节流输出吗可以但你需要自己把字符串转成字节数组再写而且还要手动指定编码。所以通常情况下文本内容用 Writer二进制内容用 OutputStream这个原则能帮你避开绝大多数选择困难。我在实际开发里的选择逻辑是这么定的如果我要输出的数据是一个字符串或者是一个可以被序列化成字符串的对象典型的就是 JSON 字符串就用getWriter()然后配合setCharacterEncoding(UTF-8)如果我要输出的是文件流、图片流、或者其他读取到的输入流就用getOutputStream()用 byte 数组做缓冲循环写入。这里有个容易忽略的细节PrintWriter的write(String)方法本身不会抛 IOException它是把异常吞掉了要用checkError()才能检查输出是否出错。所以在比较严谨的框架代码里输出大量数据之后会主动调用checkError()来判断一下是否有传输异常。2.3 缓冲区、flush 和容器提交响应的时机HttpServletResponse 背后是有缓冲区的。你在代码里写的数据不会立刻发到客户端网络连接上而是先写入缓冲区满了或者你主动flush()容器才把数据真正发送出去。这个机制设计的初衷是性能减少网络 I/O 次数。但它也带来一个副作用响应头一旦通过网络发送出去就永远不能修改了。所以你会看到很多 Servlet 教程里反复强调“必须在写响应体之前设置响应头”原因就在这里。用生活化的比喻响应头是你寄快递时填的运单信息响应体是包裹里的东西。你可以在装包裹的时候反复修改运单内容但一旦把运单贴好、包裹交给快递员再想改就来不及了。在代码里getOutputStream().flush()就是“把包裹交给快递员”的那个动作。所以如果你的业务逻辑是先输出一部分数据又根据后续结果决定要不要改状态码或响应头——那基本是行不通的除非把输出全部缓冲在内存里最后一次性决定状态和头信息。我遇到过某些大文件下载接口因为是边读边写输出流中途发现文件读取异常想返回一个 500 错误但前面一部分数据已经发出去状态码已经定了只能中断连接客户端会收到一个不完整的响应。这个问题在设计接口时就要提前规避最好先校验好所有可能失败的环节再开始正式输出。关于flush()我还有一个经验写大数据量的时候主动分批次 flush能显著提升用户体验。比如在输出一个几 MB 的文件时如果你一直不 flush浏览器可能长时间处于等待状态进度条一动不动但如果你每写一段就 flush 一次客户端能实时看到下载进度体验会好很多。当然也不能频繁极端地 flush否则网络小包太多反而拖慢速度。实际项目里我一般设置 8KB 或 16KB 的缓冲每写完一个缓冲大小就 flush 一次。3. 文件下载完整流程、中文文件名和断点续传3.1 下载在 HTTP 层面到底发生了什么很多刚接触的人以为下载文件就是从服务器读文件、往 response 输出流里写数据只要把文件读出来写进去就完事了。但如果真这么干你会发现浏览器并不会下载文件而是直接打开了一个乱码页面或者直接在页面上展示文件内容。这就是因为你没有告诉浏览器这是一个附件请把它当成文件保存下来而不是在页面里渲染。这个关键就在Content-Disposition响应头。当它的值是attachment; filenamexxx时浏览器收到响应后会弹出下载框或者在静默策略下直接保存到下载目录如果它的值是inline浏览器就会尝试在当前页面渲染内容。默认情况下如果你没设置这个头浏览器会根据Content-Type推测处理方式比如一个 PDF 且类型是application/pdf浏览器很可能直接打开 PDF 预览而不是下载。所以实现文件下载的标准姿势是这样的设置Content-Type为文件的 MIME 类型设置Content-Disposition为attachment设置Content-Length让浏览器能显示下载进度然后通过getOutputStream()把文件字节流写出去。代码骨架大概是File file new File(/path/to/file/template.xlsx); response.setContentType(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet); response.setHeader(Content-Disposition, attachment; filename\template.xlsx\); response.setContentLengthLong(file.length()); try (InputStream in new FileInputStream(file); OutputStream out response.getOutputStream()) { byte[] buffer new byte[8192]; int len; while ((len in.read(buffer)) ! -1) { out.write(buffer, 0, len); } }这里我用了setContentLengthLong而不是setContentLength因为setContentLength只接受 int 参数万一文件超过 2GBint 溢出就会出错。实际项目里大文件不常见但这是长期养成的习惯顺手就写对了。3.2 中文文件名的编码坑一坑接一坑文件下载最热闹的战场就是中文文件名。你设置了Content-Disposition里filename年度报表.xlsx然后发现浏览器下载下来的文件名是乱码甚至干脆报错。这背后的原因要从 HTTP 头的编码规则说起HTTP 头默认只允许 ASCII 字符中文属于非 ASCII 字符直接放进响应头里并不规范不同浏览器对此处理方式完全不同。常见的解决办法是把中文文件名做 URL 编码也就是URLEncoder.encode(filename, UTF-8)然后设置成filenamefilename这个方案在绝大多数现代浏览器上是兼容的。后来规范又有了一个更正确的做法用filename*参数格式是filename*UTF-8URL编码后的文件名这解决了老方案在部分浏览器上解析不规范的问题。但现实比规范复杂老版本的浏览器不认filename*只认filename新版本浏览器遇到同时存在filename和filename*时优先认filename*。所以我项目里的做法是两条都写上String encodedName URLEncoder.encode(fileName, UTF-8).replaceAll(\\, %20); response.setHeader(Content-Disposition, attachment; filename\ encodedName \; filename*UTF-8 encodedName);这里有个很小但是致命的细节URLEncoder.encode会把空格转成加号而标准 URL 编码里空格应当编码成%20所以在拼接进Content-Disposition之前要把加号替换掉否则文件名里如果带了空格浏览器解析时可能会把当成一个字面字符导致下载下来的文件名多出一个加号。这个细节我在项目中修过一次排查了半天最后抓包才发现文件名里的空格变成了。另外要提一下attachment后面那个filename参数IE 时代它要求文件名必须用双引号包起来现代浏览器对这个要求不严格但为了兼容旧环境我还是习惯用双引号包住文件名值。如果文件名特别长有些浏览器还有长度限制我记得某旧版本浏览器对Content-Disposition整个头的长度有限制太长的文件名会被截断甚至导致下载失败所以如果文件名是用户随意输入的超长文本可以考虑截断处理或者用固定规则重命名文件。3.3 不用框架实现断点续传的核心逻辑如果只是写一个简单的下载接口上面的代码已经够用了。但现实项目中经常遇到大文件下载中断的情况用户按了暂停或者网络闪断如果从头再来体验很差。这时候就要支持 Range 请求头也就是 HTTP 协议里的断点续传。原理是这样的客户端发起下载时在请求头里带上Range: bytes100-199意思是“我从第 100 个字节开始要一直要到我指定的结束位置或者到文件结束”。服务器收到这个请求后如果支持分段下载就应该响应状态码 206 Partial Content并且设置Content-Range响应头告诉客户端当前返回的是文件的哪一段然后从指定位置开始读取文件字节流而不需要从头遍历整个文件。在 HttpServletResponse 里的实现思路也很清晰。先从请求头里取出Range如果没有就直接走全量下载如果有就按规则解析起止字节然后通过RandomAccessFile或者FileChannel定位到对应位置再循环读取输出。这里我写一个去掉边界处理的简化版本但核心逻辑都在long fileSize file.length(); String rangeHeader request.getHeader(Range); if (rangeHeader null || !rangeHeader.startsWith(bytes)) { // 全量下载 } else { String[] range rangeHeader.substring(6).split(-); long start Long.parseLong(range[0]); long end (range.length 1 range[1].length() 0) ? Long.parseLong(range[1]) : fileSize - 1; long length end - start 1; response.setStatus(206); response.setHeader(Content-Range, bytes start - end / fileSize); response.setContentLengthLong(length); try (RandomAccessFile raf new RandomAccessFile(file, r)) { raf.seek(start); byte[] buffer new byte[8192]; long remaining length; int len; while (remaining 0 (len raf.read(buffer, 0, (int) Math.min(buffer.length, remaining))) ! -1) { response.getOutputStream().write(buffer, 0, len); remaining - len; } } }这个实现看着不难坑基本都在 Range 头的边界条件上。比如客户端可能发Range: bytes0-0只请求第一个字节可能发Range: bytes-100表示倒数 100 个字节可能发Range: bytes100-表示从 100 字节到最后还有可能发多段 Range 比如bytes0-100,200-300——这种多段 Range 响应需要用到 multipart/byteranges 格式复杂度会更高。在真正的项目里如果完整支持所有 Range 情况是很繁琐的所以我通常的做法是先支持最常用的单段 Range对多段 Range 直接忽略按全量下载返回。这不是偷懒而是绝大多数下载工具和浏览器实际只会发送单段 Range 请求。关于断点续传还有一个重要配套头Accept-Ranges。如果服务器支持 Range 请求应当在响应里加Accept-Ranges: bytes这样客户端才知道可以发分段请求。在文件下载接口上这个响应头应该是标配。3.4 文件下载的 MIME 类型与内容类型表既然下载要设置Content-Type那文件类型和 MIME 的映射就得掌握。有些开发者偷懒所有文件下载都设置成application/octet-stream这是“未知二进制流”类型浏览器收到了会当作文件下载但用户体验并不好因为浏览器没法判断点击后是该用哪款应用打开有些 PDF 识别不了。更合理的做法是针对已知类型设置明确的 MIME 类型这样浏览器可以对它熟悉的类型做预览或者选择合适的默认程序打开。我整理了日常用的几个高频映射直接背下来即可。文本文件是text/plainHTML 是text/htmlJSON 是application/jsonXML 是application/xml普通图片是image/jpeg、image/png、image/gifPDF 是application/pdf老版 Excel 是application/vnd.ms-excel新版 Excel 是application/vnd.openxmlformats-officedocument.spreadsheetml.sheet新版 Word 是application/vnd.openxmlformats-officedocument.wordprocessingml.documentZIP 压缩包是application/zip。还有一个容易搞混的如果拿不准就用application/octet-stream兜底浏览器至少能正常下载只是没有预览能力。其实在 Servlet 规范的较新版本里容器本身提供了一些 MIME 映射能力可以调用servletContext.getMimeType(fileName)来获取文件对应的 MIME 类型。这个方法内部查表比自己写一个 Map 硬编码靠谱所以我在项目里的选择是优先用getMimeType获取如果返回空再手动兜底为application/octet-stream。这样既省了维护映射表的事又能覆盖最常见的文件类型。4. 常见问题与排查技巧实录4.1 响应中文乱码定位编码链路的断点中文乱码是 HttpServletResponse 使用中出现频率最高的问题没有之一。我把它分成几种情况来排查。第一种是响应体内容里有中文前端拿到后乱码。这种情况通常是响应头里的Content-Type和实际写入的字节编码不一致。比如你设置了text/html但没有设置charsetUTF-8那么很多浏览器默认会用 ISO-8859-1 去解码中文自然就乱了。解决方式很简单response.setContentType(text/html;charsetUTF-8)或者分别调用setContentType和setCharacterEncoding。要注意setContentType的字符串里 charset 的拼写必须正确我见过有人写成charsetutf8有些容器可以容忍有些则不会识别宁可写标准写法UTF-8。第二种情况是用getOutputStream()写字符串比如response.getOutputStream().write(中文.getBytes())这个方法容易踩坑的点是你调用getBytes()时没有指定编码Java 会用平台默认字符集通常是 UTF-8在 Windows 上可能是 GBK。如果这台服务器的默认字符集和你在Content-Type里声明的不一样就会导致乱码。所以用字节流写字符串必须写成中文.getBytes(UTF-8)或者直接用getWriter()写。我建议文本内容一律用getWriter()让容器帮你处理编码减少这类低级错误。第三种情况是下载文件名乱码我在上面已经讲过原理是 HTTP 头不支持非 ASCII 字符必须 URL 编码。排查的时候判断标准就是抓包看响应头里Content-Disposition的值如果直接看到了中文汉字说明你漏了编码如果看到的是%E5%B9%B4%E5%BA%A6这种百分号编码那基本是正常的。4.2 响应头设置“失效”的真正原因我遇到过几次特别诡异的情况代码里明明设置了自定义响应头response.setHeader(X-Token, abc)前端通过getResponseHeader(X-Token)拿到的却是 null。排查了好一阵子才发现原因是在业务代码里无意中调用了一次response.sendRedirect()或者response.sendError()这两个方法会先清空响应头再发起重定向或错误响应。所以如果发现响应头没生效先检查代码里有没有调用过 sendRedirect、sendError 或 reset 系列方法。还有一种常见原因是代理服务器或网关把响应头过滤了。比如有些企业防火墙会过滤Content-Disposition这种和下载相关的头有些反向代理会对包含下划线的自定义头做丢弃处理具体取决于代理配置。在项目里遇到“我在本地测没问题上了测试环境响应头就没了”的情况优先怀疑中间链路用curl -v直接请求目标接口看返回的头信息就能判断是应用层的问题还是代理层的问题。4.3 下载完文件后文件损坏、大小不对文件下载接口最常见的另一种故障现象是文件能下来但打不开或者文件大小和服务器原文件不一致。这个问题的根因往往是响应体中混入了额外的数据或者输出过程中有数据丢失。先说不完整的情况。用循环read()写入时很多人会犯一个低级错误out.write(buffer)而不是out.write(buffer, 0, len)。因为最后一次读取可能不足 8192 字节如果直接写入整个 byte 数组就会把上次残留的垃圾数据也写进去。这个错误我早年犯过一次当时生成 Excel 文件每次大小都不对非常隐蔽。所以写文件流的时候务必用write(buffer, 0, len)。再说混入额外数据的情况。如果在调用getOutputStream()之后代码里又有个getWriter()或者不经意间调用了response.getWriter().write(...)就会抛出异常或者导致输出流中混入字符。还有框架层面的问题如果你的接口在一个拦截器或者过滤器里在业务代码执行之后又往响应里追加了内容比如日志切面在 finally 里调用了response.getWriter()就会破坏文件流的完整性。排查这个问题的办法是抓包对比原始文件字节数和响应体字节数。4.4 文件不存在或权限不足的异常处理下载接口中文件路径是用户可传的就得考虑文件不存在的场景。一个常见的错误是在输出流已经打开之后才发现文件不存在然后尝试往 response 里写错误信息这时候如果你已经写了一些字节状态码就已经定了前面也讲了写也是白写。所以正确顺序应该是先检查文件是否存在、是否可读再设置响应头再打开输出流。如果文件确实不存在建议用response.sendError(HttpServletResponse.SC_NOT_FOUND)返回 404。但要注意sendError会清空缓冲区并生成容器默认错误页如果你想让前端收到一个自定义结构的错误 JSON就不能用sendError应该用setStatus(404)然后自己写一段 JSON。这两种方式没有绝对的对错看团队和项目约定但前提是搞清楚二者行为差异再选。另外涉及文件读取时一些项目用了尝试访问不存在路径的方式去判断文件类型或获取文件名也会触发异常这类问题建议在入口就统一封装返回一个项目约定的业务错误码。4.5 嵌入式容器下 response 对象的线程与资源管理在多线程并发环境下HttpServletResponse 本身是线程不安全的但这不代表你需要加锁——因为每个请求都有自己独立的 response 对象Servlet 容器已经帮你隔离了。真正需要关心的是流资源的管理在使用getInputStream()读文件、getOutputStream()写响应的时候要确保流最后被关闭特别是文件读取流否则会出现文件句柄泄漏。但这里有一个微妙之处response.getOutputStream()返回的ServletOutputStream是否应该显式关闭我的习惯是业务代码里不主动关闭它因为容器在请求结束后会负责清理和刷新剩余缓冲但如果你用 try-with-resources 包裹了它你调用close()也不会出大问题容器会有相应的处理。比较推荐的做法是文件输入流自己关闭输出流交给容器管理你只负责 flush 缓冲区。如果写代码时使用了包装流比如 BufferedOutputStream包装流的 close 会触发底层流的 close所以要注意别把 response 的输出流给意外关了导致后续框架无法再写内容。在实际项目中我见过过滤器在请求结束之后想给响应追加一段内容结果因为业务代码已经关了输出流导致追加失败这种问题排查起来很费神。5. 响应处理的其他常见应用场景缓存、压缩和跨域5.1 用响应头控制浏览器缓存响应数据时我们有时希望浏览器把结果缓存起来减少重复请求有时又希望完全不缓存防止用户看到旧数据。这些都需要通过响应头来控制。HttpServletResponse 没有专门的缓存 API但我们可以通过setHeader或者setDateHeader来实现。比如一个不经常变化的静态数据接口可以设置Cache-Control: max-age3600意思是浏览器在 3600 秒内可以直接使用本地缓存不再向服务器发起请求。如果需要强制重新验证则用no-cache注意no-cache不是“不缓存”而是“缓存前必须向服务器确认”。真正禁止缓存需要设置Cache-Control: no-store。还有个Expires响应头是 HTTP/1.0 时代的产物设置一个绝对过期时间现在基本被Cache-Control替代但部分老客户端仍然看它。我一般在涉及动态数据的接口上会写response.setHeader(Cache-Control, no-store); response.setHeader(Pragma, no-cache); response.setDateHeader(Expires, 0);这是三层兜底把老浏览器、现代浏览器和代理服务器都覆盖上。接口返回实时数据的时候少了这几行用户刷新页面看到的数据可能还是旧的造成“接口没生效”的假象。5.2 压缩输出Gzip 在响应处理中的应用文本类响应数据HTML、JSON、CSS压缩收益非常明显可以减少网络传输体积。Java 里通过GZIPOutputStream包装ServletOutputStream就能实现。但这里有一个关键坑你用了压缩输出流之后就不应该再设置静态的Content-Length因为长度会变正确做法是让容器使用 chunked 编码也就是不设置 Content-Length让容器在数据传输完之前无法预知总长度。如果手动设置了 Content-Length 还是原来的大小浏览器就会按这个长度去读取数据会发生截断或错乱。我在一个项目里做过一次压测一个 1MB 的 JSON 响应开启 Gzip 后大小能降到 100KB 左右接口耗时明显下降。但也要注意不是所有响应都适合压缩图片、视频、ZIP 这些本来已经压缩过的二进制内容再压一遍白费 CPU。所以压缩逻辑一般都会根据Content-Type或者Accept-Encoding来做条件判断。使用 Gzip 时还有一个注意点要配合请求头Accept-Encoding: gzip来启用如果客户端不支持 gzip你强行返回 gzip 内容客户端会直接乱码或者解析失败。判断方法就是用request.getHeader(Accept-Encoding)检查。因为压缩属于对响应数据的加工很多框架比如 Spring Boot 的 server.compression.enabled已经内置了压缩能力但如果你自己在 Servlet 层面处理上面的这些细节还是要知道。5.3 跨域响应头的设置思路当前后端分离之后跨域问题成了响应处理的常客。当页面在 A 站点接口在 B 站点浏览器会因为同源策略拦下响应。这时候就需要在响应头里加上跨域相关的字段Access-Control-Allow-Origin是最核心的表示允许哪些源访问如果是携带 Cookie 的请求还需要Access-Control-Allow-Credentials: true同时Access-Control-Allow-Origin不能是*必须是明确的源地址。用 HttpServletResponse 来设置跨域响应头并不复杂response.setHeader(Access-Control-Allow-Origin, https://example.com); response.setHeader(Access-Control-Allow-Credentials, true); response.setHeader(Access-Control-Allow-Methods, GET, POST, PUT, DELETE, OPTIONS); response.setHeader(Access-Control-Allow-Headers, Content-Type, Authorization);比较麻烦的是预检请求。浏览器在实际跨域请求之前会先发一个OPTIONS请求来询问服务器是否允许跨域如果这个OPTIONS请求没有得到正确响应后续的真实请求根本不会发出。所以在 Servlet 里处理跨域需要单独判断OPTIONS方法并设置上述响应头然后返回状态 200。这个逻辑在过滤器里实现比较合适能统一处理所有接口。当然如果你用了 Spring 框架有CrossOrigin注解和全局跨域配置实现方式更多但原理还是这些。5.4 动态文件生成的半流式输出最后分享一个实际项目里很有用的技巧如果下载的文件不是预先存在磁盘上的静态文件而是由内存中的对象动态生成的比如生成 Excel、CSV你就不应该把全部内容先拼装成一个字符串或字节数组再写出去那样内存占用会随着数据量线性增长。正确姿势是通过输出流边生成边写。以导出 CSV 为例先是创建OutputStreamWriter和BufferedWriter来包装response.getOutputStream()然后每生成一行数据就写一行写完调用 flush。这样即使有几十万行数据内存里始终只保留当前这一行的内容响应能很快开始传输浏览器也能看到下载进度。同样的思路可以用在动态生成 PDF、Excel 2003 格式 XML 文件等场景。这套写法的好处是响应时间和内存占用都得到优化。我记得有一次上线了一个导出接口最初的做法是先用 List 把所有数据查出来再循环拼接字符串最后一次性写入输出流。几个人的数据量看不出问题放到几十万行时接口直接 OOM。改成边查边写、边写边 flush 之后问题就消失了。这其实已经不是文件下载本身的问题而是整个响应数据设计思维的问题不要总想着把所有东西攒齐了再发出去对于大体积响应流式处理才是正解。 ## 6. 几个我自己常用的调试技巧 讲完原理和实战最后分享几个让调试效率提升不少的习惯。 第一个是抓包。写完响应相关代码不确定响应头是否正确不要只在浏览器控制台看建议用抓包工具或者 curl -v 看原始报文。浏览器开发者工具在有些情况下会把响应头做一定程度的归一化或隐藏原始报文才是最可靠的。之前排查 Content-Disposition 中文文件名问题用 curl -v 一眼就看到了编码前的原始值问题立刻定位了。 第二个是区分容器层错误和业务层错误。在浏览器里看到一个 500 错误页不一定是你的 Servlet 抛的也可能是在容器解析响应时发现你写入了非法字符或非法响应头。遇到这种报错先看容器日志栈顶是不是 IllegalStateException很可能是你调用了错误的响应方法。 第三个建议是写一个小的本地 Demo 项目专门用来测试各种响应行为。我在本地维护着一个简单的 Servlet 项目里面有各种响应测试端点文本、JSON、CSV、文件下载、断点续传、Gzip 输出、跨域每次遇到响应相关的问题都可以在那个项目里快速复现。这比每次都要起一个完整业务系统去调试要快得多。 HttpServletResponse 本质不复杂它最大的难度在于它和 HTTP 协议、Servlet 容器生命周期、浏览器行为三者深度耦合。你平时写代码时看到的几行 setHeader 和 getWriter背后其实藏着很多协议层面的约定。把响应报文的结构记在心里再理解容器提交响应的时机大多数问题都能迎刃而解。如果文章里的某段代码恰好帮你解决了一个实际问题那这篇文章的价值就达到了。