curl 发送 JSON 格式 POST 请求：参数、转义与排查实践

1. 每次对接新接口我第一反应还是打开终端敲 curl干这行时间久了工具换来换去但 curl 始终留在最顺手的位置。不管是照着文档试一个新接口、复现线上返回的异常、还是给同事演示这个请求到底发了什么一条curl命令甩过去比截图、比导出集合文件、比录屏都直接。而这两年绝大多数接口收的都是 JSON 格式的请求体于是如何使用 curl 命令发送 json 格式请求体的 post 请求这件事几乎成了每天都要重复的动作——哪怕你已经敲过几百遍隔一段时间不写还是会回去翻自己以前的笔记。问题就在这儿。这条命令看着只有三四个参数但我在带新人的时候发现能一次敲对、并且说清楚每个参数为什么这么写的人并不多。十个里有六七个会在引号、Content-Type、转义这些地方栽跟头报错还都长得差不多不是 400 就是 415要么就是参数解析失败然后就开始怀疑服务端。实际上九成的问题出在命令行本身请求根本没按你以为的样子发出去。这篇东西我想把这条命令彻底拆开讲一次 POST 请求由哪几块拼成每个参数省掉会怎样请求体变长以后怎么改成文件出了错从哪一步开始查Windows 和类 Unix 系统下的引号差异怎么处理。不管你是刚接触接口调试的在校同学还是天天跟网关打交道的后端都能直接拿去用。1.1 一条命令背后其实只有四块积木很多人学 curl 是抄一条能跑的命令改改 URL 和参数这样能应付一时但环境一换就废。真正要理解的是这四块积木方法method—— 告诉服务端你要做什么POST 表示提交数据。地址URL—— 协议、域名、端口、路径、查询串。请求头header—— 描述请求体的格式、身份凭证、期望的响应形态。请求体body—— 真正承载数据的那一段 JSON 文本。这四块里前三块是信封最后一块是信纸。curl 的坑几乎全在信封和信纸对不上这件事上你明明写了 JSON但没告诉服务端这是 JSON服务端就按表单去解析解析不出来回你一个 400 或者 415。或者你在信封上写了 JSON但信纸被 shell 的引号规则啃掉了一个大括号服务端收到的是残缺内容同样报错。所以后面所有章节本质上都是在解决一个问题让 curl 原封不动地把你想发的字节送到服务端并且在信封上写清楚它是什么。1.2 图形工具那么好用为什么还留着命令行有人会问现在接口调试工具有的是可视化、能存集合、能生成代码为什么还要折腾命令行。我的理由是三条。第一条是可复现。命令行是一段纯文本可以贴进工单、贴进文档、贴进代码注释别人复制粘贴就能跑出一样的结果。图形工具的截图做不到这一点配置导出也常有版本兼容问题。第二条是够近。图形工具帮你把很多细节藏起来了藏起来的东西恰恰是出问题时最需要看的。命令行里每个头都是你自己写的出问题时你心里清楚自己写了什么排查路径短得多。第三条是能进脚本。一旦某个请求需要重复跑、需要批量跑、需要挂在定时任务里跑命令行天然就是脚本的一部分。图形工具到这一步就得靠导出代码绕一圈又回到命令行。当然命令行也有代价引号、转义、换行、编码这些在图形界面里被自动处理掉的东西在命令行里全得你自己负责。这就是接下来要重点讲的部分。1.3 新手最容易在第一步埋下的三个雷在展开细节之前我先把最常见的三个雷点摆出来你可以对照着看自己有没有中招。雷点一只写了-d没写Content-Type。curl 在只给-d的情况下默认把请求头设成application/x-www-form-urlencoded。这是个表单格式服务端的 JSON 解析器看到这个类型要么直接拒绝415要么尝试按表单读读出来是空。这个雷的迷惑性在于命令能跑通、有响应只是响应内容是错的。雷点二以为单引号在所有系统上都一样。在 bash、zsh 里单引号里的内容原样保留是写 JSON 最省心的方式。但 Windows 的 cmd 不认单引号PowerShell 对单双引号的处理又是另一套逻辑。同一条命令从文档里复制到 Windows 终端大概率直接报语法错误。雷点三JSON 里的双引号和外层引号打架。用双引号包 JSON 时里面每个都要转义成\漏一个就整段结构断裂。这类错误往往不会立刻报出来而是变成字段对不上值是空的这种更绕的问题。提示如果你只想记住一句话那就是——外层优先用单引号里面放心写双引号实在要用双引号就把内层双引号全部转义或者干脆把 JSON 写进文件。2. 最小可用命令四个参数逐个拆开讲先把最短能跑的那条命令摆出来。假设要往某个示例服务提交一条订单路径是/v1/orderscurl -X POST https://api.example.com/v1/orders \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_TOKEN \ -d {sku:A-1001,qty:2,note:加急}这条命令里出现了-X、-H、-d三类参数加上 URL。看着简单但每个都有讲究下面挨个说。2.1-X POST到底要不要写先说结论带了-d或--data、--data-binary、--json的时候-X POST可以省略curl 会自动把方法设成 POST。因为-d的语义就是提交一段数据默认动词自然是 POST。那为什么很多文档还是写上了两个原因。一是显式声明可读性好别人一眼能看出这是个 POST二是在某些组合场景下确实需要它比如你用-d传数据但希望方法是 PUT 或者 PATCHcurl -X PUT https://api.example.com/v1/orders/1001 \ -H Content-Type: application/json \ -d {qty:3}这种情况如果不写-X PUTcurl 会按 POST 发出去服务端路由匹配不上回你 405。所以我的习惯是默认方法就用 POST 时省略-X非 POST 时一定写清楚。另外提醒一句有些老教程里会写-XPOST不带空格这种写法也能用但和后面的参数连在一起时容易看错建议还是分开写。还有一个容易踩的点如果你用-G把数据拼到查询串上curl 会把方法改回 GET。这时候再叠加-X POST就会出现方法说是 POST数据却在 URL 里的怪状态服务端可能两边都读也可能都不读。这种组合除非你明确知道自己在干什么否则别这么写。2.2Content-Type漏掉的后果比你想的严重-H Content-Type: application/json是整条命令里最不能省的一行。原因前面提过curl 在没有指定内容类型时默认按application/x-www-form-urlencoded处理-d带的数据。这会导致什么举两个真实场景。第一种服务端用的是严格的 JSON 解析中间件看到内容类型不是 JSON直接返回 415 Unsupported Media Type连业务逻辑都不进。第二种服务端用的是宽松解析——不管什么类型都尝试读 body 再反序列化这种看起来能成功但一旦它先走了表单解析器你传的{a:1}会被当成一个键名为{a:1}、值为空的东西字段全部丢失最后报的是缺少必填参数让人误以为是参数名写错了。还有一个细节大小写和空格。Content-Type: application/json这个头名大小写不敏感但冒号后面的空格是建议保留的。写成Content-Type:application/json没有空格某些严格的解析器会认某些会出问题。另外如果你需要指定字符集写成application/json; charsetutf-8更保险尤其是请求体里带中文的时候。顺带说一句Accept头。它不是必须的但建议加上-H Accept: application/json。服务端有时会根据Accept决定返回 JSON 还是 HTML 错误页加上它返回的内容更好解析。2.3-d、--data-raw、--data-binary、--json怎么选这几个参数长得像行为差别不小选错了会出隐蔽的 bug。-d也就是--data它会把内容里的换行符去掉多个-d之间用连接。这个去换行的特性在传 JSON 时通常没影响因为压缩成一行照样是合法 JSON。但如果你传的是需要保留格式的内容比如带换行的文本字段就会出问题。--data-raw和-d行为基本一致区别在于它不把开头的当作读文件的标记。也就是说如果你的 JSON 内容恰好以开头很少见用--data-raw才不会误读文件。--data-binary是最老实的一个原样发送不做任何换行处理。需要从文件读请求体时我基本都用它因为能保证字节级一致调试签名、计算哈希这类场景全靠它。--json是较新版本 curl 提供的语法糖一次搞定三件事把请求体设成你给的内容、自动加Content-Type: application/json、自动加Accept: application/json同时隐含 POST。如果你的 curl 版本够新7.82.0 之后用它确实省事curl --json {sku:A-1001,qty:2} https://api.example.com/v1/orders但要注意--json在旧版本上不存在团队协作时如果同事的环境版本较低命令会直接报unknown option。所以我对外分享的命令默认还是写完整的-H加-d兼容性最好。参数换行处理开头含义典型场景-d/--data去掉换行读文件短小内联 JSON--data-raw去掉换行当普通字符内容以开头--data-binary原样保留读文件从文件读、需字节一致--json原样保留读文件新版 curl图省事2.4 三层引号单引号、双引号、转义符这是新手翻车率最高的地方值得单独拆开讲。单引号...在 bash、zsh、sh 里单引号内的所有字符原样保留变量不展开、反斜杠不转义。写 JSON 最舒服因为 JSON 本身大量使用双引号套在单引号里完全不用管。双引号...里面的$、反引号、反斜杠会被 shell 处理。所以双引号包 JSON 时内层的双引号必须写成\否则 shell 会认为字符串提前结束了curl -X POST https://api.example.com/v1/orders \ -H Content-Type: application/json \ -d {\sku\:\A-1001\,\qty\:2}这条命令能用但可读性差改一个字段就要数半天引号。单引号里要写单引号怎么办JSON 里用不到单引号但如果你的内容里有撇号或者 SQL 片段就得用\这种拼接写法先闭合单引号写一个转义的单引号再重新开单引号。看着别扭但这是 shell 的标准做法。Windows 的情况完全不一样。cmd 不认单引号必须整体用双引号包内部双引号用\转义curl -X POST https://api.example.com/v1/orders ^ -H Content-Type: application/json ^ -d {\sku\:\A-1001\,\qty\:2}注意续行符是^而不是\。PowerShell 里更麻烦它对双引号内的转义和 cmd 不同还涉及{}的解析问题。我的建议是在 Windows 上不要在命令行里直接拼 JSON一律写成文件用-d file.json传。这一条能省掉你八成的时间。注意不要把 JSON 用单引号包起来再放到双引号里也别指望\在所有 shell 里都一样。判断标准很简单——先echo一下你要传的那段字符串看看输出是不是你期望的样子再塞进 curl。3. 请求体变复杂之后从一行命令到可维护的写法内联 JSON 只适合字段少、结构平的场景。真实项目里一个请求体动辄几十个字段、嵌套两三层还有数组、布尔、null、时间戳全塞在一行命令里既写不对也维护不了。这时候就该换思路了。3.1 把 JSON 落到文件里再发最直接的做法是新建一个payload.json把内容规规矩矩写进去编辑器还能帮你做语法高亮和格式校验然后用引用curl -X POST https://api.example.com/v1/orders \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_TOKEN \ --data-binary payload.json这里几个细节值得说。后面跟文件名curl 会读取文件内容作为请求体。如果写成-表示从标准输入读可以配合管道使用比如cat payload.json | curl ... --data-binary -。用--data-binary而不是-d是为了保证文件里的内容一字不差地发出去。虽然 JSON 去掉换行仍然合法但一旦你以后要加签名字段、要计算内容哈希任何一点改动都会让签名对不上排查起来非常痛苦。一开始就用--data-binary是给未来的自己留后路。文件名建议带版本或场景后缀比如payload.create-order.json、payload.update-qty.json。我见过不少人把十几种请求体都塞进一个body.json改来改去最后分不清哪个是哪个。另外一个实用技巧发送前先做一次语法校验。如果你本机有 Python一行命令就能验证python3 -m json.tool payload.json /dev/null echo OK不 OK 会直接报出出错的行号比等服务端返回解析失败再回来猜快得多。3.2 变量注入与模板化文件方式解决了结构问题但带来了硬编码问题token、订单号、时间戳每次都要改文件很烦。常见做法是用占位符加环境变量。如果 JSON 外层用双引号包在 shell 里$VAR会被展开。但更干净的方式是用envsubst之类的工具先把模板渲染成临时文件export ORDER_SKUA-1001 export ORDER_QTY2 envsubst payload.tpl.json /tmp/payload.json curl -X POST https://api.example.com/v1/orders \ -H Content-Type: application/json \ --data-binary /tmp/payload.json模板文件里写${ORDER_SKU}、${ORDER_QTY}。这样做的好处是模板可以进版本库敏感值走环境变量不会把 token 提交上去。需要注意的是类型问题。envsubst做的是纯文本替换如果你的 JSON 里需要数字2而不是字符串2模板里就别给占位符加引号。这个坑我踩过——把数量替换成了字符串服务端反序列化直接报类型不匹配返回 400查了半天才发现是模板里的引号没去掉。3.3 认证头、自定义头的组合除了Content-Type实际请求通常还要带认证信息。常见几类认证方式请求头写法备注Bearer Token-H Authorization: Bearer xxx最常见token 别写进脚本明文自定义 Key-H X-Api-Key: xxx头名大小写按文档来签名-H X-Sign: xxx通常与时间戳、请求体内容相关追踪-H X-Request-Id: abc123排查问题时非常有用我强烈建议加上X-Request-Id值用随机串。服务端日志里如果有这个字段出问题时你能一秒定位到那一条日志而不用按时间范围去捞。生成方式很简单uuidgen或者date %s%N都行。还有一个头的坑值得单独提Expect: 100-continue。当请求体超过一定大小通常是 1024 字节时curl 会自动先发一个Expect: 100-continue头等服务端回复 100 再发 body。这在标准 HTTP 里没问题但一些老的网关、反向代理处理不好表现是命令卡住几秒然后超时。解决办法是显式禁掉它-H Expect:冒号后面什么都不写就是这个头被移除的意思。这个技巧在传大 JSON 文件时特别有用遇到请求一直不返回的情况可以先试它。3.4 响应端处理只看你想看的那部分命令发出去只是前半程后半程是读响应。curl 默认把响应体打到标准输出格式紧凑、中文可能乱码、几百个字段糊成一片。几个参数能大幅改善体验。-s静默模式不显示进度条和错误摘要-S配合-s使用静默但仍显示错误信息。这两个组合起来是-sS脚本里的标配。-o resp.json把响应体写进文件-D headers.txt把响应头单独存一份。排查问题时这两份文件很有价值尤其是响应头里的X-Request-Id、Set-Cookie、Content-Encoding。-w自定义输出可以在响应体之后追加状态码、耗时等信息curl -sS -o resp.json -w code%{http_code} time%{time_total}s\n \ -X POST https://api.example.com/v1/orders \ -H Content-Type: application/json \ --data-binary payload.json%{http_code}是状态码%{time_total}是总耗时%{time_connect}是建立连接耗时%{size_download}是下载字节数。把耗时打出来能快速判断是网络慢还是服务端处理慢。格式化响应体的首选是jqcurl -sS -X POST https://api.example.com/v1/orders \ -H Content-Type: application/json \ --data-binary payload.json | jq .jq .做美化jq .data.id直接取字段jq -r去掉引号方便塞进变量。这玩意儿配上 curl基本能把接口调试的活干完。4. 一次完整实操从连通性验证到拿到数据光讲参数容易散我把一次完整的联调过程按顺序走一遍你可以照着复现。4.1 第一步先别急着发 JSON拿到一个新接口我从来不先写完整命令而是先确认三件事域名能不能解析、端口通不通、路径对不对。用一个最简单的 GET 探路curl -sS -i --max-time 5 https://api.example.com/v1/orders-i表示把响应头一起打出来。这时候你会看到几种结果200 或 400 说明连通没问题可以继续404 说明路径写错了去看文档403 说明路径对但没权限需要检查认证头连接超时或者Could not resolve host那问题在网络层跟 JSON 一点关系都没有别在这里浪费时间调参数。这一步的意义在于把变量分开。如果一上来就发完整命令报错了你不知道是网络问题、路径问题、认证问题还是 body 问题四个变量搅在一起。先探路能把排查范围直接砍掉一半。4.2 用-v看清请求真正长什么样确认连通之后加上-v发一次真实请求。-v会打印出 curl 实际发出的请求行、请求头以及服务端返回的响应头。输出大概长这样 POST /v1/orders HTTP/1.1 Host: api.example.com Content-Type: application/json Content-Length: 46 HTTP/1.1 201 Created Content-Type: application/json重点看两行Content-Type是不是你期望的值Content-Length是不是和你估的差不多。如果Content-Length比你想的短很多说明 body 被 shell 啃掉了一块引号或者转义出问题了。如果它干脆是 0说明-d后面的内容被当成空字符串了。-v和-i的区别要分清-i只显示响应头加响应体-v显示整个交互过程包括请求头。调试请求构造问题时用-v看返回内容时用-i就够了。如果还嫌不够细--trace-ascii trace.txt能把每一个字节的收发都记下来适合排查编码、分块传输这类底层问题。注意-v的输出默认走标准错误流如果你用 resp.json重定向响应体照样能被正确存下来不会污染文件。4.3 加上超时和重试把命令变成能进脚本的东西临时敲的命令可以不管超时但一旦要放进脚本或者定时任务就必须加约束否则某次网络抖动就能让整个流程卡死。curl -sS \ --connect-timeout 3 \ --max-time 15 \ --retry 3 \ --retry-delay 2 \ --retry-connrefused \ -X POST https://api.example.com/v1/orders \ -H Content-Type: application/json \ -H Expect: \ --data-binary payload.json \ -o resp.json \ -w code%{http_code} time%{time_total}s\n--connect-timeout 3限制建立连接的时间--max-time 15限制整个请求的时长。这两个值怎么定我的经验是连接超时设 3 到 5 秒因为正常的内网或同城调用建立连接不该超过这个数总超时按业务耗时设先跑几次看time_total的分布取一个比 P99 稍大的值留出余量但不至于让用户干等。--retry只对幂等安全的错误重试包括连接失败、超时、以及部分 5xx 状态码。--retry-connrefused是额外的开关让连接被拒绝时也重试。但要注意POST 请求默认也会被重试如果服务端没有做幂等处理重试可能造成重复下单。这种情况下要么去掉重试要么在请求体里带一个唯一业务号让服务端去重。还有一个细节加了--retry之后拿到的返回值可能是最后一次重试的结果中间失败的次数不会告诉你。如果你需要知道重试了几次-w里的%{num_retries}变量可以打出来。4.4 保存请求和响应方便回放和对比联调过程中最浪费时间的事是刚才那条命令跑出问题了但我改了几笔之后复现不出来了。解决办法很简单把命令和历史响应都存下来。我自己的习惯是在项目里建一个debug/目录每条命令跑完自动存两份文件resp-时间戳.json和headers-时间戳.txt。命令本身写进一个history.sh加上注释说明场景。三次之后你就会发现回头查上周那个 400 是怎么解决的变得特别容易。对比两次响应也很常用。用diff看两份响应体的差异用jq -S .先做键排序再比能过滤掉字段顺序带来的噪音。这招在排查同一份请求A 环境成功、B 环境失败时特别好使。5. 常见报错与排查速查表这部分是我这些年攒下来的经验清单遇到问题可以直接对照。5.1 状态码类问题400、415、401、302状态码常见原因第一步检查400 Bad Requestbody 结构不合法、字段类型错、缺必填用-v看 Content-Length用 Python 校验 JSON415 Unsupported Media Type没写Content-Type: application/json补上这个头注意冒号后空格401 Unauthorizedtoken 缺失、过期、格式不对检查头名和Bearer后面的空格403 Forbidden权限不足、IP 白名单、签名错确认账号权限核对签名算法404 Not Found路径错、方法错用了 GET 打 POST 路由核对文档路径与方法405 Method Not Allowed方法用错或-X写了但被覆盖显式写-X POST302 Found服务端要求跳转curl 默认不跟随需要跟进用-L但要处理 body 丢失500 Internal Server Error服务端挂了或你的数据触发异常拿X-Request-Id找服务端日志重点说两个。415 的问题是请求头不是请求体。很多人看到 415 第一反应是我的 JSON 写错了实际上服务端压根没解析 body它是在检查内容类型这一步就拒了。补上-H Content-Type: application/json基本就解决。302 是个陷阱。加-L跟随跳转curl 会把 POST 改成 GET 重发请求体直接丢掉。如果你的接口有 HTTP 到 HTTPS 的跳转就会遇到明明请求体没问题服务端说没收到参数的怪事。解决办法是加上--post301 --post302 --post303让 curl 在跳转后继续保持 POST 方法和请求体。这几个参数知道的人不多但非常关键。5.2 引号、转义与 shell 吃掉字符这类问题最隐蔽因为报错信息不指向根因。判断方法很直接发之前先 echo。echo {sku:A-1001,qty:2}如果输出和你写的对不上说明引号就被 shell 处理掉了curl 收到的就是残缺内容。常见表现有三种。一是Content-Length偏小。前面提过用-v一眼能看出来。二是 JSON 里出现了未转义的换行。多行 JSON 放在双引号里如果没处理好续行实际内容会带换行某些严格解析器会拒绝。三是变量意外展开。双引号里的$会被 shell 替换成变量值如果你的 JSON 恰好包含$字符比如金额字段就会被吃掉。用单引号或者对$转义可以避免。还有一类是中文被转成\uXXXX或者显示成乱码。这通常不是 curl 的问题是终端的编码设置。验证方法是用-o写到文件再看如果文件里正常、终端里乱码那就是终端设置不影响实际请求。5.3 中文、编码与文件格式涉及中文的请求体我吃过两次亏都是文件格式的锅。第一次是文件保存成了带 BOM 的 UTF-8。BOM 是文件开头三个不可见字节JSON 解析器看到它会直接报非法字符而且报错位置在第 1 行第 1 列看着像是内容有问题。解决办法是用编辑器另存为UTF-8 无 BOM或者在 Linux 下用sed -i 1s/^\xEF\xBB\xBF//去掉。第二次是 Windows 上编辑的文件带了 CRLF 换行。JSON 里如果有换行CRLF 和 LF 本身不影响解析但如果你的某个字段值是字符串且需要精确比较多出来的\r会让比较失败。用file payload.json看一眼或者cat -A检查行尾。编码方面还要注意字符集声明。虽然 JSON 标准规定必须用 UTF-8但有些老服务会读Content-Type里的 charset没写就按默认编码解析。加上; charsetutf-8更保险成本为零。5.4 三个系统上的差异清单项目Linux / macOSWindows cmdPowerShell单引号包字符串支持内容原样不支持支持但有额外解析续行符\^反引号双引号内转义\\反引号转义{}解析无问题无问题可能被当脚本块推荐写法单引号内联文件传 body文件传 body 或curl.exePowerShell 那一栏要单独说一句。PowerShell 会把{}当作脚本块的一部分去解析curl又是Invoke-WebRequest的别名同一条命令在这里行为完全不同。两个应对办法一是显式写curl.exe而不是curl绕开别名二是干脆不拼内联全部走文件curl.exe -X POST https://api.example.com/v1/orders -H Content-Type: application/json --data-binary payload.json这个写法在 PowerShell 里是最省心的我建议所有 Windows 用户默认就用它。6. 用了很多年才定下来的几个书写习惯聊到最后分享几个不算技术但确实省时间的小习惯都是我改过很多次才定型的。第一参数顺序固定成地址、头、体、输出。先 URL再所有-H再 body 相关最后输出控制。固定顺序的好处是扫一眼就知道这条命令干了什么也方便用脚本批量改。我见过有人把-H夹在-d后面虽然能跑但读起来费劲。第二凡是超过三个字段的 JSON一律走文件。这个界限是我踩坑踩出来的。三个字段以内内联改起来快超过三个引号和转义的维护成本就超过文件方式的成本了。第三命令里永远带-sS。不带的话进度条会污染输出混进jq里就报解析错误只带-s不带-S出错时一片安静你会以为请求成功了。第四调试阶段一定加-v进脚本一定去掉。-v的输出很有用但会写到标准错误脚本里如果不处理日志会被塞满。第五把跑通的命令存成带注释的脚本片段。我电脑上有个snips.sh里面全是按业务场景分类的 curl 命令每条上面一行注释写着这个接口要传 X-Request-Id不然会 400这种只有自己踩过才知道的信息。三个月后再回来看这些注释比任何文档都值钱。再补一个小技巧如果服务端返回的是紧凑 JSON 且中文变成\uXXXX别急着怀疑编码先jq .一下jq默认会把 Unicode 转义还原成中文。如果jq输出正常而直接输出乱码那就是终端的问题请求本身没错。判断清楚这一点能省掉很多无效的排查时间。