联调时最容易被误判的一类故障,是中文在链路上变成了问号、方块,或者一串像 测试 这样的拉丁字符。它既不像超时那样有明确报错,也不像 500 那样能直接定位,页面照常返回,只是内容读不懂。这次遇到的情况是:请求端把中文写进请求体发出,网关转发之后,接收端落库或回显的内容变成了乱码,而三方各自单测都正常。记录一下从现象到根因的排查路径。
先分清乱码的两种形态
乱码不是一种病,至少要先分成两类,因为它直接决定往哪个方向查。
第一类是替换型:中文字符变成了 ? 或 �。这意味着某一环在做编码转换时,目标字符集里根本没有对应的码位,信息已经被就地丢弃。这种丢失不可逆,只能从配置上修。
第二类是错解型:中文字符变成了一串看似正常的拉丁字母组合,长度明显变长。这通常是 UTF-8 的多字节序列被当成 ISO-8859-1 逐字节解释的结果。它的特点是信息没丢,理论上还能反向还原,说明链路里某一环"读错了字典"而不是"字典里没这个词"。
我在现场看到的是第二种,于是判断方向立刻从"数据被截断"转向"某一跳对字符集的假设和上游不一致"。这个判断很关键:替换型要查转换动作发生在哪,错解型要查谁在解码时用错了默认值。
把链路拆成三段来看
跨服务调用看起来是一条线,实际上至少有三个可以独立出错的环节,而且它们的默认行为往往不一样。
请求端负责把内存里的字符串序列化成字节流。多数序列化框架会把 JSON 写成 UTF-8,但发出去的请求头里如果没有显式带上字符集声明,接收方就只能靠猜。这是最常见的第一个坑。
中间的 API 网关或反向代理负责转发。它本身通常不该改动请求体,但一旦配置里存在转码、重写、或者对请求头做了归一化处理,字符集声明就可能被覆盖或丢弃。这次的问题最终就落在这一段。
接收端负责把字节流解回字符串。框架、容器、数据库连接、甚至读取请求体的方式,都可能各自有一套默认字符集。任何一处和上游不一致,乱码就在那一处产生。
值得注意的是,这三段里"谁错了"并不重要,重要的是找出第一个把字节流按错误方式解释的地方。因为一旦错了,后面所有环节都会忠实继承这个错误结果,日志里看到的乱码位置会一路往后漂。
用原始字节而不是肉眼判断
排查这类问题,第一个动作应该是绕开所有中间层,直接看字节。
我习惯先用抓包工具拦一次完整请求,把请求体和响应体按十六进制或原始字节模式打开。中文字符在 UTF-8 下每个字占三个字节,首字节高四位通常是 1110,也就是常见的 E4 到 E9 开头。如果抓到的字节序列符合这个特征,说明请求端发出去的是对的,问题在后面的解码环节。
如果抓到的字节已经变成了 C3 A6 这类两字节组合,那基本可以确认上游做了错误的双重编码。
同时要核对请求头里的字符集声明。标准做法是看 Content-Type 后面有没有带 charset 参数,以及这个参数的值和实际字节是否匹配。这一次抓到的请求头里缺少字符集声明,网关在转发时按自己的默认值补了一个,接收端又照着这个补上的值去解码,两个默认值恰好都不对,乱码就出现了。
除了抓包,日志也是重要线索,但要小心一个陷阱:日志里显示乱码,不等于传输中的数据是乱码。很多终端的输出编码和应用的运行编码并不一致,日志平台在采集时也可能做过转换。如果只盯着日志判断,很容易把"展示层乱码"误判成"传输层乱码",然后改错地方。我的做法是在每一跳都打一条包含字符集声明和请求体字节长度的日志,对比长度是否一致。长度在一次转发后突然变化,往往就是转码动作发生的信号。
逐跳比对标头与长度
把链路拉直之后,具体操作可以按这个顺序走:
- 在请求端出口抓包,记录请求体的字节序列、字节长度和
Content-Type原始值。 - 在网关入口和出口各取一次同样信息,重点看标头是否被改写、长度是否变化。
- 在接收端读取请求体的位置打日志,输出实际收到的字节长度和解码后的字符长度。
- 把四组数据列在一起,找出第一次出现差异的那一跳。
这一次的差异出现在网关出口:入口字节长度和出口字节长度不同,字符集声明也从无变成了一个不匹配的值。原因定位到网关上一段针对请求体的处理配置,它把请求体当作文本读入再写出,读入时用了默认字符集,写出时又声明了另一个。改法是让这段处理直接透传字节流,不对请求体做字符层面的转换。
RPC 场景的逻辑一样,只是"标头"换成了调用框架携带的元数据或者序列化声明。判断标准不变:谁在解码,谁就必须知道上游用的是哪种编码,不能依赖默认值。
统一编码的配置清单
修完这一处之后,我把链路上所有可能引入默认字符集的位置过了一遍,形成一份可以复用的检查项:
- 请求端:序列化后的请求体显式声明字符集,不省略
charset参数。 - 传输层:URL 中的非 ASCII 内容按规范做百分号编码,不要直接拼原始字符。
- 网关与代理:明确关闭请求体转码,转发时保留原始字节和原始标头。
- 接收端:读取请求体时以声明为准,声明缺失时按既定约定处理,而不是交给框架默认值。
- 存储层:数据库、缓存、消息队列的连接字符集与业务编码保持一致。
- 日志与监控:输出端编码与应用编码统一,避免日志本身产生误判。
这份清单的价值不在于每条都要改,而在于出问题时能快速排除。多数乱码故障最终都落在其中一两条上,逐项确认比盲目改配置快得多。
最后补一句判断经验:跨语言系统之间,默认值是最危险的约定。Java 服务、Go 服务、前端页面、网关、数据库,每一层都有自己的默认字符集,而且它们的历史成因完全不同。与其记住每层默认什么,不如在链路的每一跳都显式声明,让"没有声明"成为一件需要报警的异常,而不是一件可以放任的事情。这次的问题修完之后,我做的第一件事就是把字符集声明缺失加进了接口约定的检查项里,比事后抓包省事得多。












