NestJS Enterprise Backend APIs · 课时

使用拦截器实现超时、重试与舱壁隔离

实现基于 RxJS 的超时和重试拦截器，并为出站调用设置并发舱壁。

使用拦截器实现超时、重试与舱壁隔离 是 CoddyKit 上的免费 NestJS Enterprise Backend APIs 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 NestJS Enterprise Backend APIs 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 NestJS Enterprise Backend APIs 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Why Resilience Patterns Belong in Interceptors

Outbound calls to other services fail in three classic ways: they hang forever, they fail transiently, or they flood a slow dependency until it (and you) collapse. The three matching defenses are timeouts, retries, and bulkheads.

Timeout — cap how long any one call may run.
Retry — re-attempt a failed call a bounded number of times, ideally only for transient errors.
Bulkhead — cap how many calls run concurrently so one dependency can't exhaust your resources.

In NestJS these compose cleanly as NestInterceptors. An interceptor wraps the handler's RxJS stream, so we can layer timeout and retry operators on the response Observable without touching business logic.

The Interceptor Contract

A NestJS interceptor implements intercept(context, next) and returns an Observable. Calling next.handle() runs the route handler and gives you its result stream. Anything you pipe onto that stream — timeout, retry, catchError — applies to the response.

This is why resilience logic lives here: it is cross-cutting and stream-based.
Operators run in order, so placement of timeout vs retry changes behavior — we will exploit that.

import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
import { Observable } from 'rxjs';
import { tap } from 'rxjs/operators';

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    const started = Date.now();
    // next.handle() executes the route handler; we pipe onto its stream.
    return next.handle().pipe(
      tap(() => console.log(`took ${Date.now() - started}ms`)),
    );
  }
}

A Timeout Interceptor

The RxJS timeout operator emits a TimeoutError if the source does not emit within the given window. We catch that error and convert it into a proper HTTP response — 504 Gateway Timeout — instead of leaking an RxJS error class.

Always translate TimeoutError into a meaningful status; an unhandled one becomes a generic 500.
Re-throw anything that is not a timeout so other filters can handle it.

import { CallHandler, ExecutionContext, Injectable, NestInterceptor, RequestTimeoutException } from '@nestjs/common';
import { Observable, TimeoutError, throwError } from 'rxjs';
import { catchError, timeout } from 'rxjs/operators';

@Injectable()
export class TimeoutInterceptor implements NestInterceptor {
  constructor(private readonly ms = 5000) {}

  intercept(_ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    return next.handle().pipe(
      timeout(this.ms),
      catchError((err) =>
        err instanceof TimeoutError
          ? throwError(() => new RequestTimeoutException('Upstream call timed out'))
          : throwError(() => err),
      ),
    );
  }
}

Making the Timeout Configurable Per Route

A flat 5s timeout rarely fits every endpoint. Expose the value via metadata so each handler can override it. Read it with Reflector, falling back to a default.

Define a @Timeout(ms) decorator using SetMetadata.
The interceptor pulls the value off the handler with reflector.get.

This keeps the policy declarative: the route says how patient it is.

import { SetMetadata, applyDecorators } from '@nestjs/common';

export const TIMEOUT_MS = 'timeout_ms';
export const Timeout = (ms: number) => applyDecorators(SetMetadata(TIMEOUT_MS, ms));

// In the interceptor:
// const ms = this.reflector.get<number>(TIMEOUT_MS, ctx.getHandler()) ?? 5000;
// return next.handle().pipe(timeout(ms), /* catchError ... */);

Retrying Transient Failures

RxJS retry resubscribes to the source when it errors. Naive retry(3) hammers a struggling dependency. Use retry({ count, delay }) where delay is a function returning an Observable — this lets us add exponential backoff with jitter and filter which errors are retryable.

Retry only idempotent operations (GET, PUT, DELETE) — never blind-retry a POST that may have already succeeded.
Retry only transient errors: timeouts, 502/503/504, connection resets — not a 400 or 422.

import { Observable, throwError, timer } from 'rxjs';
import { retry } from 'rxjs/operators';

const RETRYABLE = new Set([502, 503, 504]);

function withRetry<T>(source: Observable<T>): Observable<T> {
  return source.pipe(
    retry({
      count: 3,
      delay: (err, attempt) => {
        const status = err?.response?.status;
        if (status && !RETRYABLE.has(status)) return throwError(() => err);
        const base = 100 * 2 ** (attempt - 1); // 100, 200, 400 ms
        const jitter = Math.random() * base;
        return timer(base + jitter);
      },
    }),
  );
}

Backoff Math, Standalone

Before wiring backoff into an interceptor, it helps to see the delays. Full jitter picks a random delay in [0, base] to spread retries and avoid the thundering herd where every client retries at the same instant.

This snippet just prints the schedule — pure TypeScript, no framework.

function backoffSchedule(maxAttempts: number, baseMs: number): number[] {
  const delays: number[] = [];
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const cap = baseMs * 2 ** (attempt - 1);
    const fullJitter = Math.floor(Math.random() * cap); // [0, cap)
    delays.push(fullJitter);
  }
  return delays;
}

const schedule = backoffSchedule(5, 100);
console.log('Caps:   ', [100, 200, 400, 800, 1600].join(', '));
console.log('Jittered:', schedule.join(', '));
console.log('Total wait:', schedule.reduce((a, b) => a + b, 0), 'ms');

Ordering: Timeout Inside, Retry Outside

Operator order is the subtle part. Put timeout before retry in the pipe so each attempt gets its own deadline; retry then resubscribes and re-arms the timeout for the next attempt.

timeout then retry — per-attempt deadline, N fresh tries. Usually what you want.
retry then timeout — one deadline spanning all attempts; a slow first try eats the whole budget.

Always bound the worst case: attempts × (timeout + maxBackoff) must stay under the caller's own deadline.

import { CallHandler, ExecutionContext, Injectable, NestInterceptor, RequestTimeoutException } from '@nestjs/common';
import { Observable, TimeoutError, throwError, timer } from 'rxjs';
import { catchError, retry, timeout } from 'rxjs/operators';

@Injectable()
export class ResilientInterceptor implements NestInterceptor {
  intercept(_ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    return next.handle().pipe(
      timeout(2000),               // per-attempt deadline
      retry({ count: 3, delay: (_e, n) => timer(100 * 2 ** (n - 1)) }),
      catchError((err) =>
        err instanceof TimeoutError
          ? throwError(() => new RequestTimeoutException())
          : throwError(() => err),
      ),
    );
  }
}

The Bulkhead: Capping Concurrency

Timeouts and retries protect a single request. A bulkhead protects the whole process: it limits how many in-flight calls a dependency may have, so a slow downstream can't pile up unbounded promises and exhaust threads, sockets, or memory.

Calls beyond the limit either queue (bounded) or are rejected fast (503).
Named after ship compartments: a flood in one section is sealed off from the rest.

A minimal bulkhead is a semaphore: a permit count plus a waiter queue.

export class Bulkhead {
  private active = 0;
  private readonly queue: Array<() => void> = [];

  constructor(private readonly maxConcurrent: number, private readonly maxQueue: number) {}

  async run<T>(task: () => Promise<T>): Promise<T> {
    if (this.active >= this.maxConcurrent) {
      if (this.queue.length >= this.maxQueue) throw new Error('BULKHEAD_FULL');
      await new Promise<void>((resolve) => this.queue.push(resolve));
    }
    this.active++;
    try {
      return await task();
    } finally {
      this.active--;
      this.queue.shift()?.();
    }
  }
}

A Runnable Bulkhead Simulation

Here is the bulkhead exercised end-to-end with simulated async work. Watch that no more than maxConcurrent tasks run at once, and overflow past the queue is rejected immediately — the fast-fail that keeps your service healthy.

class Bulkhead {
  private active = 0;
  private queue: Array<() => void> = [];
  constructor(private max: number, private maxQueue: number) {}
  async run<T>(task: () => Promise<T>): Promise<T> {
    if (this.active >= this.max) {
      if (this.queue.length >= this.maxQueue) throw new Error('BULKHEAD_FULL');
      await new Promise<void>((r) => this.queue.push(r));
    }
    this.active++;
    try { return await task(); }
    finally { this.active--; this.queue.shift()?.(); }
  }
}

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
const bh = new Bulkhead(2, 1);
let peak = 0, running = 0;

async function call(id: number) {
  try {
    await bh.run(async () => {
      running++; peak = Math.max(peak, running);
      await sleep(50);
      running--;
    });
    return `ok-${id}`;
  } catch (e) { return `rejected-${id}`; }
}

async function main() {
  const results = await Promise.all([1, 2, 3, 4, 5].map(call));
  console.log(results.join(', '));
  console.log('peak concurrency:', peak);
}
main();

Wiring the Bulkhead into an Interceptor

To apply a bulkhead per outbound dependency, hold a Bulkhead instance in a provider and run the handler stream through it. Use from(promise) to bridge the async run() back into RxJS, then layer timeout and retry on top.

One bulkhead instance per dependency, not per request — the limit is shared, so it must be a singleton provider.
Convert BULKHEAD_FULL into 503 Service Unavailable so callers can back off.

import { CallHandler, ExecutionContext, Injectable, NestInterceptor, ServiceUnavailableException } from '@nestjs/common';
import { Observable, defer, lastValueFrom } from 'rxjs';
import { catchError } from 'rxjs/operators';
import { Bulkhead } from './bulkhead';

@Injectable()
export class BulkheadInterceptor implements NestInterceptor {
  private readonly bulkhead = new Bulkhead(10, 20); // shared, singleton-scoped

  intercept(_ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    return defer(() => this.bulkhead.run(() => lastValueFrom(next.handle()))).pipe(
      catchError((err) => {
        if (err?.message === 'BULKHEAD_FULL') throw new ServiceUnavailableException('Capacity reached');
        throw err;
      }),
    );
  }
}

Composing All Three at the HttpModule Layer

In practice you rarely intercept inbound routes for outbound resilience — you wrap the HTTP client. With Nest's HttpService (Axios + RxJS) you pipe the same operators onto each outbound observable, and run it through the dependency's bulkhead.

Tune budgets per dependency: a fast cache gets a 200ms timeout; a report API gets 10s and zero retries.
Pair this with a circuit breaker so a dependency that keeps failing is shed before timeouts even fire.

import { Injectable } from '@nestjs/common';
import { HttpService } from '@nestjs/axios';
import { AxiosResponse } from 'axios';
import { Observable, defer, lastValueFrom, throwError, timer } from 'rxjs';
import { retry, timeout } from 'rxjs/operators';
import { Bulkhead } from './bulkhead';

@Injectable()
export class PricingClient {
  private readonly bulkhead = new Bulkhead(8, 16);
  constructor(private readonly http: HttpService) {}

  getPrice(sku: string): Observable<AxiosResponse> {
    return defer(() =>
      this.bulkhead.run(() =>
        lastValueFrom(
          this.http.get(`/pricing/${sku}`).pipe(
            timeout(800),
            retry({ count: 2, delay: (_e, n) => timer(100 * 2 ** (n - 1)) }),
          ),
        ),
      ),
    );
  }
}

Quick Check

You wrap an outbound call with both a 2s timeout and a 3-attempt retry inside one RxJS pipe. You want each attempt to have its own 2-second deadline. Which operator ordering achieves that?

Recap

You built the three core outbound-resilience patterns as composable NestJS interceptors:

Timeout — timeout(ms) + catchError to translate TimeoutError into 504/408; make it per-route via Reflector metadata.
Retry — retry({ count, delay }) with exponential backoff and full jitter, restricted to idempotent operations and transient status codes.
Bulkhead — a semaphore (active count + bounded queue) per dependency that fast-fails with 503 when capacity is reached, isolating one slow downstream.

Key decisions: place timeout before retry for per-attempt deadlines; keep bulkheads singleton-scoped per dependency; and always bound the worst case (attempts × (timeout + backoff)) below the caller's deadline. Combine these with a circuit breaker for full steady-state protection.

常见问题解答

「使用拦截器实现超时、重试与舱壁隔离」课时是免费的吗？

是的 — 「使用拦截器实现超时、重试与舱壁隔离」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 NestJS Enterprise Backend APIs 课程的其余内容，请升级到 CoddyKit PRO。 NestJS Enterprise Backend APIs 课程共包含 4 节课。

「使用拦截器实现超时、重试与舱壁隔离」这节课中我会学到什么？

实现基于 RxJS 的超时和重试拦截器，并为出站调用设置并发舱壁。你通过在浏览器中直接运行的动手代码来练习 NestJS Enterprise Backend APIs，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 NestJS Enterprise Backend APIs 需要有经验吗？

无需任何先前经验。CoddyKit 上的 NestJS Enterprise Backend APIs 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「使用拦截器实现超时、重试与舱壁隔离」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 NestJS Enterprise Backend APIs 课中编写并运行代码吗？

能。每节 NestJS Enterprise Backend APIs 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 NestJS Enterprise Backend APIs