Конструктор команд cURL

Конструктор команд cURL превращает сложную команду со множеством флагов в простую пошаговую форму. Вы выбираете метод HTTP, вставляете URL, перечисляете заголовки и параметры запроса по одному на строку, задаете тело запроса и выбираете режим аутентификации — а инструмент автоматически формирует соответствующую команду curl за вас. Интерактивный предпросмотр в стиле терминала обновляется по мере ввода, позволяя увидеть финальный вид команды перед копированием.

Инструмент работает полностью на стороне браузера. Он не выполняет реальных запросов на указанный вами URL и не сохраняет ваши заголовки, токены или тело запроса. Вы получаете готовую к запуску команду, которую можно вставить в терминал, шаг CI, файл Makefile, импортировать в Postman или прикрепить к баг-репорту.

Почему визуальный конструктор лучше написания cURL вручную

Как использовать конструктор команд cURL

1. Выберите метод. GET используется для чтения, POST — для создания, PUT/PATCH — для обновления, DELETE — для удаления, HEAD запрашивает только заголовки, а OPTIONS опрашивает сервер о поддерживаемых методах для ресурса.
2. Введите URL. Лучше всего указывать полный URL, например https://api.example.com/v1/users. Если вы пропустите протокол, конструктор автоматически дополнит его до https://.
3. Укажите параметры запроса. По одному на строку в формате ключ=значение. Оставьте значение пустым для параметров в виде флагов. Конструктор добавит их в конец URL после символа ?.
4. Укажите заголовки. По одному на строку в формате Имя-Заголовка: значение. Конструктор исключает дубликаты и автоматически добавляет корректный Content-Type для тел в формате JSON, form и XML, если вы не указали его вручную.
5. Выберите тип тела запроса. Выберите JSON для вставки объекта, Form для полей application/x-www-form-urlencoded, Multipart для загрузки файлов (используйте имя=@/path/to/file), Raw для отправки байтов «как есть» или XML для SOAP и подобных API.
6. Настройте аутентификацию. Basic для формата логин:пароль, Bearer для токенов OAuth и JWT, API key в виде заголовка (например, X-API-Key) или параметра запроса (например, ?api_key=...).
7. Добавьте флаги. Включайте самые популярные флаги cURL: следовать редиректам, запрашивать сжатие gzip, показывать заголовки ответа, подробный режим (verbose), скрытый режим (silent) или отключать TLS-проверки для локальной отладки.
8. Выберите стиль вывода. Многострочный формат с обратными слэшами удобнее читать в скриптах; однострочный идеально подходит для быстрого копирования и вставки; вариант Windows CMD использует двойные кавычки и удвоенные проценты; вариант PowerShell явно вызывает curl.exe, чтобы избежать конфликтов с системным алиасом PowerShell.
9. Скопируйте и запустите. Нажмите Скопировать команду, вставьте ее в терминал и изучите полученный ответ.

Объяснение стилей вывода

Многострочный (по умолчанию) переносит каждый флаг на новую строку с символом обратного слэша в конце. Этот формат предпочтителен для документации, блогов и шелл-скриптов, так как он отлично читается сверху вниз.

curl \

  -X POST \

  -H 'Content-Type: application/json' \

  --data '{"name":"Jesse"}' \

  'https://api.example.com/v1/users'

Однострочный объединяет все элементы через пробел — идеальное решение для разовой вставки в терминал, отправки в логи или чаты сообщений.

Windows CMD заменяет одинарные кавычки в стиле bash на двойные кавычки (так как CMD не поддерживает одинарные кавычки для строк) и экранирует знаки процента путем их удваивания, благодаря чему команда корректно выполняется из cmd.exe или файлов .bat.

PowerShell явно обращается к исполняемому файлу curl.exe, поскольку в среде PowerShell имя curl по умолчанию является алиасом для командлета Invoke-WebRequest, имеющего совершенно другой синтаксис аргументов.

Кавычки: одинарные против двойных

В bash для Linux и macOS одинарные кавычки являются наиболее надежными, так как bash не раскрывает переменные и обратные кавычки внутри них. Конструктор заменяет каждый символ ' внутри передаваемого значения на экранирующую последовательность '\'', чтобы внешние одинарные кавычки по-прежнему замыкались корректно.

Двойные кавычки подходят в тех случаях, когда нужно сохранить правила экранирования bash, но при этом использовать символы кавычек, которые иначе сложно экранировать. Конструктор экранирует символы $, `, \\ и " внутри двойных кавычек, гарантируя неизменность передаваемого значения.

Шаблоны аутентификации

Basic auth отправляет заголовок Authorization: Basic base64(логин:пароль). Флаг cURL -u логин:пароль выполняет это кодирование автоматически. Всегда используйте HTTPS — аутентификацию basic auth на обычном HTTP можно перехватить без особого труда.

Токены Bearer (OAuth 2.0, JWT, персональные токены доступа GitHub) добавляют заголовок Authorization: Bearer <токен>. Относитесь к токену как к секретному паролю: сразу же отзывайте и перевыпускайте его, если он случайно утек на скриншот, в Slack или логи CI.

API-ключи могут передаваться в заголовке (X-API-Key, X-RapidAPI-Key) или в параметрах запроса (?api_key=...). Использование заголовка считается более безопасным методом, так как URL-адреса часто сохраняются в логах обратных прокси-серверов и истории браузера.

Основные методы HTTP в одном месте

• GET — чтение ресурса. Метод должен быть безопасным и идемпотентным.
• POST — создание нового ресурса или отправка данных, которые не вписываются в семантику GET. Не является идемпотентным.
• PUT — полная замена ресурса по известному URL. Идемпотентный метод.
• PATCH — частичное обновление. В зависимости от API используется JSON Patch (RFC 6902) или merge patch (RFC 7396).
• DELETE — удаление ресурса. Идемпотентный метод.
• HEAD — аналогичен методу GET, но сервер возвращает исключительно заголовки. Используется для проверки актуальности кэша или размера контента без скачивания всего тела.
• OPTIONS — запрос к серверу для получения списка разрешенных методов и метаданных CORS.

Устранение неполадок в сгенерированной команде

• Ошибки SSL-сертификатов. Включайте флаг --insecure только для доверенных хостов или ваших локальных серверов. Для отладки на продакшене рекомендуется явно указывать cURL правильный бандл CA с помощью флага --cacert.
• Пустой ответ или зависание запроса. Запустите команду с флагом подробного вывода -v, чтобы проанализировать этапы TLS-рукопожатия и заголовки. Зависание на этапе подключения обычно указывает на недоступность сервера; зависание на этапе передачи означает, что сервер принял запрос, но отвечает слишком медленно.
• 415 Unsupported Media Type. Сервер ожидает другой тип контента в Content-Type. Конструктор автоматически подставляет нужное значение для тел JSON, form и XML, если вы не задали его вручную.
• 401 против 403. Код 401 означает, что учетные данные отсутствуют или невалидны (перепроверьте токен Bearer); код 403 означает, что учетные данные верны, но у пользователя нет прав на это действие (проверьте области доступа/scopes).
• 413 Payload Too Large. Некоторые вышестоящие серверы (upstreams) ограничивают размер тела запроса в пределах 1–10 МБ. В таких случаях рассмотрите использование эндпоинтов для чанковой (chunked) загрузки или потоковой передачи данных.

Примечания по безопасности и конфиденциальности

• Конструктор работает исключительно на стороне клиента. На вводимый вами URL ничего не отправляется; результатом работы является только сгенерированный текст команды.
• Избегайте вставки действующих продакшен-токенов. Если это необходимо, относитесь к сгенерированной команде как к конфиденциальным данным — не коммитьте ее в публичные репозитории, не отправляйте в чаты с ботами и не прикрепляйте к публичным тикетам.
• В скриптах отдавайте предпочтение переменным окружения: пишите -H 'Authorization: Bearer '"$TOKEN" вместо жесткого кодирования (hard-coding) самого токена. Используйте закрытие одинарной кавычки с переходом в двойные кавычки вокруг переменной, чтобы bash мог корректно ее раскрыть.

FAQ

Можно ли импортировать команду cURL из Chrome DevTools?

Этот конструктор работает в противоположном направлении — он генерирует cURL из заполненной формы. Чтобы выполнить обратное действие, скопируйте запрос как cURL из DevTools и воспользуйтесь специализированным инструментом для парсинга cURL.

Нужно ли предварительно экранировать тело JSON?

Нет. Вставляйте JSON ровно в том виде, в каком он должен быть отправлен. Конструктор самостоятельно позаботится обо всех кавычках, чтобы тело дошло до сервера без искажений.

В чем разница между -d и --data-urlencode?

Флаг -d отправляет байты тела в исходном виде («как есть»). Флаг --data-urlencode выполняет процентное кодирование (percent-encoding) каждого поля — именно так браузер отправляет данные обычной HTML-формы. Конструктор применяет --data-urlencode для типа тела Form, а флаг --data — для JSON, raw и XML.

Как загрузить файл?

Выберите тип тела Multipart form-data и добавьте строку вида avatar=@/Users/jesse/photo.png. Символ @ указывает cURL на необходимость считать содержимое указанного файла.

Почему cURL выдает ошибку «Argument list too long»?

Размер тела запроса превысил лимит на длину аргументов (argv) в вашей командной оболочке. Вместо этого передайте тело в виде ссылки на файл с помощью конструкции --data @body.json.

Поддерживает ли инструмент протоколы HTTP/2 и HTTP/3?

Сам инструмент cURL поддерживает оба протокола с помощью флагов --http2 и --http3, при условии, что ваша локальная сборка cURL была скомпилирована с соответствующими библиотеками. Вы можете вручную дописать любой из этих флагов в сгенерированную команду.