计算机网络 / 系统课时
使用 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 隐藏进度条,但仍保留错误信息。
curl -sS -o /tmp/httpbin-body.json -w 'status=%{http_code} type=%{content_type}\n' https://httpbin.org/get预期输出:
status=200 type=application/json实际 Content-Type 可能附带字符集等参数,因此自动化判断时优先检查状态码,并根据接口约定决定是否严格匹配媒体类型。需要看完整响应头时使用 -i,只保存响应头可用 -D headers.txt。
构造查询参数与 JSON 请求
查询参数优先使用 -G 配合 --data-urlencode,让 curl 负责空格和特殊字符的百分号编码。下面把 q=hello world 和 limit=20 放入 URL,而不是手工把空格改成 %20。
curl -sS -G https://httpbin.org/get --data-urlencode "q=hello world" --data-urlencode "limit=20"预期结果的 args 字段应包含:
{"limit":"20","q":"hello world"}发送 JSON 时同时指定媒体类型和正文。--data 会让 curl 默认发起 POST;在需要明确方法的联调脚本中,也可以补上 -X POST,但不要在 GET 请求里机械添加 -X GET。
curl -sS https://httpbin.org/anything -H "Content-Type: application/json" --data '{"name":"Alice","active":true}'预期结果的 json 字段应包含:
{"active":true,"name":"Alice"}如果服务端收到的 json 为 null,先检查 Content-Type 是否正确,再检查引号是否被当前 shell 改写。Bash 中用单引号包住 JSON 最省事;在 Windows cmd.exe 中需要改用适合该 shell 的转义规则。
发送认证请求
Basic 认证可用 -u 用户名:密码,curl 会生成 Authorization: Basic ... 请求头。凭据只是编码而不是加密,因此实际业务接口必须通过 HTTPS 发送。下面的测试端点只有在用户名和密码同时匹配时才返回 200。
curl -sS -u alice:s3cr3t https://httpbin.org/basic-auth/alice/s3cr3t预期输出:
{"authenticated":true,"user":"alice"}Bearer Token 通常直接写请求头:-H "Authorization: Bearer <ACCESS_TOKEN>"。令牌属于敏感信息,不要把真实值提交到 Git,也不要在共享终端截图里展示。排查认证失败时先确认是 401 还是 403:前者通常表示缺少或无效凭据,后者表示身份已识别但权限不足。
上传 multipart 文件
文件上传常用 -F,它会生成 multipart/form-data 及正确的 boundary。下面先创建一个临时文本文件,再同时上传文件字段 file 与普通表单字段 note。
printf 'hello curl\n' > /tmp/demo.txt
curl -sS https://httpbin.org/post -F "file=@/tmp/demo.txt;type=text/plain" -F "note=report"预期结果的关键字段应包含:
{"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 或脚本联调。
curl --fail-with-body -sS -o /tmp/body.txt -w 'status=%{http_code}\n' https://httpbin.org/status/204
printf 'exit=%s\n' "$?"预期输出:
status=204
exit=0遇到超时可加 --connect-timeout 3 --max-time 10,遇到重定向需要跟随时使用 -L。只有在排查 TLS、代理或请求头细节时再开 -v;它可能打印认证头等敏感信息,日志需要脱敏。联调脚本最终至少应判定状态码、curl 退出码和业务响应字段,三者一起看比“肉眼看起来成功”可靠得多。