NestJS Enterprise Backend APIs · 课时

延迟加载模块与功能开关

使用 LazyModuleLoader 按需加载可选功能模块，降低启动成本。

延迟加载模块与功能开关 是 CoddyKit 上的免费 NestJS Enterprise Backend APIs 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 NestJS Enterprise Backend APIs 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 NestJS Enterprise Backend APIs 课程共包含 4 节课。

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

Why Eager Loading Hurts Startup

By default, NestJS instantiates every module in your imports graph at bootstrap. For an enterprise API with dozens of optional features — a PDF exporter, a payment gateway, an AI scoring engine — that means paying the full provider-instantiation and connection-warmup cost before the app even accepts a request.

Heavy SDKs (Stripe, AWS, gRPC clients) run their constructors eagerly.
Modules a given deployment never uses still load.
Cold-start latency grows linearly with the module graph.

The fix: load select feature modules lazily, only when first invoked.

The LazyModuleLoader

Nest ships a built-in LazyModuleLoader (from @nestjs/core). You inject it like any provider, then call load() with a factory that returns the module. Nest registers the module's providers on demand and caches the resulting reference for subsequent calls.

Key traits:

Lazy modules are not listed in any imports array.
They do not register controllers, resolvers, or enhancers — only providers.
The first load() instantiates; later calls return the cached ModuleRef.

import { Injectable } from '@nestjs/common';
import { LazyModuleLoader } from '@nestjs/core';

@Injectable()
export class ReportsService {
  constructor(private readonly lazyModuleLoader: LazyModuleLoader) {}

  async generate(): Promise<void> {
    const { PdfModule } = await import('./pdf/pdf.module');
    const moduleRef = await this.lazyModuleLoader.load(() => PdfModule);
    // moduleRef now exposes PdfModule's providers
  }
}

Resolving a Provider From the Lazy Module

The object returned by load() is a ModuleRef. Use its get() method to pull a concrete provider out of the freshly-loaded module. Because lazy modules are isolated, request a provider only after the module is loaded.

For request-scoped or transient providers use moduleRef.resolve() instead of get().

async generate(): Promise<Buffer> {
  const { PdfModule } = await import('./pdf/pdf.module');
  const moduleRef = await this.lazyModuleLoader.load(() => PdfModule);

  const pdfService = moduleRef.get(PdfService);
  return pdfService.render({ title: 'Invoice' });
}

Dynamic import() Is What Saves the Bytes

The real startup win comes from pairing LazyModuleLoader.load() with a dynamic import(). A static top-level import pulls the module — and its heavy transitive deps — into the bootstrap bundle. A dynamic import() defers that file evaluation until the call runs.

Static import { PdfModule } at the top of the file = loaded at startup.
await import('./pdf/pdf.module') inside the method = loaded on first use.

So always import the lazy module's file dynamically, never statically.

A Lazy Feature Module Definition

The lazy module itself is an ordinary @Module — there is nothing special in its decorator. What makes it lazy is purely how it is consumed (via LazyModuleLoader rather than an imports array).

Keep its providers self-contained so loading it does not drag in the whole app.

import { Module } from '@nestjs/common';
import { PdfService } from './pdf.service';

@Module({
  providers: [PdfService],
  exports: [PdfService],
})
export class PdfModule {}

Caching Makes Repeated Loads Cheap

Nest internally keeps a registry of already-loaded lazy modules keyed by the factory result. So calling load() repeatedly with the same module class is effectively free after the first hit — no double instantiation, no duplicate connections.

This means you can safely call load() inline in a hot handler without guarding it yourself; the framework deduplicates. The one-time cost is paid on the first request that needs the feature.

Feature Toggles: Gate the Load

Feature toggles and lazy loading are a natural pair. Instead of conditionally registering modules at compile time, you check a flag at runtime and only load() the module when the flag is on. A disabled feature then costs nothing — not even its constructor.

Flag from env, config service, or a remote flag provider (LaunchDarkly, Unleash).
If the toggle is off, short-circuit before importing.

@Injectable()
export class ExportService {
  constructor(
    private readonly lazyModuleLoader: LazyModuleLoader,
    private readonly flags: FeatureFlagService,
  ) {}

  async export(payload: ExportDto) {
    if (!this.flags.isEnabled('pdf-export')) {
      throw new ForbiddenException('Feature disabled');
    }
    const { PdfModule } = await import('./pdf/pdf.module');
    const ref = await this.lazyModuleLoader.load(() => PdfModule);
    return ref.get(PdfService).render(payload);
  }
}

A Minimal Flag Service (Standalone)

A feature-flag check is just a deterministic lookup. Here is a framework-free version you can reason about and test in isolation — the same logic a Nest FeatureFlagService would wrap. It reads a flag map and falls back to a default when the key is unknown.

class FeatureFlags {
  constructor(private readonly flags: Record<string, boolean>) {}

  isEnabled(key: string, fallback = false): boolean {
    return this.flags[key] ?? fallback;
  }
}

const flags = new FeatureFlags({ 'pdf-export': true, 'ai-scoring': false });

console.log(flags.isEnabled('pdf-export'));   // true
console.log(flags.isEnabled('ai-scoring'));   // false
console.log(flags.isEnabled('unknown', true)); // true (fallback)

Controllers and Enhancers Are Ignored

A critical limitation: when a module is loaded lazily, Nest registers its providers only. It deliberately skips:

controllers — no new HTTP routes appear.
Global guards, interceptors, pipes, filters declared in the module.
GraphQL resolvers.

So a lazy module cannot add endpoints. Expose the feature through a controller in an eagerly-loaded module that delegates to the lazily-loaded provider.

@Controller('reports')
export class ReportsController {
  constructor(private readonly reports: ReportsService) {}

  @Post('pdf')
  async pdf(@Body() dto: ExportDto) {
    // controller is eager; PdfModule is loaded lazily inside the service
    return this.reports.generate(dto);
  }
}

Warming Up vs Lazy: Pick Per Feature

Lazy loading trades a one-time first-request latency spike for a faster, lighter startup. That is the right deal for rarely used, expensive features. For features on the hot path, eager loading (or an explicit warm-up on onApplicationBootstrap) avoids penalizing the first user.

Decision guide:

Lazy: heavy SDK, used by <X% of requests, optional per deployment.
Eager: core domain, every request, latency-sensitive.
Lazy + warm-up: heavy but predictably needed soon after boot.

@Injectable()
export class Warmer implements OnApplicationBootstrap {
  constructor(private readonly lazyModuleLoader: LazyModuleLoader) {}

  async onApplicationBootstrap() {
    if (process.env.PRELOAD_PDF === 'true') {
      const { PdfModule } = await import('./pdf/pdf.module');
      await this.lazyModuleLoader.load(() => PdfModule); // pay cost now, off the request path
    }
  }
}

Measuring the Win

Quantify before and after. Wrap bootstrap timing and the first lazy load() to confirm the trade-off is real for your workload.

Startup time should drop by the cumulative constructor + connection cost of the deferred modules.
First-call latency for the lazy feature absorbs that cost once.
Watch P99 of the first request after deploy — that is where the deferred cost surfaces.

If the lazy feature is hit on nearly every request, the numbers will tell you to switch it back to eager.

const t0 = performance.now();
const { PdfModule } = await import('./pdf/pdf.module');
const ref = await this.lazyModuleLoader.load(() => PdfModule);
this.logger.log(`Lazy PdfModule ready in ${Math.round(performance.now() - t0)}ms`);

Quick Check

You lazily load PdfModule via LazyModuleLoader. PdfModule declares a controller with a @Post('pdf') route. After loading, the route returns 404. What is the correct explanation and fix?

Recap

You learned how to shrink NestJS startup cost with on-demand modules:

LazyModuleLoader.load(() => SomeModule) instantiates a module's providers on first use and caches the result.
Pair it with a dynamic import() so the module's file (and heavy deps) is never evaluated at bootstrap.
Resolve providers via moduleRef.get() (or resolve() for scoped providers).
Feature toggles gate the load: a disabled feature costs nothing, not even a constructor.
Lazy modules register no controllers, resolvers, or enhancers — delegate from an eager controller.
Choose lazy for heavy, rarely-used, optional features; eager (or lazy + warm-up) for hot-path code. Measure startup and first-call latency to confirm the trade-off.

常见问题解答

「延迟加载模块与功能开关」课时是免费的吗？

是的 — 「延迟加载模块与功能开关」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 NestJS Enterprise Backend APIs 课程的其余内容，请升级到 CoddyKit PRO。 NestJS Enterprise Backend APIs 课程共包含 4 节课。

「延迟加载模块与功能开关」这节课中我会学到什么？

使用 LazyModuleLoader 按需加载可选功能模块，降低启动成本。你通过在浏览器中直接运行的动手代码来练习 NestJS Enterprise Backend APIs，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

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

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

「延迟加载模块与功能开关」课时需要多长时间？

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

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

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

此课程中的所有课时

← 返回 NestJS Enterprise Backend APIs