计算机网络 / 系统课时

使用 curl 完成接口联调

使用 curl 完成接口联调

这篇用 curl 完成查询参数、JSON 请求、HTTP 认证和文件上传,并分别检查状态码、响应头与响应体。示例按 Bash 编写;Windows PowerShell 5.1 请显式运行 curl.exe,避免同名别名干扰。

学习目标

  • 用 curl 构造查询参数、JSON 请求体、认证头和 multipart 文件上传。
  • 分别查看状态码、响应头和响应体,快速判断问题在客户端还是服务端。
  • 使用退出码和 --fail-with-body 把人工联调变成可判定的命令。

先确认状态码和响应类型

联调时不要只看正文。先用 -o 保存响应体,再用 -w 输出状态码和内容类型。下面请求公开测试服务 https://httpbin.org/get;-sS 隐藏进度条,但仍保留错误信息。

bash
curl -sS -o /tmp/httpbin-body.json -w 'status=%{http_code} type=%{content_type}\n' https://httpbin.org/get

预期输出:

text
status=200 type=application/json

实际 Content-Type 可能附带字符集等参数,因此自动化判断时优先检查状态码,并根据接口约定决定是否严格匹配媒体类型。需要看完整响应头时使用 -i,只保存响应头可用 -D headers.txt。

构造查询参数与 JSON 请求

查询参数优先使用 -G 配合 --data-urlencode,让 curl 负责空格和特殊字符的百分号编码。下面把 q=hello world 和 limit=20 放入 URL,而不是手工把空格改成 %20。

bash
curl -sS -G https://httpbin.org/get --data-urlencode "q=hello world" --data-urlencode "limit=20"

预期结果的 args 字段应包含:

json
{"limit":"20","q":"hello world"}

发送 JSON 时同时指定媒体类型和正文。--data 会让 curl 默认发起 POST;在需要明确方法的联调脚本中,也可以补上 -X POST,但不要在 GET 请求里机械添加 -X GET。

bash
curl -sS https://httpbin.org/anything -H "Content-Type: application/json" --data '{"name":"Alice","active":true}'

预期结果的 json 字段应包含:

json
{"active":true,"name":"Alice"}

如果服务端收到的 json 为 null,先检查 Content-Type 是否正确,再检查引号是否被当前 shell 改写。Bash 中用单引号包住 JSON 最省事;在 Windows cmd.exe 中需要改用适合该 shell 的转义规则。

发送认证请求

Basic 认证可用 -u 用户名:密码,curl 会生成 Authorization: Basic ... 请求头。凭据只是编码而不是加密,因此实际业务接口必须通过 HTTPS 发送。下面的测试端点只有在用户名和密码同时匹配时才返回 200。

bash
curl -sS -u alice:s3cr3t https://httpbin.org/basic-auth/alice/s3cr3t

预期输出:

json
{"authenticated":true,"user":"alice"}

Bearer Token 通常直接写请求头:-H "Authorization: Bearer <ACCESS_TOKEN>"。令牌属于敏感信息,不要把真实值提交到 Git,也不要在共享终端截图里展示。排查认证失败时先确认是 401 还是 403:前者通常表示缺少或无效凭据,后者表示身份已识别但权限不足。

上传 multipart 文件

文件上传常用 -F,它会生成 multipart/form-data 及正确的 boundary。下面先创建一个临时文本文件,再同时上传文件字段 file 与普通表单字段 note。

bash
printf 'hello curl\n' > /tmp/demo.txt
curl -sS https://httpbin.org/post -F "file=@/tmp/demo.txt;type=text/plain" -F "note=report"

预期结果的关键字段应包含:

json
{"files":{"file":"hello curl\n"},"form":{"note":"report"}}

不要手工写 Content-Type: multipart/form-data,否则很容易漏掉 boundary;让 -F 自动生成即可。若接口要求字段名为 attachment,就必须把命令中的 file= 改成 attachment=,字段名不匹配时服务端通常拿不到文件。

把联调结果变成可判定检查

curl 默认即使收到 404 也可能以退出码 0 结束,因为 HTTP 错误状态本身不等于传输失败。curl 7.76.0 及以上可以使用 --fail-with-body:当状态码为 400 及以上时返回非零退出码,同时保留响应体,适合 CI 或脚本联调。

bash
curl --fail-with-body -sS -o /tmp/body.txt -w 'status=%{http_code}\n' https://httpbin.org/status/204
printf 'exit=%s\n' "$?"

预期输出:

text
status=204
exit=0

遇到超时可加 --connect-timeout 3 --max-time 10,遇到重定向需要跟随时使用 -L。只有在排查 TLS、代理或请求头细节时再开 -v;它可能打印认证头等敏感信息,日志需要脱敏。联调脚本最终至少应判定状态码、curl 退出码和业务响应字段,三者一起看比“肉眼看起来成功”可靠得多。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 curl 完成接口联调

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通