curl: отладка HTTP в терминале

cURL — стандартный инструмент отладки HTTP в терминале. Работает из коробки в Linux и macOS, есть в большинстве Docker-образов. Если нужно быстро проверить API, посмотреть заголовки ответа или отловить проблему с редиректом — одной строки достаточно.

Базовые флаги отладки

Самый частый сценарий — получить ответ и увидеть, что сервер отдал. Ключ -i выводит заголовки перед телом, -v включает подробный режим с деталями соединения.

curl -i https://api.example.com/health
curl -v https://api.example.com/health

Разница: -i показывает заголовки + тело, -v добавляет DNS-резолв, TLS-handshake и отладочную информацию до запроса.

HEAD-зазапрос проверяет доступность и метаданные ресурса без загрузки тела:

curl -I https://api.example.com/v2/large-file.zip

Методы и тело запроса

По умолчанию curl отправляет GET. Для остальных методов — флаг -X.

curl -X POST https://api.example.com/users
curl -X DELETE https://api.example.com/users/42

Тело запроса передаётся через -d. Для JSON-API типичный паттерн:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "ivan", "role": "admin"}'

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
  {
    "name": "ivan",
    "role": "admin"
  }
  EOF

Для отправки формы или данных из файла:

curl -X POST https://api.example.com/upload \
  -d "username=admin" \
  -d "password=secret"

Кастомные заголовки

Флаг -H добавляет или заменяет заголовок. Комбинация -H можно использовать несколько раз.

curl -X GET https://api.example.com/orders \
  -H "Accept: application/json" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Cache-Control: no-cache"

Переопределение заголовка Host полезно при отладке virtualhost или прокси:

curl -X GET http://10.0.0.5/ \
  -H "Host: example.com"

Удалить стандартный заголовок можно через -H "Accept:" (пустое значение после двоеточия).

Авторизация и сертификаты

Базовая HTTP-авторизация через -u в формате user:password:

curl -u admin:secret https://api.example.com/admin

Для Bearer-токена — через заголовок:

curl -H "Authorization: Bearer eyJhbGci..." https://api.example.com/me

При работе с самоподписанными сертификатами флаг -k отключает проверку:

curl -k https://dev.example.com/api

Для known hosts и pinned-сертификатов:

# указать CA-bundle
curl --cacert /etc/ssl/certs/ca-certificates.crt https://secure.example.com
# проверить сертификат удалённого хоста
curl -v https://secure.example.com 2>&1 | grep "Server certificate"

Таймауты и сохранение ответа

По умолчанию curl ждёт бесконечно. Для скриптов и мониторинга ограничивайте время:

curl --max-time 5 --connect-timeout 2 https://slow-api.example.com

Сохранение ответа:

# в файл с оригинальным именем
curl -O https://example.com/reports/november.csv
# в указанный файл
curl -o report.csv https://example.com/reports/november.csv

stdout перенаправляет тело ответа в пайп:

curl -s https://api.example.com/health | jq .status

Редиректы

Curl не следует редиректам по умолчанию. Флаг -L включает автоматическое перенаправление:

curl -L https://bit.ly/api-status

Для отладки цепочки редиректов:

curl -Lv https://short.link/resource 2>&1 | grep -E "< HTTP|< Location"

Комбинация флагов для полной картины при отладке API:

curl -X POST https://api.example.com/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"item_id": 101, "qty": 2}' \
  -iv --max-time 10 -o response.json

Эта строка покажет заголовки запроса и ответа, тело сохранит в файл, таймаут — 10 секунд.