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

Индекс LLMS: [llms.txt](/llms.txt)

---

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

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

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

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

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

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

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

> [!NOTE]
> HEAD не гарантирует, что сервер поддерживает диапазоны или кэширование — это зависит от конфигурации.

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

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

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

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

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

> [!TIP]
> Многострочный JSON удобнее читать в heredoc, если тело большое:
> ```bash
> curl -X POST https://api.example.com/users \
>   -H "Content-Type: application/json" \
>   -d @- <<'EOF'
>   {
>     "name": "ivan",
>     "role": "admin"
>   }
>   EOF
> ```

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

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

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

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

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

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

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

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

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

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

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

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

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

> [!WARNING]
> `-u` передаёт credentials в открытом виде (если нет TLS). Для prod-серверов всегда используйте HTTPS.

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

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

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

```bash
# указать 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 ждёт бесконечно. Для скриптов и мониторинга ограничивайте время:

| Флаг | Назначение |
|------|------------|
| `--max-time N` | общий таймаут в секундах |
| `--connect-timeout N` | таймаут подключения |

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

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

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

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

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

## Редиректы

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

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

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

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

> [!NOTE]
> `-L` ограничивает глубину редиректов (по умолчанию 50). Бесконечный цикл редиректов — типичная причина зависания curl.

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

```bash
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 секунд.