记一次微服务架构下的HTTP请求头“大小写”丢失排查之旅

杜劲松2026-06-18 9:51

在最近的微服务排障过程中，业务方反馈了一个诡异的问题：客户端发起请求时，明确携带了驼峰写法的请求头（如 appKey: asd），但请求经过反向代理和网关，到达后端具体的 Spring Boot 业务服务时，业务代码里取出来的请求头全变成了小写（appkey: asd）。

面对这种链路较长的问题，最忌讳的就是靠猜。是 Nginx 做了转换？是 Gateway 的某个 Filter 偷偷改了头？还是 Spring Boot 本身的问题？为了用事实说话，我直接上 tcpdump 和 Wireshark，在链路的各个节点进行了分段抓包。

测试环境拓扑与机器信息

在开始抓包前，我们需要明确当前测试环境的具体流量拓扑和节点的 IP、端口信息。根据排查梳理，当前链路如下：

  • 客户端 (Postman) ：IP 10.20.4.84
  • Nginx (反向代理) ：IP 10.100.38.11，对外暴露端口 9009
  • Spring Cloud Gateway (网关) ：IP 10.100.22.48，服务端口 8081
  • Spring Boot 业务服务 ：IP 10.100.22.48，服务端口 8071（注意：业务服务与网关部署在同一台物理机上）

完整的流量流向： 客户端(10.20.4.84) -> Nginx(10.100.38.11:9009) -> Gateway(10.100.22.48:8081) -> Spring Boot(10.100.22.48:8071)

第一阶段：抓取 客户端 -> Nginx（入向请求）

首先确认客户端发出的报文到底对不对。在 Nginx 所在机器（10.100.38.11）上抓取目标端口为 9009 的入向流量：

Bash

复制代码 
sudo tcpdump -i ens192 -s 0 -nn 'tcp dst port 9009' -w /tmp/nginx_before.pcap

将文件导出到本地后，通过 Wireshark 打开。为了快速定位，可以使用包含接口特征的过滤条件，例如： tcp contains "responseSpecialBufferSizeOfPost"

定位到目标数据包后，右键点击该数据包 -> 追踪流 (Follow) -> TCP 流 (TCP Stream)，即可看到直观的 HTTP 原始报文。

还原出的原始 HTTP 请求如下：

HTTP

复制代码 
POST /api-gateway-dev/demo-business-service/sms/responseSpecialBufferSizeOfPost HTTP/1.1
appid: demo-business-service
appKey: asd
Content-Type: application/json
User-Agent: PostmanRuntime/7.54.0
Host: 10.100.38.11:9009
Content-Length: 1868

{"xn":"0462add21538f...[报文过长，此处省略]...1b4f7b1911"}

结论： 客户端确实发送了驼峰格式的 appKey: asd，源头没问题。

第二阶段：抓取 Nginx -> Gateway（出向请求）

接着排查是不是 Nginx 在转发时对 Header 做了手脚。依然在 Nginx 机器上，抓取 Nginx 发往 Gateway（10.100.22.48:8081）的流量：

Bash

复制代码 
sudo tcpdump -i ens192 -s 0 -nn 'tcp and dst host 10.100.22.48 and dst port 8081' -w /tmp/nginx_after.pcap

查看报文内容：

HTTP

复制代码 
POST /demo-business-service/sms/responseSpecialBufferSizeOfPost HTTP/1.1
Host: 10.100.38.11
X-Real-IP: 10.20.4.84
X-Real-Port: 50649
X-Forwarded-For: 10.20.4.84
Content-Length: 1868
appid: demo-business-service
appKey: asd

结论： Nginx 增加了几个 X- 开头的代理头，但原封不动地保留了 appKey 的驼峰格式。Nginx 洗清嫌疑。

第三阶段：抓取 Nginx -> Gateway（入向请求确认）

为了严谨，我们前往 Gateway 所在机器（10.100.22.48），确认网关网卡实际收到的报文内容。

💡 技术要点：为什么这里不筛选 Nginx 的源端口（9009）？ > 因为 Nginx 在作为反向代理将请求转发给上游服务器时，它自己扮演了"客户端"的角色。系统会为这个新的 TCP 连接随机分配一个临时的动态端口（Ephemeral Port，例如 53971），而不是复用外部客户端访问 Nginx 时的 9009 端口。如果强行加上 src port 9009，将抓不到任何转发包。

因此，过滤条件只需指定源 IP 和目标端口：

Bash

复制代码 
sudo tcpdump -i ens33 -s 0 -nn 'src host 10.100.38.11 and dst port 8081' -w /tmp/gateway_before.pcap

报文显示 appKey: asd 依然坚挺。网关入向流量正常。

第四阶段：抓取 Gateway -> Spring Boot（出向请求）

这是最关键的一环。Spring Cloud Gateway 底层基于 Netty 构建，中间经过了一系列的 Routing Filter 配置，它会修改 Header 吗？

由于 Gateway 和最终的下游 Spring Boot 业务服务部署在同一台机器 （10.100.22.48）上，我们需要在网关机器上抓取发往下游业务服务（8071端口）的流量。

💡 技术要点：为什么网卡参数使用的是 -i any？ > 当服务部署在同一台机器时，它们之间的网络通信通常不会经过外部的物理网卡（如 ens33），而是直接走系统的本地回环网卡（Loopback interface，即 lo，IP 为 127.0.0.1 或是通过内网 IP 内部路由）。使用 -i any 可以监听本机上所有网络接口的流量，无论它们是走物理网卡出网，还是在本地回环网络内通信，都能做到"一网打尽"，避免因选错网卡而抓不到包的情况。

Bash

复制代码 
sudo tcpdump -i any -s 0 -nn 'src host 10.100.22.48 and dst port 8071 and tcp' -w /tmp/gateway_after.pcap

通过 Wireshark 追踪这部分报文，我们看到了网关发出的最终内容：

HTTP

复制代码 
POST /sms/responseSpecialBufferSizeOfPost HTTP/1.1
X-Real-IP: 10.20.4.84
X-Real-Port: 61676
X-Forwarded-For: 10.20.4.84,10.100.38.11
Content-Length: 720
appid: demo-business-service
appKey: asd
Content-Type: application/json
Forwarded: proto=http;host=10.100.38.11;for="10.100.38.11:58748"
host: 10.100.22.48:8071
sw8: 1-YWM4Nj...[链路追踪头信息省略]...MTAuMTAwLjIyLjQ4OjgwNzE=

结论： 网关追加了 SkyWalking 链路追踪相关的头（sw8 等）以及 Forwarded 路由信息，但依然完美透传 了 appKey: asd。网关也洗清了嫌疑！

峰回路转：真相在最后一公里

既然整个网络链路（Nginx -> Gateway -> 本地网卡）都没有修改请求头的大小写，那问题必定出在 Spring Boot 服务内部。

为了验证，我直接使用 Postman 直连 Spring Boot 服务（10.100.22.48:8071）发起请求，并在代码中断点调试以下获取请求头的方法：

Java

复制代码 
Enumeration<String> headerNames = request.getHeaderNames();
while (headerNames.hasMoreElements()) {
    String headerName = headerNames.nextElement();
    System.out.println(headerName + " : " + request.getHeader(headerName));
}

运行结果让人大跌眼镜：遍历打印出来的 headerName 全是小写的 appkey！

根因剖析：RFC 规范与 Tomcat 源码实现

为什么 Spring Boot 会把 Header 的名字变成小写？

实际上，HTTP/1.1 规范（RFC 2616 章节 4.2）明确规定：HTTP Header 的字段名称是大小写不敏感的（case-insensitive）。 到了 HTTP/2，规范更是直接强制要求所有的 Header 名称在传输层必须被转换为全小写。

为了遵循这一规范并提高匹配效率，Spring Boot 内嵌的 Tomcat 容器在解析 HTTP 协议的极底层代码中，直接完成了大写到小写的转换。以当前项目的 Spring Boot 2.7.18 （默认内嵌 Tomcat 9.0.83 ）为例，核心转换逻辑发生在 Coyote HTTP/1.1 处理器的 Http11InputBuffer 类中。

Tomcat 会逐字节读取 HTTP 报文。当它在 parseHeader() 方法中解析到 Header Name 时，会直接在底层的 ByteBuffer 里进行原地替换（In-place conversion）。具体源码信息如下：

关键代码片段截取：

Java

复制代码 
// 截取自 Http11InputBuffer#parseHeader() 读取 Header Name 字节流的逻辑
if (chr >= Constants.A && chr <= Constants.Z) {
    byteBuffer.put(byteBuffer.position() - 1, (byte) (chr - Constants.LC_OFFSET));
}

原理解释：

  • chr 是当前读取到的单个字节。
  • 当判断 chr 为大写字母（在 A (65) 和 Z (90) 的 ASCII 码之间）时，执行 chr - Constants.LC_OFFSET。
  • Constants.LC_OFFSET 的定义是 A - a（即 65 - 97 = -32）。所以 chr - (-32) 实质上就是 chr + 32，这正是 ASCII 码表中大写字母转换为小写字母的数学偏移量。

经过 Http11InputBuffer 这样极其底层的按字节剥离处理后，被强制转为小写的 Header Name 最终才会被封装成 MessageBytes 对象，并存入 org.apache.tomcat.util.http.MimeHeaders 结构中供后续路由和业务使用。因此，当你通过 request.getHeaderNames() 获取枚举迭代器时，暴露出来的迭代值自然就是小写的形式了。

但需要特别注意的是，虽然遍历出来是小写，由于规范要求"大小写不敏感"，且 Tomcat 底层查找逻辑做了忽略大小写的兼容，所以当你使用指定 key 去获取时： request.getHeader("appKey")、request.getHeader("APPKEY") 以及 request.getHeader("appkey") 都能 正确获取到对应的值 "asd"。

总结与避坑指南

  1. 排查思路： 遇到跨多节点的网络问题，善用 tcpdump 结合 Wireshark 追踪 TCP 流是最直接高效的手段。不要过度依赖主观猜测。清楚流量拓扑、正确选择网卡（同机用 any 或 lo）以及理解代理转发时的端口分配机制，能避免在抓包时走弯路。
  2. 开发规范： 永远不要依赖 HTTP 请求头的大小写来做业务逻辑判断（比如 if(name.equals("appKey"))）。如果必须遍历 Headers 并做精确匹配，请使用 equalsIgnoreCase 进行比较。
  3. 获取方式： 推荐直接通过 @RequestHeader("appKey") 注解或 request.getHeader("appKey") 明确获取，容器底层会帮我们处理好大小写兼容的问题。尽量避免通过 request.getHeaderNames() 遍历取 key 后再做强校验。
热门推荐
012026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？022026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf03【AI】2026 年具身智能模型和世界模型总结042026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？052026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？06GitHub 镜像站点07AI科技热点日报 | 2026年6月1日08上线仅72小时被强制下架：Claude Fable 5 的短命09HTTP 与 HTTPS 的区别：从原理到实战详解10Codex 下载安装指南：Windows 和 macOS 官方版下载