解锁 Angular HttpClient 的 Fetch 模式：withFetch 深度剖析

原创

编程小妖女

发布于 2025-06-26 10:05:07

3170

在早期的 Angular 版本中，HttpClient 默认基于 XMLHttpRequest（XHR） API 实现 HTTP 请求。XHR 在浏览器中兼容性广，但它存在冗长的回调处理、配置拦截器时的复杂度，以及在服务端渲染（SSR）环境中性能和兼容性上的局限。随着 Web 平台的发展，Fetch API 作为更现代、更简洁的 HTTP 请求方案逐渐成为主流。Angular 团队在新版中引入了 withFetch 功能，让开发者能够轻松地将 HttpClient 切换到 Fetch 实现。

借助 withFetch，开发者能够同时享受 HttpClient 对 RxJS 响应式流的封装，以及 Fetch API 的现代特性。接下来将通过严谨的逻辑推理，逐层剖析 withFetch 的作用、使用方式、底层实现差异，以及在实际项目中的最佳实践，最后给出可运行的完整示例。

探索 XHR 与 Fetch 的差异

XHR 与 Fetch 在使用体验和底层实现上有显著区别。XHR 通过回调或事件监听实现请求过程控制，支持上传进度报告，但需要实例化 XMLHttpRequest 对象、手动设置请求头与状态监听。Fetch 则基于 Promise，为 GET、POST 等请求提供统一接口，支持链式调用和 async/await，但不支持上传进度报告。

当使用 Angular 默认的 XHR 模式时，HttpClient 内部会创建 XMLHttpRequest 实例，并在它们之上封装 RxJS Observable，将 onload、onerror、onprogress 等事件映射为 Observable 的 next、error 回调。这种方式在浏览器端表现稳定，却在 SSR 或某些特殊平台（如 Web Worker）中受到限制。

引入 withFetch 后，Angular HttpClient 会改为调用全局 fetch 函数，返回的 Promise 流数据被转换为 Observable 流。这样既保留了 RxJS 操作符链的灵活性，又能够在 SSR 环境中使用全局 fetch polyfill，提高兼容性和性能。

如何在应用中启用 withFetch

在 Angular 16 及更高版本的独立应用（standalone application）中，通过 provideHttpClient API 将 withFetch 注册为 HttpClient 的特性之一。配置方式如下：

import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app/app.component';
import { provideHttpClient, withFetch } from '@angular/common/http';

bootstrapApplication(AppComponent, {
  providers: [
    provideHttpClient(
      withFetch(),        // 切换到 Fetch 实现
      // withInterceptorsFromDi(), // 若有拦截器，亦可加入
    ),
  ],
}).catch(err => console.error(err));

在基于 NgModule 的老方式中，同样能使用 provideHttpClient 来替代 HttpClientModule：

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app/app.component';
import { provideHttpClient, withFetch } from '@angular/common/http';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule],
  providers: [
    provideHttpClient(
      withFetch(),
    ),
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

紧接着在项目任意服务中注入 HttpClient，无需额外改动，即可享受 Fetch API 带来的优势。

withFetch 在内部将 HTTP 请求委派给 fetch，示例伪代码如下：

function fetchBackend(request: HttpRequest<any>): Observable<HttpEvent<any>> {
  // 根据 HttpRequest 构造 fetch init 配置
  const init: RequestInit = {
    method: request.method,
    headers: request.headers as Record<string, string>,
    body: request.body,
    credentials: 'same-origin',
    // 其它选项...
  };
  // 调用全局 fetch
  return from(fetch(request.url, init)).pipe(
    switchMap(response => {
      // 将 Fetch Response 转化为 HttpResponse
      return from(response.text()).pipe(
        map(bodyText => new HttpResponse({
          status: response.status,
          statusText: response.statusText,
          headers: parseHeaders(response.headers),
          body: parseBody(bodyText),
        }))
      );
    }),
    // 错误处理、取消等逻辑...
  );
}

由于 Fetch API 本身不支持上传进度报告，使用 withFetch 时无法再通过 HttpClient 的 observe: 'events' + reportProgress 配置获取上传进度回调。对多数读取密集型场景影响不大，但若项目需实时监控大文件上传进度，还需考虑回退到 XHR 模式。

实战演练：JSONPlaceholder 示例

在 AppComponent 中演示如何使用 HttpClient 结合 withFetch：

// app/app.component.ts

import { Component, OnInit } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { Observable } from 'rxjs';

interface Post {
  userId: number;
  id: number;
  title: string;
  body: string;
}

@Component({
  selector: 'app-root',
  template: `
    <h1>使用 withFetch 获取帖子列表</h1>
    <button (click)="loadPosts()">加载帖子</button>
    <ul>
      <li *ngFor="let post of posts$ | async">
        <strong>{{ post.title }}</strong><br />
        {{ post.body }}
      </li>
    </ul>
  `,
})
export class AppComponent implements OnInit {
  posts$!: Observable<Post[]>;

  constructor(private http: HttpClient) {}

  ngOnInit() {}

  loadPosts() {
    this.posts$ = this.http.get<Post[]>(
      'https://jsonplaceholder.typicode.com/posts'
    );
  }
}

配合前文的 provideHttpClient(withFetch())，运行应用即可在控制台或网络面板中看到基于 Fetch API 的请求，以及响应结果被正确渲染到页面。

深入对比：withFetch 与默认 XHR

由于对底层实现的替换，部分特性表现略有差异：

上传进度：XHR 支持 progress 事件，Fetch 则不支持。若业务需展示上传进度柱状图，建议继续使用默认 XHR 模式。
拦截器链：withFetch 与 XHR 模式下的 HTTP 拦截器使用方法完全一致，调用时机、错误捕获方式无差别。
SSR 兼容：在 Angular Universal 服务端渲染中，使用 Fetch 更容易 polyfill，全量支持流式渲染，推荐在 SSR 项目中开启 withFetch。
可测试性：Fetch 返回 Promise，使得测试用例中可通过 spyOn(global, fetch) 模拟返回值，对单元测试友好。

迁移建议

将现有项目迁移到 withFetch，核心步骤是将 provideHttpClient(withFetch()) 替换原有 HttpClientModule 导入。若项目体量较大，建议逐步验证各接口调用、上传模块、拦截器行为，以及在 SSR 环境下构建和渲染效果，确保无差异。

若考虑回退，也可在同一应用中混用两种模式。Angular 支持通过不同的提供者配置分别注入带与不带 Fetch 支持的 HttpClient 实例，只需在模块或组件作用域内重写 provideHttpClient 即可灵活切换。

结语

withFetch 功能让 Angular HttpClient 获得 Fetch API 的现代优势，同时保留 RxJS 驱动的响应式链式操作，兼顾开发体验与性能需求。针对不同应用场景灵活启用或回退，能够帮助团队在 SSR、跨平台或大型文件上传方面做出最佳选择。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

前端工程师