curl 入门：在终端里测试 API

curl 就是在终端里发 HTTP 请求的工具，浏览器能做的事，它都能做，而且更灵活。这篇把 curl 的常用参数逐个拆清楚，看完再回去看那些常用的API测试命令就不会有盲区了。

一、curl 是什么

curl（发音 "see URL"）是一个命令行工具，用来向服务器发送 HTTP 请求并显示响应。几乎所有 Linux 和 macOS 系统都预装了，Windows 10 以上也自带。

验证一下当前环境里有没有这个工具：

bash 复制代码

curl --version
# curl 8.4.0 ...

能打出版本号就说明可以直接用。

为什么不用浏览器测试？

浏览器只方便测 GET 请求（在地址栏输入 URL）。但登录接口是 POST 请求，还要带 JSON 数据和自定义请求头。浏览器地址栏做不了这些事。curl 可以精确控制请求的每一个细节。

二、最简单的用法

bash 复制代码

curl http://localhost:5000/hello

就这样，不加任何参数。curl 向这个 URL 发一个 GET 请求，把服务器返回的内容打印到终端：

复制代码

你好，世界

和你在浏览器地址栏输入 http://localhost:5000/hello 然后回车是一回事。

三、参数详解

例如复杂的 curl 命令可能长这样：

bash 复制代码

curl -X POST http://localhost:5000/login \
  -H "Content-Type: application/json" \
  -d '{"username": "zhangsan", "password": "123456"}'

看着一大串，其实就三个参数。先说一个前置知识：命令末尾的 \ 是换行续写符 ，告诉终端"这行没写完，下一行还是同一条命令"。去掉 \ 写成一行也完全一样，只是太长了不好看。

一条 curl 命令拆开就四个部分：工具名 + 请求方法 + 请求头 + 请求体。

3.1 `-X`：指定请求方法

bash 复制代码

curl -X POST http://localhost:5000/login

-X 后面跟 HTTP 方法。不写 -X 默认是 GET。

bash 复制代码

curl http://localhost:5000/hello          # GET（默认）
curl -X POST http://localhost:5000/login  # POST
curl -X PUT http://localhost:5000/user/1  # PUT
curl -X DELETE http://localhost:5000/user/1  # DELETE

查看信息用 GET，登录/注册/刷新 Token 用 POST。

3.2 `-H`：设置请求头

bash 复制代码

-H "Content-Type: application/json"

-H 后面跟一个请求头，格式是 "名字: 值"。请求头是 HTTP 请求的元信息，不是正文数据，而是告诉服务器一些附加信息。

常用的两个请求头：
- Content-Type: application/json ：告诉服务器"我发的请求体是 JSON 格式"。没有这个头，Flask 的 request.json 会返回 None，后面的代码就炸了。
- Authorization: Bearer eyJhbGciOi...：带上 JWT Token。服务器从这个头里取出 Token 做验签。

可以同时设多个请求头，写多个 -H：

bash 复制代码

curl http://localhost:5000/profile \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Accept: application/json"

3.3 `-d`：发送请求体

bash 复制代码

-d '{"username": "zhangsan", "password": "123456"}'

-d（data）后面跟要发送的数据，放在 HTTP 请求体里。这就是服务器端 request.json 读到的内容。

注意：如果使用 -d显示设置请求体，curl 会自动把请求方法改成 POST。所以下面两种写法效果一样：

bash 复制代码

# 显式写 -X POST
curl -X POST http://localhost:5000/login \
  -d '{"username": "zhangsan"}'

# 省略 -X POST，-d 会自动触发 POST
curl http://localhost:5000/login \
  -d '{"username": "zhangsan"}'

但 -d 不会自动加 Content-Type: application/json 头。curl 默认的 Content-Type 是 application/x-www-form-urlencoded（表单格式），不是 JSON。所以发 JSON 数据时 -H "Content-Type: application/json" 不能省，省了服务器不知道你发的是 JSON。

四、auth 系列里的四种典型用法

把上面学的参数组合起来使用。

4.1 模式一：GET 请求，不带参数

最简单的情况，获取公开数据：

bash 复制代码

curl http://localhost:5000/hello

不需要任何参数。

4.2 模式二：POST 请求，带 JSON 数据

bash 复制代码

curl -X POST http://localhost:5000/login \
  -H "Content-Type: application/json" \
  -d '{"username": "zhangsan", "password": "123456"}'

三件套：-X POST + -H 声明 JSON + -d 带数据。

4.3 模式三：GET 请求，带 Token

访问受保护接口，不用传数据，但要证明身份：

bash 复制代码

curl http://localhost:5000/profile \
  -H "Authorization: Bearer eyJhbGciOi..."

只需要一个 -H 带上 Token。

Session 方案里，登录后服务器会在响应里设置 Cookie。后续请求要把 Cookie 带回去：

bash 复制代码

# 登录，-c 把服务器返回的 Cookie 保存到文件
curl -X POST http://localhost:5000/login \
  -H "Content-Type: application/json" \
  -d '{"username": "zhangsan", "password": "123456"}' \
  -c cookies.txt

# 后续请求，-b 带上之前保存的 Cookie
curl http://localhost:5000/profile -b cookies.txt

-c（cookie jar）把响应里的 Cookie 保存到文件，-b（cookie）从文件读 Cookie 带到请求里。

五、四个实用技巧

5.1 中文显示成 \uXXXX？

如果你用 curl 测试 Flask 接口，发现中文变成了这样：

json 复制代码

{"error": "\u7f3a\u5c11 Token"}

这不是 curl 的问题，是 Flask 的 jsonify 默认把中文做了转义。在 Flask 代码里加一行就能解决：

python 复制代码

from flask import Flask
app = Flask(__name__)

app.json.ensure_ascii = False

加了之后返回的就是正常中文：{"error": "缺少 Token"}。

5.2 查看完整的请求和响应：-v

加了 -v（verbose），curl 会打印完整的请求头和响应头，方便排查问题：

bash 复制代码

curl -v http://localhost:5000/hello

复制代码

> GET /hello HTTP/1.1          ← 请求行
> Host: localhost:5000         ← 请求头
> User-Agent: curl/8.x.x
>
< HTTP/1.1 200 OK             ← 响应状态行
< Content-Type: application/json  ← 响应头
<
{"message": "你好，世界"}     ← 响应体

> 开头的是你发出去的，< 开头的是服务器返回的。当接口返回的不是你预期的结果时，先加 -v 看看请求和响应的细节。

5.3 格式化 JSON 输出：管道 + python

curl 返回的 JSON 默认是紧凑的一行，不好看。管道给 Python 格式化一下：

bash 复制代码

curl http://localhost:5000/profile \
  -H "Authorization: Bearer eyJ..." \
  | python -m json.tool

json 复制代码

{
    "message": "你好，zhangsan",
    "role": "user"
}

python -m json.tool 是 Python 自带的 JSON 格式化工具，不需要安装任何东西。

5.4 静默模式：-s

curl 默认会显示下载进度条，在脚本里会很吵。加 -s（silent）关掉：

bash 复制代码

curl -s http://localhost:5000/hello

六、总结

参数	作用	例子
（无参数）	发 GET 请求	`curl http://localhost:5000/hello`
`-X POST`	指定请求方法	`-X POST`、`-X PUT`、`-X DELETE`
`-H "..."`	设置请求头	`-H "Content-Type: application/json"`
`-d '{...}'`	发送请求体数据	`-d '{"username": "zhangsan"}'`
`-c file`	保存 Cookie 到文件	`-c cookies.txt`
`-b file`	从文件读 Cookie	`-b cookies.txt`
`-v`	显示完整请求/响应细节	排查问题时用
`-s`	静默模式，不显示进度条	脚本里用

curl 的参数远不止这些，记住最核心的组合：-X 定方法、-H 加请求头、-d 带数据。这三个覆盖了 90% 的 API 测试场景。

curl 入门：在终端里测试 API

一、curl 是什么

二、最简单的用法

三、参数详解

3.1 -X：指定请求方法

3.2 -H：设置请求头

3.3 -d：发送请求体

四、auth 系列里的四种典型用法

4.1 模式一：GET 请求，不带参数

4.2 模式二：POST 请求，带 JSON 数据

4.3 模式三：GET 请求，带 Token

4.4 模式四：带 Cookie

五、四个实用技巧

5.1 中文显示成 \uXXXX？

5.2 查看完整的请求和响应：-v

5.3 格式化 JSON 输出：管道 + python

5.4 静默模式：-s

六、总结

3.1 `-X`：指定请求方法

3.2 `-H`：设置请求头

3.3 `-d`：发送请求体