Phạm vi inject (Injection scopes)

Với những ai đến từ các ngôn ngữ lập trình khác, có thể sẽ bất ngờ khi biết rằng trong Nest, hầu như mọi thứ đều được chia sẻ (shared) giữa các request đến. Chúng ta có một connection pool tới database, các service singleton với global state, v.v. Hãy nhớ rằng Node.js không theo mô hình request/response Multi-Threaded Stateless, trong đó mỗi request được xử lý bởi một thread riêng. Do đó, việc dùng các instance singleton là hoàn toàn an toàn cho ứng dụng của chúng ta.

Tuy nhiên, có những trường hợp ngoại lệ mà vòng đời (lifetime) gắn theo request lại là hành vi mong muốn, ví dụ: cache theo từng request trong ứng dụng GraphQL, request tracking, và multi-tenancy. Phạm vi inject (injection scope) cung cấp cơ chế để có được vòng đời provider mong muốn.

Phạm vi provider (Provider scope)

Một provider có thể có một trong các phạm vi (scope) sau:

Cách dùng

Chỉ định phạm vi inject bằng cách truyền thuộc tính scope vào object option của decorator @Injectable():

import { Injectable, Scope } from '@nestjs/common';

@Injectable({ scope: Scope.REQUEST })
export class CatsService {}

Tương tự, với custom provider, thiết lập thuộc tính scope ở dạng khai báo đầy đủ (long-hand) khi đăng ký provider:

{
  provide: 'CACHE_MANAGER',
  useClass: CacheManager,
  scope: Scope.TRANSIENT,
}

Phạm vi singleton được dùng mặc định và không cần khai báo. Nếu bạn thực sự muốn khai báo một provider là singleton, dùng giá trị Scope.DEFAULT cho thuộc tính scope.

Phạm vi controller (Controller scope)

Controller cũng có thể có scope, áp dụng cho tất cả các hàm xử lý route (route handler) khai báo trong controller đó. Giống như phạm vi provider, phạm vi controller quy định vòng đời của nó. Với controller request-scoped, một instance mới được tạo cho mỗi request đến, và bị garbage-collected khi request xử lý xong.

Khai báo phạm vi controller bằng thuộc tính scope của object ControllerOptions:

@Controller({
  path: 'cats',
  scope: Scope.REQUEST,
})
export class CatsController {}

Phân cấp phạm vi (Scope hierarchy)

Phạm vi REQUEST lan truyền ngược lên (bubbles up) chuỗi inject. Một controller phụ thuộc vào một provider request-scoped thì bản thân controller đó cũng sẽ trở thành request-scoped.

Hãy tưởng tượng đồ thị phụ thuộc sau: CatsController <- CatsService <- CatsRepository. Nếu CatsService là request-scoped (còn các provider khác vẫn là singleton mặc định), CatsController sẽ trở thành request-scoped vì nó phụ thuộc vào service đã được inject. CatsRepository, do không phụ thuộc vào provider nào request-scoped, sẽ vẫn giữ nguyên singleton.

Các phụ thuộc (dependency) transient-scoped không theo quy luật này. Nếu một DogsService singleton-scoped inject một provider LoggerService transient, nó sẽ nhận một instance mới của provider đó. Tuy nhiên, DogsService vẫn giữ nguyên singleton-scoped, nên inject nó ở bất kỳ đâu cũng sẽ không trả về một instance mới của DogsService. Nếu đây là hành vi mong muốn, DogsService cũng phải được đánh dấu tường minh là TRANSIENT.

Request provider

Trong ứng dụng HTTP server-based (ví dụ dùng @nestjs/platform-express hoặc @nestjs/platform-fastify), có thể bạn sẽ muốn truy cập tham chiếu tới request object gốc khi dùng provider request-scoped. Bạn có thể làm điều này bằng cách inject object REQUEST.

Provider REQUEST vốn dĩ đã là request-scoped, nghĩa là bạn không cần khai báo tường minh scope REQUEST khi dùng nó. Thậm chí nếu bạn cố tình khai báo, nó cũng sẽ bị bỏ qua. Bất kỳ provider nào phụ thuộc vào một provider request-scoped sẽ tự động trở thành request-scoped, và hành vi này không thể thay đổi.

import { Injectable, Scope, Inject } from '@nestjs/common';
import { REQUEST } from '@nestjs/core';
import { Request } from 'express';

@Injectable({ scope: Scope.REQUEST })
export class CatsService {
  constructor(@Inject(REQUEST) private request: Request) {}
}

Do có khác biệt về nền tảng/giao thức bên dưới, cách bạn truy cập request đến sẽ hơi khác một chút đối với ứng dụng Microservice hay GraphQL. Trong ứng dụng GraphQL, bạn inject CONTEXT thay vì REQUEST:

import { Injectable, Scope, Inject } from '@nestjs/common';
import { CONTEXT } from '@nestjs/graphql';

@Injectable({ scope: Scope.REQUEST })
export class CatsService {
  constructor(@Inject(CONTEXT) private context) {}
}

Sau đó bạn cấu hình giá trị context (trong GraphQLModule) để nó chứa request như một thuộc tính của mình.

Inquirer provider

Nếu bạn muốn lấy ra class nơi một provider được khởi tạo, chẳng hạn trong các provider logging hoặc metrics, bạn có thể inject token INQUIRER.

import { Inject, Injectable, Scope } from '@nestjs/common';
import { INQUIRER } from '@nestjs/core';

@Injectable({ scope: Scope.TRANSIENT })
export class HelloService {
  constructor(@Inject(INQUIRER) private parentClass: object) {}

  sayHello(message: string) {
    console.log(`${this.parentClass?.constructor?.name}: ${message}`);
  }
}

Rồi dùng như sau:

import { Injectable } from '@nestjs/common';
import { HelloService } from './hello.service.js';

@Injectable()
export class AppService {
  constructor(private helloService: HelloService) {}

  getRoot(): string {
    this.helloService.sayHello('My name is getRoot');

    return 'Hello world!';
  }
}

Trong ví dụ trên, khi AppService#getRoot được gọi, dòng "AppService: My name is getRoot" sẽ được log ra console.

Hiệu năng (Performance)

Dùng provider request-scoped sẽ ảnh hưởng đến hiệu năng ứng dụng. Dù Nest cố gắng cache metadata nhiều nhất có thể, nó vẫn phải tạo một instance của class bạn cho mỗi request. Do đó, nó sẽ làm chậm thời gian phản hồi trung bình và kết quả benchmark tổng thể. Trừ khi provider bắt buộc phải request-scoped, bạn nên ưu tiên dùng phạm vi singleton mặc định.

Durable provider

Như đã đề cập ở phần trên, provider request-scoped có thể làm tăng độ trễ vì chỉ cần có ít nhất 1 provider request-scoped (được inject vào controller, hoặc sâu hơn - inject vào một trong các provider của nó) cũng khiến controller đó trở thành request-scoped. Điều đó nghĩa là nó phải được tạo lại (khởi tạo) cho từng request riêng lẻ (và bị garbage collect sau đó). Nghĩa là, ví dụ với 30 nghìn request song song, sẽ có 30 nghìn instance tạm thời (ephemeral) của controller (và các provider request-scoped của nó).

Việc có một provider dùng chung mà hầu hết các provider khác đều phụ thuộc vào (ví dụ: một kết nối database, hay một logger service), sẽ tự động biến tất cả các provider đó thành request-scoped luôn. Điều này có thể gây khó khăn trong các ứng dụng multi-tenant, đặc biệt với những ứng dụng có một provider “data source” request-scoped trung tâm, lấy header/token từ request object và dựa vào giá trị đó để lấy ra connection/schema database tương ứng (riêng cho tenant đó).

Ví dụ, giả sử bạn có một ứng dụng được 10 khách hàng khác nhau dùng luân phiên. Mỗi khách hàng có data source riêng, và bạn muốn đảm bảo khách hàng A không bao giờ có thể chạm tới database của khách hàng B. Một cách để làm điều này là khai báo một provider “data source” request-scoped - dựa trên request object - xác định “khách hàng hiện tại” là ai và lấy ra database tương ứng. Với cách này, bạn có thể biến ứng dụng của mình thành ứng dụng multi-tenant chỉ trong vài phút. Nhưng, một nhược điểm lớn của cách này là vì phần lớn các component trong ứng dụng của bạn phụ thuộc vào provider “data source”, chúng sẽ ngầm trở thành “request-scoped”, và do đó chắc chắn bạn sẽ thấy ảnh hưởng đến hiệu năng ứng dụng.

Nhưng nếu có một giải pháp tốt hơn thì sao? Vì chúng ta chỉ có 10 khách hàng, chẳng phải chúng ta có thể có 10 DI sub-tree riêng cho từng khách hàng (thay vì tạo lại toàn bộ cây cho mỗi request) hay sao? Nếu provider của bạn không phụ thuộc vào thuộc tính thực sự riêng biệt cho từng request liên tiếp (ví dụ: request UUID) mà thay vào đó có một số thuộc tính cụ thể cho phép chúng ta gộp nhóm (phân loại) chúng, thì không có lý do gì phải tạo lại DI sub-tree cho mỗi request đến.

Và đó chính xác là lúc durable provider phát huy tác dụng.

Trước khi đánh dấu provider là durable, trước tiên ta phải đăng ký một strategy để chỉ cho Nest biết đâu là “các thuộc tính chung của request”, cung cấp logic để gộp nhóm các request - liên kết chúng với DI sub-tree tương ứng.

import {
  HostComponentInfo,
  ContextId,
  ContextIdFactory,
  ContextIdStrategy,
} from '@nestjs/core';
import { Request } from 'express';

const tenants = new Map<string, ContextId>();

export class AggregateByTenantContextIdStrategy implements ContextIdStrategy {
  attach(contextId: ContextId, request: Request) {
    const tenantId = request.headers['x-tenant-id'] as string;
    let tenantSubTreeId: ContextId;

    if (tenants.has(tenantId)) {
      tenantSubTreeId = tenants.get(tenantId);
    } else {
      tenantSubTreeId = ContextIdFactory.create();
      tenants.set(tenantId, tenantSubTreeId);
    }

    // Nếu cây không phải durable, trả về "contextId" gốc
    return (info: HostComponentInfo) =>
      info.isTreeDurable ? tenantSubTreeId : contextId;
  }
}

Giá trị trả về từ phương thức attach cho Nest biết định danh context nào nên được dùng cho một host cụ thể. Trong trường hợp này, chúng ta chỉ định rằng tenantSubTreeId nên được dùng thay cho contextId gốc được tự sinh, khi host component (ví dụ: controller request-scoped) được đánh dấu là durable (bạn có thể xem cách đánh dấu provider là durable bên dưới). Ngoài ra, trong ví dụ trên, sẽ không có payload nào được đăng ký (payload = provider REQUEST/CONTEXT đại diện cho “gốc” - cha của sub-tree).

Nếu bạn muốn đăng ký payload cho một durable tree, hãy dùng cấu trúc sau thay thế:

// Giá trị trả về của phương thức `AggregateByTenantContextIdStrategy#attach`:
return {
  resolve: (info: HostComponentInfo) =>
    info.isTreeDurable ? tenantSubTreeId : contextId,
  payload: { tenantId },
};

Giờ đây bất cứ khi nào bạn inject provider REQUEST (hoặc CONTEXT cho ứng dụng GraphQL) bằng @Inject(REQUEST)/@Inject(CONTEXT), object payload sẽ được inject (gồm một thuộc tính duy nhất - tenantId trong trường hợp này).

Được rồi, với strategy này đã sẵn sàng, bạn có thể đăng ký nó ở đâu đó trong code (vì nó áp dụng toàn cục), ví dụ bạn có thể đặt trong file main.ts:

ContextIdFactory.apply(new AggregateByTenantContextIdStrategy());

Miễn là việc đăng ký diễn ra trước khi bất kỳ request nào chạm tới ứng dụng của bạn, mọi thứ sẽ hoạt động đúng như dự kiến.

Cuối cùng, để biến một provider thông thường thành durable provider, chỉ cần đặt flag durable thành true và đổi scope của nó thành Scope.REQUEST (không cần nếu scope REQUEST đã có sẵn trong chuỗi inject):

import { Injectable, Scope } from '@nestjs/common';

@Injectable({ scope: Scope.REQUEST, durable: true })
export class CatsService {}

Tương tự, với custom provider, thiết lập thuộc tính durable ở dạng khai báo đầy đủ khi đăng ký provider:

{
  provide: 'foobar',
  useFactory: () => { ... },
  scope: Scope.REQUEST,
  durable: true,
}