angular-http

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

@angular/common/http

Version: Angular 21 (2025) Tags: HTTP, REST, API, Interceptors

References: HttpClient • API • Interceptors

版本： Angular 21（2025年） 标签： HTTP, REST, API, 拦截器

参考资料： HttpClient • API • 拦截器

API Changes

API变更

This section documents recent version-specific API changes.

NEW: Functional interceptors — Use
```
provideHttpClient(withInterceptors([...]))
```
for modern interceptor setup source
NEW:
```
withFetch
```
— Use native fetch API with HttpClient source
NEW:
```
withInterceptorsFromDi
```
— Legacy interceptor support with functional approach
NEW: HttpContext tokens — Per-request metadata using HttpContextToken
NEW:
```
AbortSignal
```
support — Request cancellation with timeout support
DEPRECATED: Class-based HttpInterceptor — Migrate to functional interceptors

本节记录了近期版本对应的API变动：

新增：函数式拦截器 —— 使用
```
provideHttpClient(withInterceptors([...]))
```
实现现代化的拦截器配置来源
新增：
```
withFetch
```
—— 让HttpClient使用原生fetch API 来源
新增：
```
withInterceptorsFromDi
```
—— 以函数式方案支持旧版拦截器
新增：HttpContext令牌 —— 通过HttpContextToken为单个请求添加元数据
新增：
```
AbortSignal
```
支持 —— 支持基于超时的请求取消
已废弃：基于类的HttpInterceptor —— 请迁移至函数式拦截器

Best Practices

最佳实践

Use functional interceptors

// ✅ Modern functional interceptor
export const authInterceptor: HttpInterceptorFn = (req, next) => {
  const authService = inject(AuthService);
  const token = authService.getToken();
  
  if (token) {
    const authReq = req.clone({
      setHeaders: { Authorization: `Bearer ${token}` }
    });
    return next(authReq);
  }
  return next(req);
};

// Register
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(withInterceptors([authInterceptor]))
  ]
};

Use interceptors for cross-cutting concerns — Authentication, logging, error handling

// Error interceptor with retry
export const errorInterceptor: HttpInterceptorFn = (req, next) => {
  return next(req).pipe(
    catchError((error: HttpErrorResponse) => {
      if (error.status === 401) {
        inject(Router).navigate(['/login']);
      }
      return throwError(() => error);
    })
  );
};

Use retry with backoff for flaky networks

import { retry, delay, catchError } from 'rxjs/operators';

http.get('/api/data').pipe(
  retry({ count: 3, delay: 1000 })
);

Use HttpContext for per-request flags

const cacheToken = new HttpContextToken<boolean>(() => false);

export const cacheInterceptor: HttpInterceptorFn = (req, next) => {
  if (req.context.get(cacheToken)) {
    // Check cache
  }
  return next(req);
};

// Usage
http.get('/api/data', {
  context: new HttpContext().set(cacheToken, true)
});

Use proper typing for HTTP responses

interface User {
  id: number;
  name: string;
}

http.get<User>('/api/user/1').subscribe(user => {
  console.log(user.name); // TypeScript knows the type
});

Use
```
observe: 'response'
```
for full HTTP response

http.get('/api/data', { observe: 'response' }).subscribe(response => {
  console.log(response.headers);
  console.log(response.body);
});

Handle errors globally

@Injectable()
export class GlobalErrorHandler implements ErrorHandler {
  handleError(error: Error) {
    // Log to error tracking service
    console.error(error);
  }
}

// Register
provideErrorHandler(GlobalErrorHandler)

Use
```
withCredentials
```
for CORS requests

http.get('/api/data', { withCredentials: true });

使用函数式拦截器

// ✅ Modern functional interceptor
export const authInterceptor: HttpInterceptorFn = (req, next) => {
  const authService = inject(AuthService);
  const token = authService.getToken();
  
  if (token) {
    const authReq = req.clone({
      setHeaders: { Authorization: `Bearer ${token}` }
    });
    return next(authReq);
  }
  return next(req);
};

// Register
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(withInterceptors([authInterceptor]))
  ]
};

将拦截器用于横切关注点 —— 身份验证、日志记录、错误处理

// Error interceptor with retry
export const errorInterceptor: HttpInterceptorFn = (req, next) => {
  return next(req).pipe(
    catchError((error: HttpErrorResponse) => {
      if (error.status === 401) {
        inject(Router).navigate(['/login']);
      }
      return throwError(() => error);
    })
  );
};

针对不稳定网络使用带退避策略的重试机制

import { retry, delay, catchError } from 'rxjs/operators';

http.get('/api/data').pipe(
  retry({ count: 3, delay: 1000 })
);

使用HttpContext为单个请求设置标识

const cacheToken = new HttpContextToken<boolean>(() => false);

export const cacheInterceptor: HttpInterceptorFn = (req, next) => {
  if (req.context.get(cacheToken)) {
    // Check cache
  }
  return next(req);
};

// Usage
http.get('/api/data', {
  context: new HttpContext().set(cacheToken, true)
});

为HTTP响应添加合适的类型定义

interface User {
  id: number;
  name: string;
}

http.get<User>('/api/user/1').subscribe(user => {
  console.log(user.name); // TypeScript knows the type
});

使用
```
observe: 'response'
```
获取完整HTTP响应

http.get('/api/data', { observe: 'response' }).subscribe(response => {
  console.log(response.headers);
  console.log(response.body);
});

全局处理错误

@Injectable()
export class GlobalErrorHandler implements ErrorHandler {
  handleError(error: Error) {
    // Log to error tracking service
    console.error(error);
  }
}

// Register
provideErrorHandler(GlobalErrorHandler)

CORS请求使用
```
withCredentials
```

http.get('/api/data', { withCredentials: true });