卷曲到代码

什么是 cURL？

cURL（Client URL）是一个用于通过 URL 传输数据的命令行工具。它支持 HTTP、HTTPS、FTP 以及许多其他协议。在大多数系统上它已预装——你可以在 macOS、Linux 或 Windows（PowerShell）的任意终端中运行 curl。

cURL 是 API 文档的通用语言。当 API 展示示例请求时，几乎总是一条 cURL 命令。浏览器开发者工具允许你将任意网络请求复制为 cURL。这使 cURL 成为分享和复现 HTTP 请求的通用格式，即使你在生产代码中从不直接使用 cURL。

常用 cURL 选项

-X（或 --request）设置 HTTP 方法：-X POST、-X PUT、-X DELETE。未指定方法时默认为 GET。

-H（或 --header）添加请求头：-H "Content-Type: application/json" -H "Authorization: Bearer token123"。

-d（或 --data）发送请求体并隐含 POST：-d '{"name":"test"}'。使用 --data-raw 发送字面数据，不会把 @ 解释为文件引用。

-F（或 --form）发送 multipart 表单数据：-F "file=@photo.jpg" -F "caption=My photo"。每个 -F 标志添加一个表单字段。

-o（或 --output）将响应保存到文件：-o response.json。-O 使用远程文件名。

-v（或 --verbose）显示完整的请求和响应头——对调试极有价值。

-s（或 --silent）隐藏进度条。-S（或 --show-error）即使在静默模式下也显示错误。可组合使用：-sS。

-L（或 --location）跟随重定向。不加该选项时，cURL 返回 301/302 响应而不是跟随重定向。

从浏览器复制 cURL 命令

所有现代浏览器都允许将网络请求复制为 cURL 命令。在 Chrome、Firefox 或 Edge 中：打开开发者工具（F12），进入 Network 面板，发起要捕获的请求，右键该请求，选择「Copy as cURL」。

复制的命令包含 URL、方法、所有请求头（包括 cookie 和认证令牌）以及请求体。这是在代码中复现浏览器请求，或与同事分享以便调试的最快方式。

重要提示：复制的命令常常包含会话 cookie 和授权令牌。分享前请移除敏感请求头。粘贴到文档或聊天时，用「Bearer YOUR_TOKEN_HERE」等占位符替换真实令牌。

用 cURL 进行 API 测试

cURL 是无需写代码即可测试 API 端点的最快方式。从 API 文档中的示例 cURL 命令入手，修改参数后在终端运行。

对于 JSON API，请包含 Content-Type 请求头：curl -X POST -H "Content-Type: application/json" -d '{"email":"test@example.com"}' https://api.example.com/users。

要同时查看响应头和响应体，添加 -i。要查看完整的请求/响应交换，添加 -v。要格式化 JSON 输出，通过 jq 管道：curl -s https://api.example.com/users | jq .

测试需要认证的 API 时，将令牌存入变量：TOKEN="your_token"，然后引用：curl -H "Authorization: Bearer $TOKEN" https://api.example.com/me。这样可保持命令历史干净，也便于切换令牌。

从 cURL 到生产代码

在终端中可用的 cURL 命令是一份已验证的请求规范——你知道端点、请求头、方法和请求体都正确。接下来是将其转换为所用语言的 HTTP 客户端。

Dokall 可将 cURL 转换为 JavaScript（fetch 和 axios）、Python（requests 和 http.client）、Go（net/http）、PHP（cURL 扩展）、Rust（reqwest）等。生成的代码会按各语言约定处理请求头格式、请求体序列化和方法指定。

转换后请审阅生成的代码并按生产环境调整：添加错误处理、设置超时、用环境变量存放 API 密钥（切勿硬编码密钥）、为瞬时失败实现重试逻辑，并添加日志。转换后的代码是起点——并非可直接上线的生产代码。

对于常用的 API 调用，将转换后的代码封装为带类型参数和返回值的函数。这样可形成清晰的 API 客户端，应用其他部分无需了解 HTTP 细节即可调用。