HttpServletRequest读取POST body：getInputStream、乱码与缓存一次说清

简介在Java Web应用开发中获取POST请求Body内容是常见需求而Body参数无名无键无法用getParameter直接读取。这份PDF资料围绕HttpServletRequest从底层IO流读取Body的方法展开重点讲解getInputStream与BufferedReader组合读取、读取顺序对QueryString参数的影响、以及必须先于getParameter调用等易错环节并配有可直接参考的Java示例代码适合中初级Java开发者解决接口联调与前后端数据解析问题。包体为1个PDF文件整体仅38KB轻量便携方便随时对照查阅。目前已有34465人学习是同类技巧中热度较高的实用参考。资料虽短但直击“POST Body取不到值”的根因能帮助读者避开常见坑点在业务中稳妥获取JSON等请求体数据。1. 从HttpServletRequest里拿POST body先想清楚这三件事一个很典型的场景你的接口文档里写着POST application/json客户端确实把数据发过来了可到了Java这边request.getParameter(name)拿到的是null。搜了一圈才知道POST body根本不在parameter里得自己从HttpServletRequest的输入流里读。这个需求看起来只差几十行代码但踩过的人都知道里面有InputStream只能读一次的限制、Content-Type不同解析方式不同、中文编码还会临时跳出来搅局。这篇就把从HttpServletRequest里读POST body的完整套路、边界和坑一次讲清楚适合正在写Servlet/Filter/拦截器的Java开发也适合面试前快速过一遍这道常见基础题。2. 直接读bodygetInputStream()与getReader()怎么选2.1 为什么JSON body在getParameter()里是nullServlet容器只帮你解析一种POST格式application/x-www-form-urlencoded。只有这种表单提交你才能直接用request.getParameter(name)拿到值。至于JSON、XML、纯文本、甚至二进制流容器只负责把body原封不动塞进输入流解析由你自己做。这就是很多人第一次卡住的原因。客户端明明在body里放了一段JSON你却在getParameter()里找自然什么都找不到。换个角度理解HttpServletRequest把body的读取权交给你但它没有义务替你猜里面是什么格式。另外还有个隐藏规则一旦调用了getParameter()或者getParameterMap()容器会趁机把body解析掉一部分如果后面的代码再去getInputStream()很可能读出来是空的。所以读body这件事最好放在所有参数操作之前。2.2 最稳的写法getInputStream()按字节读手动指定UTF-8先给一个不依赖任何框架、放到Servlet里就能跑的最小实现WebServlet(/api/echo) public class EchoServlet extends HttpServlet { Override protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException { // 1. 从输入流里把body完整读成字节数组 byte[] bodyBytes readRequestBody(req.getInputStream()); // 2. 显式按UTF-8解码不要用 new String(bytes) 偷懒 String body new String(bodyBytes, StandardCharsets.UTF_8); resp.setContentType(text/plain;charsetUTF-8); resp.getWriter().write(received: body); } private byte[] readRequestBody(InputStream input) throws IOException { ByteArrayOutputStream output new ByteArrayOutputStream(); byte[] buffer new byte[4096]; int len; while ((len input.read(buffer)) ! -1) { output.write(buffer, 0, len); } return output.toByteArray(); } }这段代码的逻辑是开一个ByteArrayOutputStream接收数据用4096字节的缓冲区循环从输入流里取数据直到read()返回-1表示流结束。缓冲区大小的核心参数是4096它不是必须值开1KB到8KB都常见主要作用是减少IO次数。对于绝大多数JSON接口body通常不超过几百KB这个写法完全够用。第2步的new String(bodyBytes, StandardCharsets.UTF_8)是关键。getInputStream()返回的是原始字节流它不知道这段body是UTF-8、GBK还是什么编码你必须显式告诉它。如果省略字符集JVM会用平台默认编码在Windows开发和Linux生产环境之间来回切换乱码问题极其容易出现。如果你的服务跑在JDK 9以上可以用更短的写法byte[] bodyBytes req.getInputStream().readAllBytes();readAllBytes()内部做了同样的事把流一次性读干净。但如果你的老项目还在Java 8上跑这行代码直接编译不过去老老实实用上面的循环读法。2.3 getReader()和getInputStream()到底该用哪个网上教程里经常混着用这两个方法其实它们的区别值得对一眼维度getInputStream()getReader()返回类型ServletInputStream字节流BufferedReader字符流编码处理不处理给你原始字节按请求的字符编码解码适合场景二进制、JSON、不确定编码的body确定是文本且编码声明正确的body编码坑需要自己指定charset如果客户端没传charset用默认值解码我一般建议读接口的body统一走getInputStream()。原因很直接很多客户端调用POST接口时只写了Content-Type: application/json没带charsetgetReader()这时候会用什么编码完全看容器心情不如自己拿到字节后统一按UTF-8处理。如果客户端确实用GBK发过来你还可以从req.getCharacterEncoding()拿到声明再手动切换解码方式。2.4 顺手处理一下“body是不是空的”的情况读取之前可以先判断一下req.getContentLength()如果是0说明根本没有body直接返回空字符串省一次流操作。但要注意HTTP协议里body为空并不等于getContentLength()一定是0也可能返回-1表示长度未知。比较稳妥的方式是把body读出来然后看trim()之后是不是空串。3. 常见问题排查流被读空、中文乱码、超大body的五个坑3.1 Filter里提前读了bodyController收到null对象现象你想在Filter里打日志于是先调了一次request.getInputStream()把body读了一遍打印出来的内容是对的。结果请求到了Controller参数对象里的字段全是null或者Service再读一次body直接抛IOException: Stream closed。原因ServletInputStream不是文件流不能rewind也不能reset。它是一次性的你在这头读完那头就已经到EOF了。后续所有代码再getInputStream()都会拿到一个空流甚至直接抛异常。解决不要在Filter里读完就完事把body缓存下来再用包装后的request继续传递。具体做法在下面3.3节给。3.2 读一次就没是Servlet模型的天性不是代码写错很多刚接触的人会反复确认自己是不是方法调错了。其实这是Servlet规范里很自然的模型请求流是“拉取式”的你拉多少它就少多少没有后悔药。Spring MVC里某些场景你会看到ContentCachingRequestWrapper它能让你在日志里看到body内容同时下游也能正常读到数据底层原理就是包装类里做了缓存。想一个问题就明白了GET参数在URL上随便读几遍都行POST body是流读一遍就是一遍。所以涉及到body的操作要么保证只有一个地方读要么把缓存做好。3.3 给request做个包装缓存body之后的读取都从缓存里来在普通Servlet或Filter里最常见的通用做法是写一个HttpServletRequestWrapper的子类在构造时把body一次性读出来存到字节数组里然后重写getInputStream()每次返回的都是缓存数组的新流public class CachedBodyRequestWrapper extends HttpServletRequestWrapper { private final byte[] body; private final String charset; public CachedBodyRequestWrapper(HttpServletRequest request) throws IOException { super(request); // 构造时一次性把原始body读完并缓存 this.body readBytes(request.getInputStream()); // 记录原始请求声明的编码后面getReader()要用 this.charset request.getCharacterEncoding(); } Override public ServletInputStream getInputStream() { ByteArrayInputStream byteIn new ByteArrayInputStream(body); return new ServletInputStream() { Override public int read() { return byteIn.read(); } Override public boolean isFinished() { return byteIn.available() 0; } Override public boolean isReady() { return true; } Override public void setReadListener(ReadListener readListener) { // 同步阻塞读场景不需要留空 } }; } Override public BufferedReader getReader() { Charset cs charset ! null ? Charset.forName(charset) : StandardCharsets.UTF_8; return new BufferedReader(new InputStreamReader(new ByteArrayInputStream(body), cs)); } private byte[] readBytes(InputStream input) throws IOException { ByteArrayOutputStream output new ByteArrayOutputStream(); byte[] buffer new byte[4096]; int len; while ((len input.read(buffer)) ! -1) { output.write(buffer, 0, len); } return output.toByteArray(); } }使用方式是在Filter里包装一次然后让请求继续往下走if (!(request instanceof CachedBodyRequestWrapper)) { request new CachedBodyRequestWrapper(request); } chain.doFilter(request, response);这个包装类的关键参数有两个。一个是body数组它决定了整个request的大小另一个是charset它在重写getReader()时用来解码。如果原始请求声明了charsetGBK这里就必须按GBK来不然又会出现乱码。缓存这个动作放在构造函数里意味着这个Filter是整个链路上第一次读body的地方之后无论Controller还是其他Filter都可以反复读不会再出现“读一次就没了”的翻车现场。3.4 中文乱码new String(bytes)不传charset就是赌博现象日志里出现“锟斤拷”“”之类或者读出来的字符串全是问号。原因body读出来是字节数组字节本身没有编码概念编码是你赋予它的。直接new String(bodyBytes)不传字符集JVM会用操作系统的默认编码。Windows开发机默认GBKLinux服务器默认UTF-8同一套代码在不同环境表现完全不一样。这种问题是最玄学的一类因为它不报错只是内容不对。解决解码时强制指定字符集。优先用req.getCharacterEncoding()如果没声明就按业务约定默认UTF-8。还有一个细节要注意HTTP Header里的charset是客户端声明的它可能写的是错的所以更保险的做法是接口层约定“一律UTF-8”客户端不按约定来就让对方改。3.5 超大body一次readAllBytes()可能直接把内存打满现象接口在某次上传大文件时彻底卡死日志里出现java.lang.OutOfMemoryError: Java heap space。原因body很大时一次性读到字节数组里会干掉一大块堆内存。比如传一个50MB的文件你在Filter里这么一缓存内存里就多出50MB并发一多直接OOM。解决分场景处理。如果body是JSON这类业务数据先做好大小限制比如在Filter里判断Content-Length超过10MB就直接拒绝如果body是大文件上传别用getInputStream()手动读改用getParts()或框架里的multipart处理容器会帮你把文件写进临时目录不会进内存。重复读的包装类也一样只适用于小body大文件场景要格外警惕。4. 按Content-Type分流JSON、表单和multipart各自的读取方式4.1 先拿到Content-Type再决定怎么读别一上来就开流不同Content-Type意味着body里的组织方式完全不同。JSON是个整体字符串表单是键值对流水multipart则是分段数据。拿到请求后先判断类型再走对应分支这是每个写接收POST接口的人都该有的习惯String contentType request.getContentType(); if (contentType null) { // 纯裸请求没有Content-Type按自己的约定处理 } else if (contentType.toLowerCase().contains(application/json)) { // JSON走JSON解析 } else if (contentType.toLowerCase().contains(application/x-www-form-urlencoded)) { // 表单可以直接用getParameterMap() } else if (contentType.toLowerCase().contains(multipart/form-data)) { // 上传走getPart()别手动读流 }这里的toLowerCase()是为了规避客户端把Application/JSON写成大小写混合的边界情况。前端框架一般不会这么坑但第三方回调接口就不好说了。4.2 解析JSON body字符串只是中间态落到对象才算数读到的body如果确定是JSON一般不会直接拿字符串用而是转成对象。最常见的方案是Jackson// ObjectMapper要定义为全局单例它是线程安全的 private static final ObjectMapper OBJECT_MAPPER new ObjectMapper(); PostMapping(/api/user) public User createUser(HttpServletRequest request) throws IOException { byte[] bodyBytes request.getInputStream().readAllBytes(); // 反序列化为User对象 User user OBJECT_MAPPER.readValue(bodyBytes, User.class); return userService.save(user); }readValue有两个参数要重点理解第一个是字节数组或字符串第二个是目标类型。如果接口的JSON结构不知道具体类型可以用readTree()转成JsonNode再取字段比如node.get(name).asText()这适合做转发和校验的中间层。有一点务必记住如果你的服务还在Java 8上这里的readAllBytes()是不能用的要换成前面写过的循环读法。另外body刚读出来如果是空串readValue会抛JsonParseException接口层最好先做一次空body判断再进解析逻辑。4.3 表单场景能用getParameterMap()就别自己解析字符串application/x-www-form-urlencoded格式的body长这样namejavatypepost。这种格式容器已经帮你解析好了直接拿就行MapString, String[] params request.getParameterMap(); String name params.get(name)[0]; String type params.get(type)[0];注意这里的坑getParameterMap()获取的是所有参数但值永远是String[]因为HTTP允许同一个key出现多次比如多选checkbox。自己解析字符串拼参数很容易漏掉这个细节。multipart则完全不同。multipart/form-data格式的body被分成了若干段每段都有自己的Content-Disposition头普通字段和文件混在一起。这时的正确做法是Part filePart request.getPart(file); String fileName filePart.getSubmittedFileName(); // 用getInputStream()从Part里取出文件内容到了multipart场景手动用getInputStream()读整个body会让你怀疑人生。每个Part其实也是一个流容器已经帮你把每段数据切好了你只需要从对应的Part里取数据就可以。这也是java基础面试题里经常被追问的点同样都是POST为什么form表单能getParameter()而文件上传不行。5. 验证读到的body对不对curl、MockHttpServletRequest和一个记录习惯5.1 用curl模拟不同Content-Type的POST确认读取逻辑本地起服务后用curl分别打两种请求能快速验证自己的读取代码# 模拟JSON body curl -X POST http://127.0.0.1:8080/api/echo \ -H Content-Type: application/json;charsetUTF-8 \ -d {name:java,type:post} # 模拟表单body curl -X POST http://127.0.0.1:8080/api/echo \ -H Content-Type: application/x-www-form-urlencoded \ -d namejavatypepost注意这两个请求到达服务端时getContentType()的值不同你写的分支代码会走进不同的解析逻辑。如果返回结果和你预期的不符先打印getContentType()别急着怀疑解析代码。5.2 单元测试里伪造带body的POST请求写单元测试时手动构造MockHttpServletRequest是最快的方式MockHttpServletRequest request new MockHttpServletRequest(); request.setMethod(POST); request.setContentType(application/json;charsetUTF-8); byte[] body {\name\:\java\}.getBytes(StandardCharsets.UTF_8); request.setContent(body); request.setContentLength(body.length);setContent()只负责往request里塞bodysetContentLength()是手动告知内容长度。这两个方法在测试里必须成对出现很多Mock场景下读取结果不对都是因为只set了Content忘了setContentLength。5.3 留一个日志习惯Filter里记录body但限制长度线上排查问题绝大多数时候靠的是日志里的请求内容。我现在写接收POST的接口时会在Filter里统一记录uri、contentType和body并且body超过500个字符就截断避免日志被大请求撑爆。这个习惯帮我在好几起“客户端说发了、服务端说没有”的扯皮里快速定位到问题比事后猜要靠谱得多。前端框架的请求头、代理层配置、服务端读取顺序任何一个环节出问题body都可能变成空。所以我现在的第一个习惯动作永远是先确认Content-Type是什么再确认body有没有被上游Filter提前消费然后才放心去读流。希望帮到你。本文还有配套的精品资源点击获取