---

前言

这篇文章主要介绍了 @ngify/http 这一响应式 HTTP 客户端，包括其与 axios 的关联、功能特点、基本用法（如获取不同类型数据、设置参数和标头等）、拦截器的使用、更换请求实现、防护机制、全局配置及测试请求等，还对比了它与其他库的差异，强调了其稳定性和便捷性。

---

一、什么是ngify？

在前端开发中，使用最广泛的 HTTP 客户端为 axios，它是一个用于浏览器和 Node.js 的、基于 Promise 的 HTTP 客户端。
axios 的前身其实是 AngularJS 的 $http 服务。axios 深受 AngularJS 中提供的 $http 服务的启发，将 $http 服务从 AngularJS 中剥离，提供一个独立的服务，以便在 AngularJS 之外使用。

注：AngularJS 特指 AngularJS v1，而非 Angular 2+。

Angular2+ 抛弃了原有的 $http 服务，转而与 RxJS 深度集成，打造了一个更加先进、现代化的响应式 HTTP 客户端。这个新的客户端充分利用了 RxJS 的强大功能，提供了更灵活、更易于理解的异步操作方式。然而，由于其与 Angular 的依赖注入和 SSR 功能紧密耦合，使得它无法直接应用于 Angular 生态之外。

@ngify/http 是一个基于 RxJS 的响应式 HTTP 客户端，提供了与 Angular HttpClient 高度一致的 API，主要包含以下功能：

• 请求类型化响应对象的能力。
• 简化的错误处理。
• 请求和响应的拦截机制。
• 轻松处理请求超时、重试、并发、缓存等等。
• 支持多种平台：Web、Node.js、微信小程序、uni-app、taro 等等。

@ngify/http 的目标与 axios 一致：提供一个独立的 HTTP 服务，以便在 Angular2+ 之外使用。

💯无需担心 @ngify/http 的稳定性，@ngify/http 采用了与 Angular HttpClient 相同的严格单元测试，确保了其代码质量和可靠性，在各种场景下保持足够的稳定性。

二、npm安装

npm install @ngify/http

三、发起请求

HttpClient 具有与用于发出请求的不同 HTTP 动词相对应的方法，这些方法既可以加载数据，也可以在服务器上应用变更。每个方法都返回一个 RxJS Observable，订阅后会发送请求，然后在服务器响应时发出结果。

由 HttpClient 创建的 Observable 可以被订阅任意多次，并且每次订阅都会发出一个新的后端请求。

通过传递给请求方法的选项对象，可以调整请求的各种属性和返回的响应类型。

3.1 获取 JSON 数据

从后端获取数据通常需要使用 HttpClient.get() 方法发出 GET 请求。此方法采用两个参数：要从中获取的字符串端点 URL，以及用于配置请求的可选选项对象。

例如，要使用 HttpClient.get() 方法从假设的 API 获取配置数据：

http.get<Config>('/api/config').subscribe(config => {
  // process the configuration.
});

请注意泛型类型参数，它指定服务器返回的数据的类型为 Config 。该参数是可选的，如果省略它，则返回的数据将具有 any 类型。

🎯 注意： 如果数据具有未知形状的类型，那么更安全的方法是使用 unknown 作为响应类型。

请求方法的通用类型是关于服务器返回的数据的类型断言。 HttpClient 不会验证实际返回数据是否与该类型匹配。

3.2 获取其他类型的数据

默认情况下， HttpClient 假定服务器将返回 JSON 数据。与非 JSON API 交互时，您可以告诉 HttpClient 在发出请求时期望并返回什么响应类型。这是通过 responseType 选项完成的。

Response type	Returned response type
‘json’ (默认)	给定泛型类型的 JSON 数据
‘text’	字符串文本
‘blob’	Blob 实例
‘arraybuffer’	包含原始响应字节的 ArrayBuffer

例如，您可以要求 HttpClient 将 .jpeg 图像的原始字节下载到 ArrayBuffer 中：

http.get('/images/dog.jpg', { responseType: 'arraybuffer' }).subscribe(buffer => {
  console.log('The image is ' + buffer.byteLength + ' bytes large');
});

3.3 改变服务器状态

执行修改的服务器 API 通常需要发出 POST 请求，并在请求正文中指定新状态或要进行的更改。

HttpClient.post() 方法的行为与 get() 类似，只是第二位参数变为 body 参数：

http.post<Config>('/api/config', newConfig).subscribe(config => {
  console.log('Updated config:', config);
});

可以提供许多不同类型的值作为请求的 body，并且 HttpClient 将相应地序列化它们：

Body	typeSerialization as
string	纯文本
number、boolean、Array 或 object	JSON 字符串
ArrayBuffer	来自 buffer 的原始数据
Blob	具有 Blob 内容类型的原始数据
FormData	multipart/form-data 表单数据
HttpParams 或 URLSearchParams	application/x-www-form-urlencoded 格式化字符串

3.4 设置 URL 参数

使用 params 选项指定应包含在请求 URL 中的请求参数。

传递字面量对象是配置 URL 参数的最简单方法：

http.get('/api/config', {
  params: { filter: 'all' },
}).subscribe(config => {
  // ...
});

http.post('/api/config', body, {
  params: { filter: 'all' },
}).subscribe(config => {
  // ...
});

或者，如果您需要对参数的构造或序列化进行更多控制，则可以传递 HttpParams 的实例。

🎯注意： HttpParams 的实例是不可变的，不能直接更改。相反，诸如 append() 之类的可变方法会返回应用了变更的 HttpParams 的新实例。

const baseParams = new HttpParams().set('filter', 'all');

http.get('/api/config', {
  params: baseParams.set('details', 'enabled')
}).subscribe(config => {
  // ...
});

http.post('/api/config', body, {
  params: baseParams.set('details', 'enabled')
}).subscribe(config => {
  // ...
});

您可以使用自定义 HttpParameterCodec 实例化 HttpParams（构造方法中的第二个参数），该自定义 HttpParameterCodec确定HttpClient` 如何将参数编码到 URL 中。

3.5 设置请求标头

使用 headers 选项指定应包含在请求中的请求标头。

传递字面量对象是配置请求标头的最简单方法：

http.get('/api/config', {
  headers: {
    'X-Debug-Level': 'verbose',
  }
}).subscribe(config => {
  // ...
});

或者，如果您需要对标头的构造进行更多控制，请传递 HttpHeaders 的实例。

🎯注意： HttpHeaders 的实例是不可变的，不能直接更改。相反，诸如 append() 之类的可变方法会返回应用了变更的 HttpHeaders 的新实例。

const baseHeaders = new HttpHeaders().set('X-Debug-Level', 'minimal');

http.get<Config>('/api/config', {
  headers: baseHeaders.set('X-Debug-Level', 'verbose'),
}).subscribe(config => {
  // ...
});

3.6 与服务器响应事件交互

为了方便起见，HttpClient 默认返回服务器返回的数据的 Observable（body）。有时需要检查实际响应，例如检索特定的响应标头。

要访问整个响应，请将 observe 选项设置为 'response'：

http.get<Config>('/api/config', { observe: 'response' }).subscribe(res => {
  console.log('Response status:', res.status);
  console.log('Body:', res.body);
});

3.7 接收原始进度事件

除了响应正文或响应对象之外，HttpClient 还可以返回与请求生命周期中的特定时刻相对应的原始事件流。这些事件包括何时发送请求、何时返回响应标头以及何时完成正文。这些事件还可以包括报告大型请求或响应正文的上传和下载状态的进度事件。

默认情况下，进度事件处于禁用状态（因为它们会产生性能成本），但可以使用 reportProgress 选项来启用。

🎯注意：HttpClient 的 fetch 实现不支持报告上传进度事件。

要观察事件流，请将 observe 选项设置为 'events'：

http.post('/api/upload', myData, {
  reportProgress: true,
  observe: 'events',
}).subscribe(event => {
  switch (event.type) {
    case HttpEventType.UploadProgress:
      console.log('Uploaded ' + event.loaded + ' out of ' + event.total + ' bytes');
      break;
    case HttpEventType.Response:
      console.log('Finished uploading!');
      break;
  }
});

事件流中报告的每个 HttpEvent 都有一个 type 来区分事件所代表的内容：

3.8 处理请求失败

HTTP 请求失败有两种情况：

• 网络或连接错误可能会阻止请求到达后端服务器。
• 后端可以收到请求但无法处理，并返回错误响应。

HttpClient 在 HttpErrorResponse 中捕获这两种错误，并通过 Observable 的错误通道返回该错误。网络错误的 status 代码为 0，error 是 ProgressEvent 的实例。
后端错误具有后端返回的失败 status 代码，以及错误响应 error。检查响应以确定错误的原因以及处理错误的适当操作。

RxJS 提供了多个可用于错误处理的运算符。

您可以使用 catchError 运算符将错误响应转换为 UI 的值。该值可以告诉 UI 显示错误页面或值，并在必要时捕获错误原因。

有时，诸如网络中断之类的暂时性错误可能会导致请求意外失败，只需重试请求即可使其成功。RxJS 提供了几个重试运算符，它们在某些条件下自动重新订阅失败的 Observable。例如，retry() 运算符将自动尝试重新订阅指定的次数。

3.9 Http Observables

HttpClient 上的每个请求方法都会构造并返回所请求响应类型的 Observable。使用 HttpClient 时，了解这些 Observable 的工作原理非常重要。
HttpClient 生成 RxJS 所谓的 “冷” Observable，这意味着在订阅 Observable之前不会发生任何实际请求。只有这样，请求才真正发送到服务器。多次订阅同一个 Observable会触发多个后端请求。每个订阅都是独立的。
一旦响应返回，来自 HttpClient 的 Observable通常会自动完成（尽管拦截器会影响这一点）。
由于自动完成，如果不清理 HttpClient订阅，通常不存在内存泄漏的风险。

四、更换 HTTP 请求实现

@ngify/http 内置了以下 HTTP 请求实现：

HTTP请求实现	包	描述
withXhr	@ngify/http	使用 XMLHttpRequest 进行 HTTP 请求
withFetch	@ngify/http	使用 Fetch API 进行 HTTP 请求
withWx	@ngify/http-wx	在 微信小程序 中进行 HTTP 请求
withTaro	@ngify/http-taro	在 Taro 中进行 HTTP 请求
withUni	@ngify/http-uni	在 Uni-app 中进行 HTTP 请求

HttpClient 默认使用 withXhr，您可以自行切换到其他实现：

import { withXhr, withFetch } from '@ngify/http';
import { withWx } from '@ngify/http-wx';

const xhrHttp = new HttpClient(
  withXhr()
);
const fetchHttp = new HttpClient(
  withFetch()
);
const wxHttp = new HttpClient(
  withWx()
);

你还可使用自定义的 HttpBackend 实现：

// 需要实现 HttpBackend 接口
class CustomHttpBackend implements HttpBackend {
  handle(request: HttpRequest<any>): Observable<HttpEvent<any>> {
    // ...
  }
}

const customHttp = new HttpClient(
  {
    kind: HttpFeatureKind.Backend,
    value: new CustomHttpBackend()
  }
);

五、XSRF/CSRF 防护

HttpClient 支持用于防止 XSRF 攻击的通用机制。执行 HTTP 请求时，拦截器从 cookie 中读取令牌（默认为 XSRF-TOKEN），并将其设置为 HTTP 标头（默认为 X-XSRF-TOKEN）。
由于只有在您的域上运行的代码才能读取 cookie，因此后端可以确定 HTTP 请求来自您的客户端应用程序而不是攻击者。

要启用 XSRF 防护，请在 HttpClient 实例化时或在 setupHttpClient 中传递 withXsrfProtection()：

const http = new HttpClient(
  withXsrfProtection()
);

如果您的后端服务对 XSRF 令牌 cookie 或标头使用不同的名称，请自定义 cookie 名称与标头名称：

withXsrfProtection({
  cookieName: 'CUSTOM_XSRF_TOKEN',
  headerName: 'X-Custom-Xsrf-Header',
});

默认情况下，拦截器会在除 GET/HEAD 外的所有请求（例如 POST）上将此标头发送到相对 URL，但不会在具有绝对 URL 的请求上发送此标头。

为什么不保护 GET 请求？

仅对于可以更改后端状态的请求才需要 CSRF 保护。就其本质而言，CSRF 攻击跨越域边界，并且 Web 的同源策略将阻止攻击页面检索经过身份验证的 GET 请求的结果。

为了利用这一点，您的服务器需要在页面加载或第一个 GET 请求时在名为 XSRF-TOKEN 的 cookie 中设置一个令牌。
在后续请求中，服务器可以验证 cookie 是否与 X-XSRF-TOKEN HTTP 标头匹配，因此确保只有在您的域上运行的代码才能发送请求。
令牌对于每个用户必须是唯一的，并且必须可由服务器验证；这可以防止客户端创建自己的令牌。

HttpClient 仅支持 XSRF 保护方案的客户端部分

您的后端服务必须配置为为您的页面设置 cookie，并验证标头是否存在于所有符合条件的请求中。如果不这样做，HttpClient 的 XSRF 保护就会失效。

六、全局配置

您可以使用 setupHttpClient 函数进行全局配置：

setupHttpClient(
  withFetch(),
  withXsrfProtection(),
);

七、基本用法

待续

八、拦截请求和响应

请移步：ngify 拦截请求和响应

九、测试请求

参考 angular.dev/guide/http/…

十、支持

对 @ngify/http 感兴趣？为该项目点星⭐！@ngify/http

---