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

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

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

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

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

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

Сервис $http — это функция, которая принимает один аргумент — объект конфигурации, используемый для генерации HTTP-запроса, и возвращает обещание с двумя специфичными для $http методами: success и error.

// Simple GET request example :
$http.get('/someUrl').
  success(function(data, status, headers, config) {
    // this callback will be called asynchronously
    // when the response is available
  }).
  error(function(data, status, headers, config) {
    // called asynchronously if an error occurs
    // or server returns response with an error status.
  });

// Simple POST request example (passing data) :
$http.post('/someUrl', {msg:'hello word!'}).
  success(function(data, status, headers, config) {
    // this callback will be called asynchronously
    // when the response is available
  }).
  error(function(data, status, headers, config) {
    // called asynchronously if an error occurs
    // or server returns response with an error status.
  });

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

Код состояния ответа от 200 до 299 считается кодом состояния успеха и вызовет обратный вызов успеха. Обратите внимание, что если ответ является перенаправлением, XMLHttpRequest прозрачно выполнит его, что означает, что обратный вызов ошибки не будет вызван для таких ответов.

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

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

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

Методы сокращенного доступа

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

$http.get('/someUrl').success(successCallback);
$http.post('/someUrl', data).success(successCallback);

Полный список методов сокращенного доступа:

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

Установка 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).success(function(){...}).error(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);
  })
});

Кэширование

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

Обратите внимание, что даже если ответ предоставлен из кэша, доставка данных выполняется асинхронно, так же как и для реальных запросов.

Если существует несколько запросов GET на один и тот же URL, которые должны быть кэшированы с использованием одного и того же кэша, но кэш ещё не заполнен, будет отправлен только один запрос на сервер, а остальные запросы будут удовлетворены с помощью ответа от первого запроса.

Вы можете изменить кэш по умолчанию на новый объект (созданный с помощью $cacheFactory), обновив свойство $http.defaults.cache. Все запросы, которые устанавливают своё свойство cache в true, теперь будут использовать этот объект кэша.

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

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

Перед началом создания интерцепторов ознакомьтесь с $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

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

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

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

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

['one','two']

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

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

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

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

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

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

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