{"detail":"There was an error parsing the body"}—— 如果你在浏览器的 Network 面板或者日志里撞见这行响应，第一反应大概是"我 JSON 写错了"。我第一次遇到它的时候也是这么想的，然后把请求体翻来覆去检查了二十遍：字段名、引号、逗号、括号、嵌套层级，全对，甚至拿在线校验器过了一遍，绿色的。可服务端还是这行 400。
真正的原因藏在一个跟 JSON 语法完全没关系的地方。这篇就聊这件事：这个 API 请求错误到底是谁抛出来的，为什么它几乎不携带任何有效信息，以及在实际项目里，哪些根因会把一个看起来完全正常的请求推进这条分支。内容适合已经能把接口跑通、却被一个 400 卡住半天的后端和前端同学，也适合做联调、维护网关规则、写中间件的人——因为这篇文章里有一半的坑，不在业务代码里。
1. 这句报错的出处：它由框架的兜底分支产生
1.1 从响应体文本反查代码位置
先做一个最基本的定位动作：这行文本不是你的业务代码写的，也不是数据库写的，它是 Web 框架层的固定文案。在 Python 生态里，detail这个字段名加上这句英文，基本可以把范围锁死在 Starlette / FastAPI 这一支。你可以在依赖目录里直接搜这段字符串，命中的位置通常在路由处理模块中，形如HTTPException(status_code=400, detail="There was an error parsing the body")。
找到这一行之后，往上看十几行，你会看到它的上下文长这样：
try: body = await request.body() if body: # 判断 Content-Type，决定是否调用 request.json() ... except json.JSONDecodeError as e: # 新版本：转成 422 的校验错误 raise RequestValidationError(...) from e except HTTPException: raise except Exception as e: http_error = HTTPException( status_code=400, detail="There was an error parsing the body", ) raise http_error from e这段结构信息量极大。它告诉你三件事：第一，这个 400 是在"读取并解析请求体"这个阶段产生的；第二，json.JSONDecodeError被单独拎出来处理了，走的是另一条分支；第三，剩下所有异常统统被最后的except Exception收走，统一压成这一句 400。
换句话说，能触发这个 400 的，恰恰不是"JSON 语法写错了"这一类最常见的错误。语法错误有它自己的归宿。
1.2 为什么它一句有用的话都不说
except Exception as e这个兜底写法，把原始异常对象整个吞掉了，只在raise ... from e里留了一条__cause__引用。而框架的 HTTP 异常处理器拿到这个HTTPException之后，做的事情非常简单：取exc.detail拼成 JSON 返回，状态码 400，结束。它不会打印 traceback，也不会把__cause__暴露给客户端。
所以你看到的现象就是：服务端日志干干净净，客户端只收到一句"解析请求体出错了"。到底哪里出错、错在第几个字节、原始异常是什么类型，全都没有。这也是为什么这个问题特别耗时间——它不是难在修复，而是难在定位。
我见过有人在这种情况下去翻框架的 issue 列表，翻了两个小时，最后发现是自己团队写的日志中间件把请求体流读走了。信息缺失造成的排查成本，远大于问题本身的复杂度。
提示：只要看到"信息极少但状态码明确"的框架级错误，第一优先级永远是"把被吞掉的原始异常捞出来"，而不是"猜原因"。
1.3 三分钟内拿到原始异常的三条路径
路径一：临时关掉兜底，让异常直接冒出来。在本地开发环境，可以临时改一下依赖包里的那段代码，把except Exception分支改成raise。改完重启，请求一次，完整的 traceback 就打在控制台上了。注意这只在本地做，别提交。改依赖包听起来脏，但它是最快的，三十秒搞定。
路径二：注册一个全局 HTTP 异常处理器，把__cause__打出来。这个方案可以长期保留，后面第 5 节会展开写完整实现。核心就是判断exc.__cause__是否存在，存在就用logger.error(..., exc_info=exc.__cause__)打全栈。
路径三：在读取请求体的位置加探针。如果你不方便动框架代码，可以写一个最外层的中间件，在请求进来时把await request.body()的结果取长度、取前 64 字节的十六进制、算个哈希，全部记进日志。这样一来，即使解析失败，你也能知道服务端究竟收到了什么字节。
三条路径里，我最常用的是第二条加第三条组合：长期可观测性靠全局处理器，具体某一次排查靠字节探针。第一条只在"我已经确认问题在本地能稳定复现、但就是想看 stack"的时候用。
2. "改 Content-Type"这条建议，在多数情况下是错的
2.1 框架判断"要不要解析 JSON"的完整分支
网上关于这个报错的答案，十条里有八条是"你没设Content-Type: application/json"。这条建议本身没错，但它的因果关系被传反了。我们顺着源码把判断逻辑还原一遍：
body_bytes = await request.body() if body_bytes: json_body = Undefined content_type_value = request.headers.get("content-type") if not content_type_value: # 没有 Content-Type，直接尝试按 JSON 解析 json_body = await request.json() else: message = email.message.Message() message["content-type"] = content_type_value if message.get_content_maintype() == "application": subtype = message.get_content_subtype() if subtype == "json" or subtype.endswith("+json"): json_body = await request.json() if json_body != Undefined: body = json_body else: body = body_bytes逐条拆开看：
- 完全没带 Content-Type：框架会尝试按 JSON 解析。所以"没设 header 就解析失败"这个说法不成立，它反而会去试。
- 带了
application/json或application/xxx+json：按 JSON 解析。 - 带了其他类型，比如
text/plain、application/x-www-form-urlencoded、multipart/form-data：不解析，直接把原始字节往下传。 - 请求体为空：整段跳过，
body保持空值。
关键在于最后两种情况：原始字节被直接交给参数校验层，校验层拿到一堆 bytes 去匹配一个结构化模型，结果必然是"字段缺失"或"类型不符"，返回的是422，不是这个 400。
所以结论很直接：如果真的是 Content-Type 写错了，你看到的应该是 422 加上一串字段级的错误详情，而不是这句干巴巴的 400。这两者的排查方向完全不同，混淆了就会在错误的方向上耗时间。
2.2 Content-Type 错位真正长什么样
为了让你有个直观对照，我把几种典型错位和实际现象列成表：
| 客户端实际行为 | 服务端收到的 Content-Type | 典型结果 |
|---|---|---|
传 FormData 但手动设了application/json | application/json | 解析 multipart 字节失败，可能是 400 或 422 |
| 传 JSON 字符串但没设 header | 无 | 正常解析，通常能成功 |
传 JSON 字符串，header 写成text/plain | text/plain | 422，提示字段缺失或类型错误 |
传 JSON 字符串，header 写成application/json | application/json | 正常解析 |
传 URL 编码表单，header 写成application/json | application/json | 解析失败，走 JSON 错误分支 |
传 JSON 字符串，header 带charset=gbk | application/json; charset=gbk | 可能触发这个 400，原因见 3.1 |
表格里倒数第二行值得单独说一句。很多人用表单序列化库（比如把对象转成a=1&b=2）之后，忘了把 header 改回来。这时候服务端拿到的是 URL 编码的字节，却按 JSON 去解析，json.loads("a=1&b=2")直接抛语法错误。在新版本框架里这是 422，在老版本里会落到兜底分支变成 400。
2.3 客户端各种写法对应的实际请求头
这块是前端同学最容易踩的地方，因为不同 HTTP 客户端对 header 的自动处理策略差别很大。
// fetch：不会自动序列化，也不会自动设 Content-Type await fetch("/api/x", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(payload), }); // 错误写法：直接把对象塞进 body await fetch("/api/x", { method: "POST", body: payload }); // 变成 "[object Object]"fetch的坑在于它太诚实了。body传对象不会报错，会静默转成字符串"[object Object]"，然后你带着application/json的 header 发过去，服务端解析这个字符串，得到一个语法错误。这个错误在浏览器控制台里完全看不见，只有服务端能看到。
// axios：会自动序列化并设 header，但显式覆盖 header 会出问题 axios.post("/api/x", payload, { headers: { "Content-Type": "application/json" }, // 多余但无害 }); // 危险写法：传 FormData 却手动指定 json const fd = new FormData(); fd.append("file", file); axios.post("/api/x", fd, { headers: { "Content-Type": "application/json" }, // 手动覆盖，破坏边界字符串 });第二种写法的问题在于，FormData需要浏览器自动生成boundary参数，一旦你手动把 Content-Type 设成固定值，boundary就丢了，服务端根本无法还原出各个字段。这个坑极其常见，因为很多人是从"加个 header 更保险"的思路出发的，结果反而搞坏了。
命令行这边同理：
# 错误：-d 默认带 application/x-www-form-urlencoded curl -X POST http://127.0.0.1:8000/api/x -d '{"name":"a"}' # 正确：显式指定 curl -X POST http://127.0.0.1:8000/api/x \ -H 'Content-Type: application/json' \ --data-binary '{"name":"a"}'注意-d和--data-binary的区别：前者会去掉换行符，后者原样发送。做复现测试时用--data-binary，能保证你发出去的字节和文件里完全一致。
3. 四类真正会触发兜底分支的根因
接下来是本文的核心。既然语法错误已经被单独分支接走了，那还有什么能落到except Exception里？
3.1 非 UTF-8 字节混进了 JSON 请求体
这是我认为最高频、也最容易被忽视的一类。关键在于json.loads对bytes的处理方式：它内部会先做一次解码，编码检测只认字节序标记（BOM），完全不看你 header 里的charset参数。
import json # 一段 GBK 编码的中文 JSON raw = '{"name":"张三"}'.encode("gbk") json.loads(raw) # UnicodeDecodeError: 'utf-8' codec can't decode byte 0xd5 in position 9抛出来的是UnicodeDecodeError。它和JSONDecodeError是"堂兄弟"关系——两者都继承自ValueError，但彼此没有继承关系。所以前面那个except json.JSONDecodeError分支接不住它，异常继续往下走，被except Exception收走，变成你看到的那句 400。
这条路径解释了一个非常反直觉的现象：你在 header 里明明白白写了charset=gbk，服务端还是不认。因为 JSON 的规范本身就要求用 UTF-8 传输，框架把 bytes 直接丢给标准库解析器，解析器压根不看 header。
怎么发生的？几个典型场景：
- 老系统之间的接口对接，发送方用的是本地默认编码（在很多环境里是 GBK），把 JSON 字符串编码成字节发出去。
- 用某些脚本语言或老版本 HTTP 客户端拼请求，默认编码不是 UTF-8。
- 请求体里混入了用户上传的文本文件内容，而那个文件不是 UTF-8。
- 从 Excel、CSV 里读出来的中文，直接拼进 JSON 序列化前的原始字符串再编码。
我处理过的一次就是最后一种：后端读了一个本地编码的配置文件，把里面的中文塞进响应再转发，转发时又按本地编码编了一次字节。整个链路上没有任何一处代码"看起来有问题"，但字节到了对端就是解析不了。
定位方法很简单，用十六进制看：UTF-8 的中文是三个字节起步，形如e4 b8 ad；GBK 是两字节，形如d5 c5。只要你看到请求体里出现大量0x80以上的双字节组合，基本就能确认编码不对。
# 直接把请求体的十六进制打出来看 echo -n '{"name":"张三"}' | iconv -f utf-8 -t gbk | xxd | head修复方向上，原则只有一条：JSON 一律用 UTF-8 传输。发送端强制encode("utf-8")，或者干脆交给 JSON 库自己处理（json.dumps默认就返回 str，编码交给你选择的 HTTP 客户端）。真的遇到必须兼容老编码的场景，只能在服务端接管请求体读取，自己按约定编码解码，这条路径第 5.2 节会写。
3.2 中文全角标点与"看起来像 JSON"的文本
第二类是最让人哭笑不得的：请求体肉眼看上去完全合法，但里面有全角字符。
｛"name"："张三"，"age"：18｝这串东西在编辑器里高亮正常、长度正常、结构也"对"，但它用的全是中文输入法下的全角括号、全角引号、全角逗号。json.loads会毫不留情地拒绝。
这一类在新版本框架里通常表现为 422 加"JSON 解析错误"的定位信息，而老版本会变成这个 400。所以如果你在排查老项目，一定要把这条列为怀疑对象。
比全角标点更隐蔽的是不可见字符：
- 从 Word、微信、富文本编辑器里复制出来的文本，可能夹带零宽空格（
U+200B）、不换行空格（U+00A0）。 - 代码里用模板字符串拼 JSON，模板缩进带进来的制表符没问题，但某些编辑器会自动插入特殊空白。
- 复制粘贴时带进来的软连字符。
这些字符在浏览器 DevTools 的 Payload 面板里基本看不出来，因为面板会做一些格式化处理。我吃过这个亏——盯着屏幕看了半小时，最后把请求体复制到十六进制查看器里，才发现开头有个ef bb bf之外的东西。
排查这类问题最有效的办法不是"再检查一遍"，而是把请求体存成文件，用工具逐字节过一遍：
# 找出所有非 ASCII 且非 UTF-8 中文范围的字节 python3 -c " data = open('body.json','rb').read() for i, b in enumerate(data): if b > 0x7f: print(i, hex(b)) "3.3 分块传输、压缩与截断造成的字节断裂
第三类根因跟"内容对不对"无关，纯粹是"字节在路上被搞坏了"。
压缩场景：如果客户端或中间层对请求体做了 gzip 压缩，但忘了带Content-Encoding: gzip，服务端拿到的就是一串二进制。json.loads去解码这串二进制，大概率在某处撞上非法 UTF-8 序列，抛UnicodeDecodeError，落到兜底分支。
反过来，如果带了Content-Encoding但服务端的解压环节出问题，或者中间层解压后又没把 header 去掉，也会造成类似的错位。
截断场景：请求体很大、传输过程中连接中断、或者上游限流把 body 截了一半。剩下半截 JSON 的尾部如果正好切在一个多字节字符中间，就会产生一个不完整的 UTF-8 序列。这种情况特别隐蔽，因为前面 99% 的内容都是好的。
举个具体的例子，"张"的 UTF-8 是e5 bc a0，如果截断发生在e5 bc，剩下两个字节就是非法序列，解码直接失败。而如果截断发生在完整字符边界上，那只会得到一个 JSON 语法错误（走另一条分支）。这就解释了为什么同一个接口"有时候报语法错误，有时候报这个 400"——取决于截断落点。
这类问题的排查思路是先量长度：
# 对比客户端发出的长度和服务端收到的长度 curl -s -o /dev/null -w '%{size_upload}\n' \ -X POST http://127.0.0.1:8000/api/x \ -H 'Content-Type: application/json' \ --data-binary @payload.json服务端那边同步记一下Content-Length和实际读到的字节数，两个数字不一致，问题就在传输层，跟你的 JSON 一点关系都没有。
3.4 请求体流被提前消费
第四类是目前我认为最"高级"的坑，因为它需要你对 ASGI 的消息模型有基本认识。
请求体在 ASGI 里不是"一个可以从头读的文件"，而是一条只能顺序消费一次的消息流。框架的Request对象用两个标记来管理状态：_body存缓存的字节，_stream_consumed标记流有没有被消费过。读取逻辑大致是这样：
async def stream(self): if hasattr(self, "_body"): yield self._body yield b"" return if self._stream_consumed: raise RuntimeError("Stream consumed") while not self._stream_consumed: message = await self._receive() if message["type"] == "http.request": body = message.get("body", b"") if not message.get("more_body", False): self._stream_consumed = True if body: yield body现在假设你写了一个自定义的 ASGI 中间件，为了做审计日志，直接await receive()把消息读了出来。读完之后，消息没有被放回队列，也没有触发_body缓存。下游的请求处理函数再调request.body()时，会走进stream()，此时_stream_consumed可能已经是True，于是抛出RuntimeError("Stream consumed")。
这个RuntimeError不是 JSON 语法错误，直接落到兜底分支——400，那句话。
另一条相关路径：request.form()解析表单时用的是self.stream()，解析完之后不会回填_body。所以如果你在中间件里调了一次form()，业务代码再调body()就会拿到空内容或者直接报错。这个行为在文档里写得很含糊，很多人是在踩过一次之后才知道。
还有一个容易忽略的点：request.json()内部会调body()，如果_body已经缓存，多次调用json()是安全的。所以同一请求内重复解析 JSON 不会出问题，出问题的永远是"用stream()或form()消费了流但没缓存"。
4. 一条可复现的排查链路：从响应头到最小请求
讲完根因，接下来是操作层面的东西。我自己遇到这个错误时的固定流程是这样，一般十五分钟内能有结论。
4.1 先确认报错是谁产生的
这一步听起来多余，但真的能省时间。因为这句话也可能是上游服务返回的，你的客户端只是原样转发了一遍。
判断依据看响应头：
curl -i -X POST http://127.0.0.1:8000/api/x \ -H 'Content-Type: application/json' \ --data-binary '{"a":1}'看server、content-type、x-request-id这类字段的形态。如果响应头里出现了网关特有的标记，或者content-type不是标准的application/json，那这条 400 可能在更前面就产生了，你的业务代码压根没收到请求。这时候应该去查网关的转发配置、请求体大小限制、WAF 规则，方向完全不同。
还有一个更直接的判据：在业务代码里加一行日志，放在路由函数的第一行。如果这行日志没打出来，说明请求根本没进到你的函数，问题在框架层或更前面。
4.2 浏览器面板会骗你：看原始字节
DevTools 的 Network 面板在展示请求体时会做格式化，尤其是选择了 JSON 视图的时候。它会帮你把内容重新排版、去掉多余空白、甚至有选择地处理转义字符。这意味着你看到的和实际发出去的，可能不是同一串字节。
正确做法是切到"原始/Raw"视图，或者直接复制请求为 curl 命令，拿到命令行里跑一遍。Chrome 和 Firefox 都有"Copy as cURL"的功能，拿到之后检查三处：
--data-binary或--data-raw后面跟着的那串内容，是不是有奇怪的转义。- 有没有
-H 'Content-Type: ...'，值是什么。 - 有没有
--compressed或--compressed-ssh这类自动加上的参数。
我有一次就是在这第三步发现问题的：浏览器自动加了一个压缩相关的参数，而服务端在某个版本上对解压的处理有问题，导致请求体被当成原始字节直接解析。这种问题你盯着 Payload 面板看一辈子都看不出来。
4.3 用 curl 构造最小可复现请求
确认服务端确实收到了请求之后，下一步是把请求缩到最小：一个字段、一个值、最短的 URL。
# 最小请求 curl -i -X POST http://127.0.0.1:8000/api/x \ -H 'Content-Type: application/json' \ --data-binary '{"a":1}'如果这条能过，说明框架和路由配置没问题，问题在你的真实请求体里。然后逐层加回去：加字段、加中文、加嵌套、加特殊字符。加到某一层突然失败，那一层就是嫌疑人。
如果最小请求也过不去，那问题在更基础的地方：路由定义、依赖注入、全局中间件。这时候把中间件一个一个注释掉试，比读代码快得多。
我还会准备一个"已知能过"的用例作为对照组，比如用框架自带的交互式文档页面发一次同样的请求。文档页面的请求是浏览器生成的，编码、header 都是标准的。如果文档页面能过、你的 curl 不能过，对比两者的请求头差异，差距通常一目了然。
4.4 服务端临时落盘方案
当一切都看不出来的时候，我会上最笨也最有效的办法：把收到的原始字节写到文件里。
from fastapi import FastAPI, Request app = FastAPI() @app.middleware("http") async def dump_body(request: Request, call_next): if request.url.path.startswith("/api/"): body = await request.body() with open("/tmp/dump.bin", "ab") as f: f.write(b"--- " + request.url.path.encode() + b" ---\n") f.write(body + b"\n") return await call_next(request)然后拿dump.bin去做三件事：
xxd看十六进制，确认有没有 BOM、有没有双字节中文、有没有不可见字符。file命令猜编码，虽然不是百分百准，但能给出方向。python3 -c "import json; json.load(open('/tmp/dump.bin'))"手动跑一遍解析，看抛的是什么类型的异常。
这一步做完，绝大多数情况都能定性。剩下的就是按第 3 节的四类根因对号入座。
不过要提醒一句：这个中间件会读取请求体，务必确认它跑在不会破坏后续读取的位置。如果是自定义的纯 ASGI 中间件，读完之后一定要重新构造receive把消息放回去，否则就变成第 3.4 节说的那个坑了。用@app.middleware("http")装饰器注册的中间件，框架内部做了缓存包装，相对安全，但也是在新版本上。
5. 让异常自己开口：日志与全局处理器的改造
排查是一时的，可观测性是一直的。这个错误之所以烦人，本质原因是框架的兜底逻辑把信息灭了。下面三处改造，我基本上每个项目都会加上。
5.1 给兜底异常加日志
注册一个全局 HTTP 异常处理器，重点是把__cause__打出来：
import logging from fastapi import FastAPI, Request from fastapi.responses import JSONResponse from starlette.exceptions import HTTPException as StarletteHTTPException logger = logging.getLogger("app.http") app = FastAPI() @app.exception_handler(StarletteHTTPException) async def http_exception_handler(request: Request, exc: StarletteHTTPException): cause = exc.__cause__ if cause is not None: logger.error( "HTTP %s on %s %s, detail=%r, cause=%s", exc.status_code, request.method, request.url.path, exc.detail, type(cause).__name__, exc_info=cause, ) return JSONResponse( status_code=exc.status_code, content={"detail": exc.detail}, )这段代码的价值不在于"多打了日志"，而在于把被框架归类为"未知错误"的那一批，重新变成有类型、有堆栈、有行号的已知错误。上线之后，你搜cause=UnicodeDecodeError就能直接命中编码问题，搜cause=RuntimeError基本就是流被消费了，分类效率完全不同。
注意logger.error的用法：exc_info参数可以接受一个异常实例（Python 3.5 之后支持），传进去之后日志里会带上那个异常的完整堆栈。这一点很多人不知道，习惯性地只在except块里用logger.exception，出了块就打不出来了。
5.2 自定义请求体读取入口
对于明确知道自己要处理非标准编码的场景，可以在路由里绕开框架的默认解析，自己读字节、自己解码：
from fastapi import APIRouter, Request, HTTPException import json router = APIRouter() @router.post("/api/legacy") async def legacy_endpoint(request: Request): raw = await request.body() if not raw: raise HTTPException(status_code=400, detail="empty body") # 先按 UTF-8 试，不行再按约定的老编码兜底 try: text = raw.decode("utf-8") except UnicodeDecodeError: try: text = raw.decode("gbk") except UnicodeDecodeError: raise HTTPException(status_code=400, detail="unsupported encoding") try: payload = json.loads(text) except json.JSONDecodeError as e: raise HTTPException( status_code=400, detail=f"json decode error at pos {e.pos}: {e.msg}", ) return {"ok": True, "keys": list(payload.keys())}这个写法把三种失败分开了：空体、编码不支持、语法错误。每一种返回的提示都不一样，前端拿到之后能直接知道该改哪里。比起统一返回"解析出错"，联调效率差好几倍。
要强调的是，这属于兼容性妥协方案，正常的新接口不应该需要它。JSON 就该是 UTF-8，这是规范，不是建议。
5.3 中间件写法的注意事项
如果你确实需要写自定义中间件，记住三条：
第一条，读请求体要用await request.body()，不要用request.stream()。前者会缓存_body，后续读取安全；后者会消费流，后果自负。
第二条，如果必须用流式处理（比如做大文件校验），读完之后手动把数据放回receive。具体做法是构造一个新的receive可调用对象，第一次返回缓存的http.request消息，后续透传原始的receive。
第三条，尽量不要在中间件里调request.form()。它内部用的是stream()，解析完不回填。这条是我用血换来的经验，当时排查了整整一个下午。
还有个细节：如果你用的是基于BaseHTTPMiddleware的写法，框架内部会做一层请求缓存包装，安全性比自己手写 ASGI 中间件高很多。所以能用前者就别用后者，除非你有明确的性能或功能需求。
6. 前端与被代理层：几个反复出现的现场细节
最后一节讲几个跟框架无关、但在现场反复出现的细节。这些问题不解决，你把服务端代码读烂了也找不到原因。
6.1 反向代理对请求体的改写
中间隔一层反向代理的时候，请求体的样子可能跟你发的完全不一样。几个常见的改写点：
- 请求体大小限制。超过阈值的请求体会被直接截断，或者返回代理自己的错误页。截断的 body 到后端就是半截 JSON，表现为语法错误或编码错误。
- 压缩与解压。有些代理会自动对上游请求做压缩，如果配置了但 header 处理不完整，后端拿到的就是压缩后的字节。
- 字符集转换。极少数老配置会做这种转换，一旦开启，UTF-8 请求可能被转成别的编码。
- 缓冲区行为。代理默认会把请求体完整缓冲后再转发。如果后端做了流式读取，代理的缓冲策略可能影响消息分片方式。
排查这类问题，最有效的办法是绕过代理直连后端。如果直连正常、走代理异常，那答案就已经有了。这一步看起来笨，但它能把排查时间从几小时压缩到几分钟。
6.2 客户端框架的隐式行为
前端这边有几个容易被忽略的默认行为：
fetch不做任何序列化。传对象进去会变成"[object Object]"。这个前面提过，但它值得再强调一次，因为它太安静了。
axios的transformRequest会改你的 body。默认情况下它会检查 body 类型，如果是普通对象就JSON.stringify并设 header。但如果你在拦截器里改过config.data，或者在transformRequest里做了自定义处理，最终发出去的可能不是你预期的形状。
表单序列化库的输出不带引号。qs.stringify({a: 1})出来的是a=1，不是{"a":1}。搞混这两者的场景实在太常见。
某些 HTTP 客户端会对你设置的值做规范化。比如把Content-Type的值自动转小写、去掉多余空格、补上charset。这些规范化大多无害，但在跟严格的中间件配合时可能出问题。
我的习惯是：联调阶段不信任任何客户端的隐式行为，一律显式写出 header 和序列化，哪怕代码看起来啰嗦一点。等接口稳定了，再考虑简化。
6.3 一份可以抄的自检清单
最后把整篇文章的判断逻辑压缩成一份清单，遇到这个报错时从上往下过一遍：
| 顺序 | 检查项 | 判据 | 若不通过 |
|---|---|---|---|
| 1 | 这条 400 是谁返回的 | 响应头是否有代理特征、业务日志是否打印 | 去查代理/网关，不看业务代码 |
| 2 | 服务端实际收到多少字节 | 对比Content-Length与实际读取长度 | 查传输层、限流、截断 |
| 3 | 请求体前 64 字节的十六进制 | 是否存在 UTF-8 之外的多字节序列 | 定位编码问题 |
| 4 | 是否调过stream()或form() | 中间件里有没有相关调用 | 改成body()或加缓存重放 |
| 5 | 原始异常的类型 | 全局处理器打出的cause字段 | 按类型对号入座 |
| 6 | 直连后端是否正常 | 绕过代理发同样请求 | 确认是代理层问题 |
| 7 | 最小请求能否通过 | 单字段 JSON 请求 | 二分法定位到具体字段 |
这张表的顺序不是随便排的。前两项解决"是不是我的问题"，中间三项解决"问题在哪一类"，最后两项是收尾验证。按这个顺序走，基本不会在错误的方向上耗时间。
我个人在实际操作中的体会是，这个报错之所以让人头疼
