Улучшить документацию Просмотреть исходный код $http

Обзор

Сервис $http является основным сервисом AngularJS, который облегчает взаимодействие с удалёнными HTTP-серверами через браузерный объект XMLHttpRequest или через JSONP.

Для тестирования приложений, использующих сервис $http, см. $httpBackend mock.

Для более высокого уровня абстракции, ознакомьтесь с сервисом $resource.

API $http основан на API отложенных задач/обещаний, предоставляемых сервисом $q. Хотя для простых сценариев использования это не столь важно, для продвинутых сценариев необходимо ознакомиться с этими API и предоставляемыми ими гарантиями.

Общее использование

Сервис $http представляет собой функцию, которая принимает один аргумент — объект конфигурации объект конфигурации — для генерации HTTP-запроса и возвращает promise.

// Simple GET request example:
$http({
  method: 'GET',
  url: '/someUrl'
}).then(function successCallback(response) {
    // this callback will be called asynchronously
    // when the response is available
  }, function errorCallback(response) {
    // called asynchronously if an error occurs
    // or server returns response with an error status.
  });

Объект ответа имеет следующие свойства:

• data – {string|Object} – Тело ответа, преобразованное с помощью функций трансформации.
• status – {number} – Код HTTP-статуса ответа.
• headers – {function([headerName])} – Функция получения заголовков.
• config – {Object} – Объект конфигурации, который использовался для генерации запроса.
• statusText – {string} – Текст HTTP-статуса ответа.
• xhrStatus – {string} – Статус XMLHttpRequest (complete, error, timeout или abort).

Код статуса ответа в диапазоне от 200 до 299 считается успешным статусом, и вызов success callback. Любой код статуса ответа вне этого диапазона считается статусом ошибки и вызовет вызов error callback. Также коды статусов меньше -1 нормализуются до нуля. -1 обычно означает, что запрос был прерван, например, с помощью config.timeout. Обратите внимание, что если ответ является переадресацией, XMLHttpRequest прозрачно следует за ней, что означает, что результат (успех или ошибка) будет определяться конечным кодом статуса ответа.

Методы-ярлыки

Также доступны методы-ярлыки. Все методы-ярлыки требуют передачи URL, а данные запроса должны быть переданы для запросов POST/PUT. В качестве последнего аргумента можно передать необязательную конфигурацию.

$http.get('/someUrl', config).then(successCallback, errorCallback);
$http.post('/someUrl', data, config).then(successCallback, errorCallback);

Полный список методов-ярлыков:

• $http.get
• $http.head
• $http.post
• $http.put
• $http.delete
• $http.jsonp
• $http.patch

Написание тестов модулей, использующих $http

При тестировании модулей (с использованием ngMock) необходимо вызвать $httpBackend.flush() для обработки каждого ожидающего запроса с помощью обученных ответов.

$httpBackend.expectGET(...);
$http.get(...);
$httpBackend.flush();

Установка HTTP-заголовков

Сервис $http автоматически добавит определённые HTTP-заголовки ко всем запросам. Эти значения по умолчанию можно полностью настроить, обратившись к объекту конфигурации $httpProvider.defaults.headers, который в настоящее время содержит эту конфигурацию по умолчанию:

• $httpProvider.defaults.headers.common (заголовки, общие для всех запросов):
  • Accept: application/json, text/plain, */*
• $httpProvider.defaults.headers.post: (значения заголовков по умолчанию для запросов POST)
  • Content-Type: application/json
• $httpProvider.defaults.headers.put (значения заголовков по умолчанию для запросов PUT)
  • Content-Type: application/json

Чтобы добавить или перезаписать эти значения по умолчанию, просто добавьте или удалите свойство из этих объектов конфигурации. Чтобы добавить заголовки для HTTP-метода, отличного от POST или PUT, просто добавьте новый объект с именем HTTP-метода в нижнем регистре в качестве ключа, например, $httpProvider.defaults.headers.get = { 'My-Header' : 'value' }.

Значения по умолчанию также могут быть установлены во время выполнения через объект $http.defaults таким же образом. Например:

module.run(function($http) {
  $http.defaults.headers.common.Authorization = 'Basic YmVlcDpib29w';
});

Кроме того, вы можете указать свойство headers в объекте конфигурации, переданном при вызове $http(config), что переопределяет значения по умолчанию без глобальных изменений.

Чтобы явно удалить заголовок, автоматически добавленный через $httpProvider.defaults.headers в каждом запросе, используйте свойство headers, установив желаемый заголовок в значение undefined. Например:

var req = {
 method: 'POST',
 url: 'http://example.com',
 headers: {
   'Content-Type': undefined
 },
 data: { test: 'test' }
}

$http(req).then(function(){...}, function(){...});

Преобразование запросов и ответов

И запросы, и ответы могут быть преобразованы с помощью функций преобразования: transformRequest и transformResponse. Эти свойства могут быть одной функцией, которая возвращает преобразованное значение (function(data, headersGetter, status)) или массивом таких функций преобразования, что позволяет вам push или unshift новую функцию преобразования в цепочку преобразований.

Преобразования по умолчанию

Провайдер $httpProvider и сервис $http экспонируют свойства defaults.transformRequest и defaults.transformResponse. Если запрос не предоставляет собственных преобразований, то применяются эти значения.

Вы можете расширить или заменить преобразования по умолчанию, изменив эти свойства, добавив или заменив массив.

AngularJS предоставляет следующие преобразования по умолчанию:

Преобразования запросов ($httpProvider.defaults.transformRequest и $http.defaults.transformRequest) — это массив с одной функцией, которая выполняет следующее:

• Если свойство data объекта конфигурации запроса содержит объект, сериализуйте его в формате JSON.

Преобразования ответов ($httpProvider.defaults.transformResponse и $http.defaults.transformResponse) — это массив с одной функцией, которая выполняет следующее:

• Если обнаружен префикс XSRF, удалите его (см. раздел «Соображения безопасности» ниже).
• Если Content-Type равно application/json или ответ похож на JSON, десериализуйте его с помощью парсера JSON.

Переопределение преобразований по умолчанию на уровне запроса

Если вы хотите переопределить преобразования запросов/ответов только для одного запроса, укажите свойства transformRequest и/или transformResponse в объекте конфигурации, переданном в $http.

Обратите внимание, что если вы указываете эти свойства в объекте конфигурации, преобразования по умолчанию будут переопределены. Если вы хотите расширить преобразования по умолчанию, вы должны включить их в свой локальный массив преобразований.

Следующий код демонстрирует добавление нового преобразования ответа, которое будет выполняться после выполнения преобразований ответа по умолчанию.

function appendTransform(defaults, transform) {

  // We can't guarantee that the default transformation is an array
  defaults = angular.isArray(defaults) ? defaults : [defaults];

  // Append the new transformation to the defaults
  return defaults.concat(transform);
}

$http({
  url: '...',
  method: 'GET',
  transformResponse: appendTransform($http.defaults.transformResponse, function(value) {
    return doTransform(value);
  })
});

Кэширование

$http ответы по умолчанию не кэшируются. Чтобы включить кэширование, необходимо установить значение config.cache или значения кэша по умолчанию в TRUE или в объект кэша (созданный с помощью $cacheFactory). Если определено, значение config.cache имеет приоритет над значением кэша по умолчанию.

Для:

• кэширования всех ответов — установите значение кэша по умолчанию в TRUE или в объект кэша
• кэширования конкретного ответа — установите значение config.cache в TRUE или в объект кэша

Если кэширование включено, но ни кэш по умолчанию, ни config.cache не заданы как объект кэша, используется объект кэша по умолчанию $cacheFactory("$http").

Значение кэша по умолчанию можно установить, обновив свойство $http.defaults.cache или свойство $httpProvider.defaults.cache.

При включенном кэшировании $http сохраняет ответ от сервера, используя соответствующий объект кэша. При следующем запросе на тот же ресурс ответ возвращается из кэша без отправки запроса на сервер.

Обратите внимание:

• Кэшируются только запросы GET и JSONP.
• Ключ кэша — URL запроса, включая параметры поиска; заголовки не учитываются.
• Кэшированные ответы возвращаются асинхронно, так же как и ответы от сервера.
• Если несколько идентичных запросов отправляются с использованием одного кэша, который ещё не заполнен, один запрос будет отправлен на сервер, а остальные запросы вернут тот же ответ.
• Заголовок cache-control в ответе не влияет на кэширование ответов.

Интерцепторы

Перед созданием интерцепторов убедитесь, что вы понимаете $q и API отложенных задач/обещаний.

Для целей глобальной обработки ошибок, аутентификации или любого вида синхронной или асинхронной предобработки запроса или последующей обработки ответов желательно иметь возможность перехватывать запросы до передачи их на сервер и ответы перед передачей их коду приложения, который инициировал эти запросы. Интерцепторы используют API обещаний обещаний для удовлетворения этой потребности как при синхронной, так и при асинхронной предобработке.

Интерцепторы — это фабрики сервисов, которые регистрируются в $httpProvider путем добавления их в массив $httpProvider.interceptors. Фабрика вызывается и инжектируется с зависимостями (если указаны) и возвращает интерцептор.

Существует два типа интерцепторов (и два типа интерцепторов отмены):

• request: перехватывающие модули вызываются с объектом http config. Функция свободна изменять объект config или создать новый. Функция должна вернуть объект config напрямую или промис, содержащий объект config или новый объект config.
• requestError: перехватывающий модуль вызывается, когда предыдущий перехватывающий модуль бросил ошибку или разрешился с отклонением.
• response: перехватывающие модули вызываются с объектом http response. Функция свободна изменять объект response или создать новый. Функция должна вернуть объект response напрямую или в виде промиса, содержащего объект response или новый объект response.
• responseError: перехватывающий модуль вызывается, когда предыдущий перехватывающий модуль бросил ошибку или разрешился с отклонением.

// register the interceptor as a service
$provide.factory('myHttpInterceptor', function($q, dependency1, dependency2) {
  return {
    // optional method
    'request': function(config) {
      // do something on success
      return config;
    },

    // optional method
   'requestError': function(rejection) {
      // do something on error
      if (canRecover(rejection)) {
        return responseOrNewPromise
      }
      return $q.reject(rejection);
    },



    // optional method
    'response': function(response) {
      // do something on success
      return response;
    },

    // optional method
   'responseError': function(rejection) {
      // do something on error
      if (canRecover(rejection)) {
        return responseOrNewPromise
      }
      return $q.reject(rejection);
    }
  };
});

$httpProvider.interceptors.push('myHttpInterceptor');


// alternatively, register the interceptor via an anonymous factory
$httpProvider.interceptors.push(function($q, dependency1, dependency2) {
  return {
   'request': function(config) {
       // same as above
    },

    'response': function(response) {
       // same as above
    }
  };
});

Безопасность

При разработке веб-приложений учитывайте угрозы безопасности, исходящие от:

• Уязвимости JSON
• XSRF

Для устранения этих угроз необходимо взаимодействие как сервера, так и клиента. AngularJS поставляется с предварительно настроенными стратегиями, которые решают эти проблемы, но для их работы требуется взаимодействие с сервером бэкэнда.

Защита от уязвимости JSON

Уязвимость JSON позволяет сторонним веб-сайтам преобразовывать URL вашего JSON-ресурса в JSONP-запрос при определенных условиях. Для предотвращения этого ваш сервер может добавлять к всем JSON-запросам следующую строку ")]}',\n". AngularJS автоматически удалит префикс перед обработкой запроса как JSON.

Например, если ваш сервер должен вернуть:

['one','two']

что уязвимо к атакам, ваш сервер может вернуть:

)]}',
['one','two']

AngularJS удалит префикс перед обработкой JSON.

Защита от межсайтовых поддельных запросов (XSRF)

XSRF — это техника атаки, при которой злоумышленник может обмануть авторизованного пользователя, чтобы он неосознанно выполнил действия на вашем веб-сайте. AngularJS предоставляет механизм для противодействия XSRF. При выполнении XHR-запросов служба $http считывает маркер из cookie (по умолчанию XSRF-TOKEN) и устанавливает его как HTTP-заголовок (X-XSRF-TOKEN). Поскольку только JavaScript, выполняемый на вашем домене, может прочитать cookie, ваш сервер может быть уверен, что XHR-запрос был отправлен JavaScript, работающим на вашем домене. Заголовок не будет установлен для запросов между разными доменными именами.

Чтобы воспользоваться этим, ваш сервер должен установить маркер в cookie сессии JavaScript с именем XSRF-TOKEN при первом запросе HTTP GET. При последующих XHR-запросах сервер может проверить, соответствует ли cookie HTTP-заголовку X-XSRF-TOKEN, и, следовательно, быть уверенным, что запрос мог отправить только JavaScript, работающий на вашем домене. Маркер должен быть уникальным для каждого пользователя и должен быть проверяем сервером (чтобы предотвратить создание JavaScript собственных маркеров). Рекомендуется использовать дайджест cookie аутентификации вашего сайта с солью для дополнительной безопасности.

Имя заголовков можно указать, используя свойства xsrfHeaderName и xsrfCookieName либо в $httpProvider.defaults во время конфигурации, либо в $http.defaults во время выполнения, либо в конфигурации каждого запроса.

Чтобы предотвратить столкновения в средах, где несколько приложений AngularJS используют один и тот же домен или поддомен, рекомендуется, чтобы каждое приложение использовало уникальное имя cookie.