Собираем контейнер: разрешение вглубь, один экземпляр, токены

Возьмём три слоя, из которых состоит почти любая ручка API. Контроллер принимает запрос и зовёт сервис. Сервис решает, что делать, и сохраняет через репозиторий. Репозиторий знает, где лежат строки: пока это массив в памяти, потом будет Postgres. Второй контроллер, статистика, считает заметки через такой же сервис. У каждого класса один и тот же вопрос: откуда взять объект, от которого он зависит. Самый прямой ответ — создать самому, полем с new. Прогноз: что напечатает последняя строка?

class NotesRepo {
  #rows: string[] = [];

  add(text: string) {
    return this.#rows.push(text);
  }

  count() {
    return this.#rows.length;
  }
}

class NotesService {
  #repo = new NotesRepo();

  create(text: string) {
    return `заметка ${this.#repo.add(text)}: ${text}`;
  }

  count() {
    return this.#repo.count();
  }
}

class NotesController {
  #notes = new NotesService();

  post(body: { text: string }) {
    return this.#notes.create(body.text);
  }
}

class StatsController {
  #notes = new NotesService();

  get() {
    return `всего заметок: ${this.#notes.count()}`;
  }
}

const notes = new NotesController();
const stats = new StatsController();
console.log(notes.post({ text: "купить хлеб" }));
console.log(notes.post({ text: "позвонить маме" }));
console.log(stats.get());

Один объект на всех в Node уже встречался: модуль выполняется один раз, и пул, созданный в модуле, делят все файлы, которые его подключили. Но и там платил тест. Чтобы получить свежий объект, он удалял модуль из кеша require, а файлы, подключившие модуль раньше, продолжали работать со старым.

Выход — развернуть зависимость. Класс не создаёт то, что ему нужно, а получает готовым в конструкторе: constructor(private readonly repo: NotesRepo) {}. Это параметр-свойство, и так написан конструктор почти любого сервиса Nest. Объекты создаёт кто-то снаружи, один раз и в одном месте: const repo = new NotesRepo(), потом new NotesService(repo), потом оба контроллера с этим сервисом. Такой приём называют внедрением зависимостей. Порядок строк не выбирают: сервис нельзя создать раньше репозитория, его нечем передать в конструктор. Для четырёх объектов это четыре строки, а в приложении классов десятки, и держать порядок руками — та работа, которую отдают контейнеру.

Класс перечисляет, что ему нужно. Кто и когда это создаст, его не касается.

Контейнеру нужно знать, что передать в конструктор, а из самого класса этого не узнать. Типы стираются: от constructor(private readonly repo: NotesRepo) в выполняемом коде остаются constructor(repo) и присваивание this.repo = repo, а слова NotesRepo там нет. Nest получает типы параметров от компилятора, но так умеют только старые декораторы, стандартные — нет. Поэтому зависимости объявляются списком: @Injectable({ deps: [NotesRepo] }) кладёт список в WeakMap по самому классу, как реестр прошлой статьи. Метод get берёт класс, получает каждую его зависимость тем же get, только потом вызывает new и запоминает готовый объект в Map. Чтобы видеть его работу, get печатает, кого у него попросили и кого он создал. Прогноз: в каком порядке выйдут строки «нужен» и «создан» и напечатает ли что-нибудь второй get?

type Class = new (...args: any[]) => object;

const depsOf = new WeakMap<Class, Class[]>();

function Injectable(options: { deps?: Class[] } = {}) {
  return function (value: Class, context: ClassDecoratorContext) {
    depsOf.set(value, options.deps ?? []);
  };
}

class Container {
  #instances = new Map<Class, object>();

  get<T extends object>(cls: new (...args: any[]) => T): T {
    const ready = this.#instances.get(cls);
    if (ready) return ready as T;
    console.log(`нужен ${cls.name}`);
    const args = (depsOf.get(cls) ?? []).map((dep) => this.get(dep));
    const instance = new cls(...args);
    console.log(`создан ${cls.name}`);
    this.#instances.set(cls, instance);
    return instance;
  }
}

@Injectable()
class NotesRepo {
  #rows: string[] = [];

  add(text: string) {
    return this.#rows.push(text);
  }
}

@Injectable({ deps: [NotesRepo] })
class NotesService {
  constructor(private readonly repo: NotesRepo) {}

  create(text: string) {
    return `заметка ${this.repo.add(text)}: ${text}`;
  }
}

@Injectable({ deps: [NotesService] })
class NotesController {
  constructor(private readonly notes: NotesService) {}

  post(body: { text: string }) {
    return this.notes.create(body.text);
  }
}

const container = new Container();
const controller = container.get(NotesController);
console.log(controller.post({ text: "купить хлеб" }));
console.log(container.get(NotesController) === controller);

Просили сверху вниз: контроллер, сервис, репозиторий. Создавали снизу вверх: репозиторий, сервис, контроллер. Сортировки в контейнере нет, порядок получается из рекурсии. new NotesController(…) не вызвать, пока не вернулся get(NotesService), а тот ждёт get(NotesRepo). Первым возвращается самый глубокий вызов, и первым создаётся объект без зависимостей. Это и называют разрешением вглубь: контейнер спускается по зависимостям до дна и собирает объекты на обратном пути. Второй get не напечатал ничего: объект нашёлся в Map, и вернулся тот же контроллер с тем же сервисом внутри.

У списка есть цена. Порядок в deps обязан совпадать с порядком параметров конструктора, и сверить их некому: типы стёрты, а контейнер видит только функцию и массив. Переставьте в списке два разных сервиса — каждый параметр получит чужой объект, и в лучшем случае ошибка всплывёт на первом вызове метода, которого у чужого объекта нет. Когда список пишет компилятор, как в Nest, перестановки не бывает. А класс, у которого записи в реестре нет вовсе, контейнер пока молча создаёт без аргументов. К чему это приводит, разберёт статья о «Nest can't resolve dependencies».

Порядок создания нигде не записан: он получается из того, что new ждёт свои аргументы.

Второй get вернул тот же объект, и так контейнер обходится с каждым классом: создаёт один раз и отдаёт всем, кто попросит. Ниже два сервиса зависят от счётчика номеров. Контейнер из прошлого примера — в подложке, печать из него убрана. В последних двух строках появляются второй контейнер и сервис, созданный через new в обход контейнера. Прогноз: какие номера получат заметки и метка?

declare function Injectable(options?: { deps?: Function[] }): (value: Function, context: ClassDecoratorContext) => void;
declare class Container {
  get<T>(cls: new (...args: any[]) => T): T;
}

@Injectable()
class IdCounter {
  #last = 0;

  next() {
    return ++this.#last;
  }
}

@Injectable({ deps: [IdCounter] })
class NotesService {
  constructor(private readonly ids: IdCounter) {}

  create(text: string) {
    return `заметка ${this.ids.next()}: ${text}`;
  }
}

@Injectable({ deps: [IdCounter] })
class TagsService {
  constructor(private readonly ids: IdCounter) {}

  create(name: string) {
    return `метка ${this.ids.next()}: ${name}`;
  }
}

const app = new Container();
console.log(app.get(NotesService).create("купить хлеб"));
console.log(app.get(TagsService).create("дом"));
console.log(new Container().get(NotesService).create("позвонить маме"));
console.log(new NotesService(app.get(IdCounter)).create("сдать отчёт"));

Метка получила номер 2: у TagsService и NotesService один счётчик на двоих, потому что под ключом IdCounter в контейнере одна запись. Свежий контейнер начал с единицы: у него своя Map и свой счётчик. А сервис, созданный руками, выдал 3. Сам он новый — класс не мешает вызывать new сколько угодно раз, — но счётчик ему передали из app. Одиночкой объект делает не класс, а запись в контейнере: один объект на ключ, пока жив контейнер.

Для большинства сервисов так и нужно. Данных отдельного вызова они не хранят, а держат общее: пул соединений, настройки, кеш. Создавать их заново на каждый запрос значило бы заново соединяться с базой. Отсюда же удобство для тестов: вместо того чтобы вычищать кеш модулей, тест создаёт новый контейнер, и прежние объекты ему не мешают. Как на этом строится подмена репозитория в тестах, разберёт статья о тестах против настоящей базы.

Обратная сторона видна на метке. Общее состояние делят все, кто получил объект, в том числе те, кому оно не предназначалось. На сервере «все» — это ещё и все запросы сразу: контроллер и его сервисы создаются один раз и обслуживают каждый запрос, пока жив процесс. Поле такого сервиса, куда один запрос положил «текущего пользователя», увидит и другой. Для данных запроса у провайдеров Nest есть область запроса. Чего она стоит и как общее поле ломается на двух одновременных запросах, разберёт статья о модулях и областях. А счётчику, который заметкам и меткам нужен разный, поможет не область, а второй ключ.

Один экземпляр — на ключ в одном контейнере. Новый контейнер или new руками дают новый объект.

До сих пор ключом в Map контейнера был сам класс: попросили IdCounter — получили экземпляр IdCounter. Эти роли пора развести. Ключ, по которому объект просят, называют токеном, а правило, как этот объект получить, — провайдером. Токеном годится любое значение, ведь ключом Map бывает что угодно, но на деле это класс, строка или символ. Провайдеры у контейнера ниже трёх видов, и все три есть в Nest под теми же именами: useClass создаёт экземпляр класса с его зависимостями, useValue отдаёт готовое значение, useFactory вызывает функцию с зависимостями из inject. В deps теперь тоже токены. Счётчик зарегистрирован трижды: под своим классом и под двумя символами. Прогноз: что напечатают три последние строки?

type Token = Function | string | symbol;
type Provider =
  | { useClass: new (...args: any[]) => unknown }
  | { useValue: unknown }
  | { useFactory: (...args: any[]) => unknown; inject?: Token[] };

const depsOf = new WeakMap<Function, Token[]>();

function Injectable(options: { deps?: Token[] } = {}) {
  return function (value: Function, context: ClassDecoratorContext) {
    depsOf.set(value, options.deps ?? []);
  };
}

class Container {
  #providers = new Map<Token, Provider>();
  #instances = new Map<Token, unknown>();

  provide(token: Token, provider: Provider) {
    this.#providers.set(token, provider);
    return this;
  }

  get(token: Token): unknown {
    if (this.#instances.has(token)) return this.#instances.get(token);
    const provider = this.#providers.get(token);
    if (!provider) {
      const name = typeof token === "function" ? token.name : String(token);
      throw new Error(`нет провайдера для ${name}`);
    }
    let instance: unknown;
    if ("useValue" in provider) instance = provider.useValue;
    else if ("useClass" in provider) instance = new provider.useClass(...this.#getAll(depsOf.get(provider.useClass)));
    else instance = provider.useFactory(...this.#getAll(provider.inject));
    this.#instances.set(token, instance);
    return instance;
  }

  #getAll(tokens: Token[] = []) {
    return tokens.map((token) => this.get(token));
  }
}

class IdCounter {
  #last = 0;

  next() {
    return ++this.#last;
  }
}

const NOTE_IDS = Symbol("note-ids");
const TAG_IDS = Symbol("tag-ids");

const app = new Container()
  .provide(IdCounter, { useClass: IdCounter })
  .provide(NOTE_IDS, { useClass: IdCounter })
  .provide(TAG_IDS, { useClass: IdCounter });

const noteIds = app.get(NOTE_IDS) as IdCounter;
noteIds.next();
console.log(noteIds.next());
console.log((app.get(TAG_IDS) as IdCounter).next());
console.log(app.get(IdCounter) === app.get(NOTE_IDS));

Второе, ради чего заводят токены, — зависеть не от конкретного класса. Сервису заметок нужно хранилище: в тесте в памяти, в работе в Postgres. Хочется написать deps: [NotesStore], где NotesStore — интерфейс. Компилятор ответит «"NotesStore" относится только к типу, но используется здесь как значение», в терминале это TS2693, а запуск упадёт с ReferenceError. Интерфейс исчезает при компиляции бесследно, и контейнеру нечего положить в Map. Ключ должен дожить до выполнения. Строка доживёт, но две части приложения, выбравшие одинаковую строку, в нашем контейнере затрут записи друг друга. Символ равен только себе, и два Symbol("notes") не совпадут никогда. В Nest токеном можно сделать и абстрактный класс: abstract при сборке стирается, а сам класс остаётся, и одно имя служит и типом параметра, и ключом.

Токен — адрес ячейки, провайдер — что в неё положить. Тип параметра ни то ни другое.

Ниже NotesService зависит от символа NOTES, а параметр описан интерфейсом. Контейнеров два, и собраны они по-разному. В рабочем под NOTES фабрика: она берёт адрес базы из настроек под CONFIG и соединяется — connect здесь только печатает адрес и считает строки. В тестовом под тем же токеном готовая подделка, чей add всегда отвечает 42. Контейнер из прошлого примера — в подложке. Прогноз: сколько раз напечатается «соединяюсь» и какой номер выдаст тестовый контейнер?

type Token = Function | string | symbol;
declare function Injectable(options?: { deps?: Token[] }): (value: Function, context: ClassDecoratorContext) => void;
declare class Container {
  provide(token: Token, provider: object): this;
  get(token: Token): unknown;
}

interface NotesStore {
  add(text: string): number;
}

const NOTES = Symbol("notes");
const CONFIG = Symbol("config");

@Injectable({ deps: [NOTES] })
class NotesService {
  constructor(private readonly store: NotesStore) {}

  create(text: string) {
    return `заметка ${this.store.add(text)}: ${text}`;
  }
}

function connect(url: string): NotesStore {
  console.log(`соединяюсь с ${url}`);
  let rows = 0;
  return { add: () => ++rows };
}

const app = new Container()
  .provide(CONFIG, { useValue: { databaseUrl: "postgres://localhost/app" } })
  .provide(NOTES, {
    useFactory: (config: { databaseUrl: string }) => connect(config.databaseUrl),
    inject: [CONFIG],
  })
  .provide(NotesService, { useClass: NotesService });

const test = new Container()
  .provide(NOTES, { useValue: { add: () => 42 } })
  .provide(NotesService, { useClass: NotesService });

for (const container of [app, app, test]) {
  const notes = container.get(NotesService) as NotesService;
  console.log(notes.create("купить хлеб"));
}

Цена этой свободы стоит в строке container.get(NotesService) as NotesService. get возвращает unknown: по символу компилятор не знает, что под ним лежит, а as ничего не проверяет. То же с параметром store: NotesStore — это обещание, а не проверка. Подделку { add: () => "42" } со строкой вместо числа контейнер принял бы без единой диагностики. В Nest та же дыра: @Inject(NOTES) принимает любой токен, и тип параметра рядом с ним компилятор с провайдером не сверяет. Как привязать тип к самому токену, — во второй задаче.

В главном модель совпадает с Nest: токен — ключ, провайдер — рецепт, зависимость создаётся раньше того, кто её получает, и по умолчанию под токеном один объект. Провайдеры в Nest перечисляют в модуле: это класс с декоратором @Module, у которого в массиве providers лежат провайдеры, а в controllers — контроллеры. Модуль передают в NestFactory.create, и тот возвращает готовое приложение. Расходится модель с нашей там, где разницу видно только запуском. Сверено с Nest 12.0.3: проект собран tsc с experimentalDecorators и emitDecoratorMetadata и запущен node.

Две строки таблицы стоит развернуть. Первая — когда. Nest не ждёт первого get: внутри NestFactory.create он создаёт все провайдеры и контроллеры, в том числе провайдер, который никто не просит. Исключение — провайдеры с областью запроса: их создают на каждый запрос. Ошибка в фабрике или конструкторе роняет запуск, а не первый запрос — тот же принцип, ради которого статья о старте приложения проверяет настройки раньше всего остального. Вторая — порядок. Если перечислить провайдеры как [NotesService, Unused, NotesRepo], где Unused ни от кого не зависит и никому не нужен, конструкторы вызовутся в порядке Unused, NotesRepo, NotesService, и только потом контроллеры. Провайдеры модуля Nest создаёт через Promise.all: фабрика бывает асинхронной, поэтому весь контейнер работает на промисах. Пока NotesService дожидался репозитория, Unused успел появиться. Гарантия остаётся одна, та же, что у рекурсии: зависимость готова раньше того, кто её получает. На порядок остальных полагаться нельзя.

Список зависимостей в Nest пишет компилятор. С emitDecoratorMetadata он сохраняет в метаданных класса типы параметров конструктора, у NotesService это [NotesRepo], и контейнер читает их вместо нашего deps. Интерфейс там превращается в Object, по которому искать нечего, поэтому для токена-символа или строки перед параметром ставят @Inject(NOTES) — декоратор параметра, которого нет в стандарте. Откуда берутся эти метаданные и чем такой проект собирать, разберёт статья «Почему Nest живёт на старых декораторах».

Остаётся граница. Наш контейнер плоский: любой класс достаёт любой токен. В Nest провайдеры живут в модулях, и «один объект на токен» считается внутри модуля: класс, записанный в providers двух модулей, даёт два объекта. Модули и то, почему провайдер одного из них не виден другому без экспорта, контейнер получит в следующей статье.