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

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

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

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

API $http основан на API `deferred/promise` $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-статуса ответа.

Код состояния ответа между 200 и 299 считается успешным и вызовет обратный вызов успеха. Обратите внимание, что если ответ является перенаправлением, 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. Если запрос не предоставляет собственных преобразований, эти будут применены.

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

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

Преобразования запросов ($httpProvider.defaults.transformRequest и $http.defaults.transformRequest):

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

Преобразования ответов ($httpProvider.defaults.transformResponse и $http.defaults.transformResponse):

• Если обнаружен префикс XSRF, он будет удалён (см. раздел "Учёт мер безопасности" ниже).
• Если обнаружен 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 или значение по умолчанию 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 и deferred/promise API.

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

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

Существует два вида перехватывателей (и два вида перехватывателей отклонений):

• request: обработчики вызываются с объектом http-конфигурации. Функция свободна изменять объект 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

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

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

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

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

['one','two']

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

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

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

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

XSRF — это техника атаки, с помощью которой злоумышленник может обмануть аутентифицированного пользователя и незаметно выполнить действия на вашем сайте. Angular предоставляет механизм для защиты от 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 во время выполнения, или в объекте конфигурации для каждого запроса.

Для предотвращения коллизий в средах, где несколько приложений Angular используют один и тот же домен или поддомен, мы рекомендуем каждому применению использовать уникальное имя cookie.