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

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

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

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

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

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

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

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 или значение по умолчанию для кэша в 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.

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

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

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

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