Как правильно добавить custom headers в AJAX jQuery

Быстрый ответ

Если у вас возникают проблемы с заголовками AJAX-запросов, убедитесь в правильности настройке сервера по возврату заголовка Access-Control-Allow-Origin в такой форме:

Access-Control-Allow-Origin: http://yourdomain.com

Для нестандартных заголовков, например, X-Custom-Header, следует прописать их явное разрешение на сервере:

Access-Control-Allow-Headers: X-Custom-Header

Отказывайтесь от попыток установить Access-Control-Request-Headers с помощью jQuery, поскольку это регулируется браузером. Используйте следующий шаблон для AJAX-запроса:

$.ajax({
  url: "https://example.com/api",
  method: 'POST',
  dataType: 'json',
  headers: {
    'Content-Type': 'application/json'
  },
  data: JSON.stringify({ key: 'value' }),
  beforeSend: function(xhr) {
    xhr.setRequestHeader('X-Custom-Header', 'custom_value');
  },
  processData: false,
  success: function(data) { console.log(data); },
  error: function(err) { console.error(err); }
});

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

Объяснение работы CORS и нештатных заголовков

Предварительные запросы: Рукопожатие перед основным общением

Предварительные запросы играют ключевую роль для CORS (Cross-Origin Resource Sharing). Браузеры применяют метод OPTIONS в качестве проверки перед основным запросом, особенно если речь идет о нестандартных заголовках или если запрос относится к нестандартным.

Подробнее об этом расскажет наш спикер на видео

Отправка нестандартных заголовков правильно

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

1. Непосредственно в параметре headers при вызове $.ajax.
2. Используя функцию в параметре beforeSend, обратившись к объекту xhr и применив setRequestHeader.

Настройка сервера: налаживание работы CORS

Серверу нужна правильная обработка OPTIONS запросов, а также включение требуемых Access-Control-Allow заголовков в ответ. В зависимости от конфигурации сервера, вам может понадобиться изменить настройки Apache или nginx.

JSON и Content-Type: отличная пара

Когда вы отправляете данные в формате JSON, обязательно используйте заголовок Content-Type и передавайте данные в виде строки. Как свойство processData: false в настройках AJAX запроса поможет избежать нежелательной обработки данных со стороны jQuery.

Отладка с помощью FireBug: надежный инструмент

Встроенные разработчику средства, такие как FireBug или DevTools в Chrome, идеально подходят для мониторинга пользовательских заголовков в AJAX-запросах и поиска ошибок, если вы столкнулись с проблемами с CORS.

Решение проблем CORS: план Б

Если проблемы с CORS сохраняются, рассмотрите возможность использования API fetch. В сложных ситуациях может потребоваться реализация проксирования на уровне сервера.

Визуализация

Вот как происходит взаимодействие с заголовком Access-Control-Request-Headers при отправке AJAX-запроса через jQuery:

Клиент (🖥️)             AJAX запрос       Сервер (🔐)
     |---------------------->|
     |    Можно ли добавить  |
     |    заголовки вида     |
     |    `Content-Type`?    |
     |<----------------------|
     |          🚦            |

🚦= Ответ сервера:
    "Да, можно добавлять `Content-Type`, `Authorization` и даже картинку милой собачки!"

Получив разрешение от сервера, клиент исполняет запрос:

Клиент (🖥️)                          Сервер (🔐)

     | ------------------------------->
     |   Запрос с установленными заголовками  
     |<-------------------------------

Основная идея: сперва проверяете возможности (🚦), а после уже отправляете необходимые данные!

Разбор практических ситуаций

Динамическое определение доменов

Если ваши клиенты имеют возможность обращаться с различных доменов, убедитесь, что сервер допускает динамическую настройку Access-Control-Allow-Origin в зависимости от источника запроса, или проверяет его в белом списке разрешенных источников.

Использование учетных данных

При отправке запросов с использованием учетных данных через кроссдоменный запрос, используйте withCredentials: true и убедитесь в том, что сервер возвращает Access-Control-Allow-Credentials: true.

Заголовок Content-Type: значимые нюансы

Обратите внимание, что использование Content-Type, отличающегося от application/x-www-form-urlencoded, multipart/form-data или text/plain, приведет к отправке предварительного запроса.

Прокси-серверы как вариант решения

Если настроить CORS прямо на сервере не получается, можно рассмотреть внедрение прокси-сервера, который пропишет требуемые заголовки CORS в ответ.

Полезные материалы

1. Cross-Origin Resource Sharing (CORS) – HTTP | MDN – подробное руководство по CORS.
2. jQuery.ajax() | jQuery API Documentation – официальная документация jQuery по AJAX.
3. Preflight request – MDN Web Docs Glossary: Definitions of Web-related terms | MDN – сведения о принципах работы предварительных запросов в CORS.
4. Access-Control-Allow-Credentials – HTTP | MDN — информация об использовании учетных данных в AJAX с CORS.
5. Access-Control-Allow-Headers – HTTP | MDN — инструкция по работе с заголовком Access-Control-Allow-Headers.
6. Fetch Standard — актуальная спецификация Fetch API.
7. XMLHttpRequest: setRequestHeader() method – Web APIs | MDN — как применять метод setRequestHeader() в XMLHttpRequest.