Об одной из важнейшей функциональностей фреймворка Angular «Внедрение зависимостей» расскажу я, Александр Желнин, full-stack разработчик, архитектор Департамента информационных технологий Россельхозбанка и автор YouTube-канала.

Мне захотелось представить на конкретных примерах все возможные варианты регистрации зависимостей и их подключения в классах. А также поделиться трудностями, с которыми можно столкнуться, и рассказать об опыте применения «Внедрения зависимостей».

На просторах рунета о «Внедрения зависимостей» написано преступно мало, в основном затрагивается, только «Внедрение сервисов». A «Внедрение зависимостей» — это не только сервисы, но и другие сущности, о которых по какой-то причине не говорят. С помощью «Внедрение зависимостей» вы можете передавать настройки, например, URL к back-end сервису и многое другое. Так же в зависимости от типа сборки можно подменять зависимости с учётом особенностей, например, для тестирования или «параноидального» логирования.

Немного теории по теме

Начнём с такого набора принципов, который называется SOLID. Каждая буква из этого названия — это первая буква соответствующего принципа. Обратим внимание на последний принцип Dependency Inversion «Инверсия зависимостей», который говорит о том, что объект не должен создавать зависимости внутри себя, а должен получать эти зависимости, например, в конструкторе. Ниже приведу примеры без инверсии зависимостей и с инверсией зависимостей. Начнем с примера без инверсии:

class CarOptions
{
  public static read(id: number): CarOptions
  {
    return new CarOptions();
  }
}

class CarComponent
{
  public id: number = 1;
  public options?: CarOptions;

  constructor()
  {
    // Тут зависимость создаём в самом классе.
    // Более того сама зависимость может создавать зависимости и т.д.
    this.options = new CarOptions();

    // или

    this.options = CarOptions.read(this.id);
  }
}

В этом примере в классе машина создаёт зависимость на опции машины. У классического подхода без «Инверсии зависимостей» есть недостатки, например, повышается сложность такого класса, потому что класс должен знать, как и откуда получать зависимости.

Рассмотрим пример с «Инверсией зависимостей»:

class Car
{
  constructor(public carOptions: CarOptions)
  {
  }
}

 Принцип «Инверсия зависимостей» даёт ряд неоспоримых преимуществ:

• упрощает взаимосвязи класса: класс получает зависимости в конструкторе

• юнит-тестирование класса упрощается: тестирование происходит только класса, а не его зависимостей

К минусам при «голом» использовании принципа «Инверсия зависимостей» можно отнести то, что объекты класса могут создаваться множество раз, и писать код для передачи зависимостей — трудозатратно.

new Car(new CarOptions(/* тут аргументы*/) /*, а тут ещё зависимости, которых может быть много!!! */)

Механизм, позволивший автоматизировать процесс создания объектов с учётом зависимостей, называется Dependency Injection «Внедрения зависимостей».

Для понимания: принцип «Инверсии зависимостей» и механизм «Внедрения зависимостей» — это разные понятия и в первом случае — это паттерн, а во втором — реализация, позволяющая нам использовать этот принцип на практике.

В Angular механизм «Внедрение зависимостей» работает по принципу:

• Во-первых, создаётся механизм регистрации зависимостей, который называется DI Container

• Во-вторых, создание объекта переносится на фабрику классов, называемую Injector

В итоге фабрика создаёт объекты, передавая зависимости, которые получает из контейнера зависимостей.

injector.get('ключ, например тип')

В качестве зависимостей можем использовать такие типы как:

• Сервисы (выделил в отдельный пункт, потому что сервисы часто получают другие сервисы, в качестве зависимостей и т.д.)

• Значения

  • Скалярные

  • Объекты

  • Функции

Такое разделение условное, и служит лишь примером.

Как же регистрируется зависимости?

Для ответа на этот вопрос необходимо понять, что существуют несколько уровней иерархии для регистрации зависимостей:

Зарегистрировать зависимость можно на любом из уровней, представленном на схеме. Для понимания, каждый элемент схемы — это уровень. В итоге получаем иерархию регистраций зависимостей. При получении зависимости фабрика если не находит зависимость на текущем уровне, переходит вверх по иерархии, пока не найдёт необходимую зависимость.

 Пояснения по схеме:

Первый уровень — это уровень платформы. В своей практике я не регистрирую зависимости на этом уровне, в этом нет необходимости, но такая возможность присутствует.

Большинство зависимостей регистрируются в модулях. Общие зависимости регистрируются в корневом модуле, и если его не переименовывали, то он называется AppModule.

Перейдём непосредственно к регистрации зависимостей.

В Angular зависимости можно зарегистрировать 2-мя возможными способами: 

Давайте подробно рассмотрим оба способа.

Регистрация в providers

В простейшем случае регистрация зависимости, выглядит так:

providers: [
  OptionsService,
  /* Другие провайдеры */
]

В более сложном случае необходимо указывать ключ и реализацию экземпляра зависимости:

Для начала разберём какие варианты «ключей» бывают:

• Строка

 providers: [
  // регистрация
  { 
    provide: 'API_URL',
    /* тут будет вариант подстановки зависимости */
  },
  /* Другие провайдеры */
]

Этот вариант плох тем, что строковый ключ легко могут использовать в подключаемой библиотеке, в результате чего будет конфликт. Настоятельно не рекомендую применять этот вариант на практике, чтобы потом не тратить время на поиск ошибки.

• Класс

providers: [
  // регистрация
  {
    provide: OptionsService, 
    /* тут будет вариант подстановки зависимости */
  },
  /* Другие провайдеры */
]

Если хотим делать несколько реализаций, то в качестве ключа можем использовать класс. Но при одной реализации лучше применять упрощённую регистрацию, которая описана ниже в примере UseClass.

• Токен  

/** Объявление токена */
export const API_URL_TOKEN = new InjectionToken<string>('API_URL'); 

// регистрация
providers: [
  {
    provide: API_URL_TOKEN, 
    /* тут будет вариант подстановки зависимости */
  },
  /* Другие провайдеры */
]

Использование токена в качестве ключа наиболее предпочтительно. Строковый ключ рекомендую всегда заменять на токен.

 

С вариантами ключей разобрались, перейдём к вариантам подстановки зависимости. Angular поддерживает такие варианты как useClass, useValue, useFactory, useExisting.

Подробно разберём каждый из этих вариантов:

• useClass

Это самый простой вариант, который заключается в том, что для реализации указывается класс.

providers: [
  { provide: OptionsService, useClass: OptionsService },
  /* Другие провайдеры */
]

Пример ниже это упрощённая запись примера выше. И если хотите зарегистрировать сервис без вариантов, то сокращённая запись предпочтительнее.

providers: [
  OptionsService,
  /* Другие провайдеры */
]

• useValue

В этом варианте подставляем конкретный экземпляр значения, которое может быть любым типом данных.

providers: [
  // число
  { provide: 'VALUE_NUMBER', useValue: 1  },
  // текст
  { provide: 'VALUE_STRING', useValue: 'Текстовое значение' },
  // функция
  { provide: 'VALUE2_FUNCTION', useValue: () => { return 'что-то' } },
  // объект
  { provide: 'VALUE2_OBJECT', useValue: { id: 1, name: 'имя' } },
  // массив
  { provide: 'VALUE2_ARRAY', useValue: [1, 2, 3] } },
  // и т.д.
  /* Другие провайдеры */
]

С помощь регистрации значений часто регистрируют конфигурационные значения. Например, Angular содержит файлы environment, в которых хранятся конфигурационные значения в зависимости от типа сборки, но к этим файлам нет доступа из подключаемых библиотек. В своей практике часто беру значение из environment и регистрирую это значение в контейнере, после чего к конфигурации получает доступ библиотека. В примере ключ сделал строкой исключительно в демонстрационных целях, в реальных проекта используйте токены. 

• useFactory

Это вариант, в котором функция регистрируется как результат. Функция выполняет роль фабрики, возвращающей значение зависимости.

providers: [
    { provide: 'VALUE', useFactory: () => { return 'что-то' } }, 
    /* Другие провайдеры */
  ]

Вариант useFactory отличается от варианта useValue c функцией тем, что когда возвращается функция в useValue, потом с этой функцией необходимо работать как с функцией, а с фабрикой получаем значение, с которым и работаем, и нет повторных вызовов функции.

Для работы фабрики часто необходимо получать зависимости, поэтому предусмотрен механизм передачи зависимостей в функцию фабрики.

Хочу привести «реальный» пример, которой заключается в том, что необходимо получать настройки, например, с back-end, а потом зарегистрировать эти настройки в качестве зависимости.

/** Интерфейс конфигурации */
export interface ISettings
{
  /** URL к API для некоторого сервиса My */
  apiUrlMy: string;
} 

/** Токен конфигурации */
export const SETTINGS_TOKEN = new InjectionToken<Observable<ISettings>>('SETTINGS_TOKEN');
/** Токен для получения URL API */
export const API_URL_MY_TOKEN = new InjectionToken<Observable<string>>('API_URL_MY_TOKEN'); 

providers: [
  {
    provide: SETTINGS_TOKEN,

    useFactory: (http: HttpClient): Observable<ISettings> =>
      http
        .get<ISettings>('/assets/settings.json')
        .pipe(shareReplay()),
    deps: [HttpClient]
  },
  {
    provide: API_URL_MY_TOKEN,
    useFactory:
      (injector: Injector) =>
        injector.get(SETTINGS_TOKEN).pipe(map(s => s.apiUrlMy)),
    deps: [Injector]
  }, 
  /* Другие провайдеры */
]

В представленном примере хотелось бы обратить внимание на свойство deps, которое осуществляет передачу зависимостей в фабрику.

• useExisting

Этот вариант наиболее непонятный для новичка. Суть useExisting заключается в том, что выбирается уже существующая зависимость.

providers: [
  { provide: 'CarService1', useClass: CarService},
  { provide: 'CarService2', useExisting: 'CarService1' }, 
  /* Другие провайдеры */
]

Сразу отвечу на первый же вопрос – почему мы не должны написать код так:

providers: [
  { provide: 'CarService1', useClass: CarService },
  { provide: 'CarService2', useClass: CarService },
  /* Другие провайдеры */
]

Этот вариант регистрация зависимости создаст нам два экземпляра CarService. Что может доставить много не удобств при отладке, т.к. сервис часто хранит состояние, в результате чего произойдёт так называемый сайд-эффект.

Расскажу почему ещё так важен useExisting

 При работе с компонентом экземпляр компонента регистрируется в «Контейнере зависимостей», таким образом легко получить доступ для родительского компонента.

/** Родительский компонент "Машина" */
@Component({
  selector: 'car-di',
  template: `
  <p>car-di works!</p>
  <wheels-di ad-car></wheels-di>`
})
export class CarComponent
{
  constructor() { }
}

/** Дочерний компонент "Колёса машины" демонстрирует через DI получаем доступ к родительскому компоненту */
@Component({
  selector: 'wheels-di',
  template: `<p>wheels works!</p>`
})
export class WheelsComponent
{
  /**
   * Конструктор, в котором получаем DI аргументы
   * @param car Родительский компонент "Машина"
   */
  constructor(public car: CarComponent) { }
} 

/** Директива демонстрирует доступ к родительским компонентам по средствам DI */
@Directive({ selector: '[ad-car]' })
export class CarDirective
{
  /**
   * Конструктор, в котором получаем DI аргументы
   * @param wheels Родительский компонент "Колёса"
   * @param car Родительский -> Родительский компонент "Колёса"
   */
  constructor(wheels: WheelsComponent, car: CarComponent)
  {
  }
}

Разработчики часто пишут универсальные директивы, которые можно использовать в разных компонентах. Поэтому необходимо получить доступ к компоненту по универсальному ключу, а дальше работать с базовым интерфейсом компонента. Для этого нужно использовать регистрацию зависимости useExisting c реализацией forwardRef

/** Общий интерфейс */
export interface IUniversal
{
  /** Марка */
  name: string;
  /** Масса */
  weight: number;
} 

/** Токен для роботы в DI */
export const UNIVERSAL_TOKEN = new InjectionToken<IUniversal>('UNIVERSAL_TOKEN'); 

/** Дочерний компонент "Колёса машины" демонстрирует регистрацию зависимости для специального токена, в качестве зависимости выступает сам компонент */
@Component({
  selector: 'wheels-universal-di',
  template: `<p>wheels works!</p>`,
  providers:[
    { provide: UNIVERSAL_TOKEN, useExisting: forwardRef(() => WheelsComponent), multi: true }
  ]
})
export class WheelsComponent implements IUniversal
{
  /** Марка, от интерфейса IUniversal */
  public name = 'no-name';
  /** Масса, от интерфейса IUniversal */
  public weight = 10; 

  /**
   * Конструктор, в котором получаем DI аргументы
   * @param car Родительский компонент "Машина"
   */
  constructor(public car: CarComponent) { }
} 

/** Получаем доступ к родительскому компоненту используя базовый интерфейс. Соответственно эта директива может работать со всеми компонентами, реализующих UNIVERSAL_TOKEN */
@Directive({ selector: '[ad-universal]' })
export class UniversalDirective
{
  /**
   * Конструктор
   * @param universal объект с базовой реализацией интер
   */
  constructor(@Inject(UNIVERSAL_TOKEN) universal: IUniversal) { }
}

forwardRef позволяет обратиться к ещё не зарегистрированной зависимости. Из примера понятно, что в коде декоратора сам компонент ещё не был зарегистрирован в контейнере зависимостей. 

Такая же реализация помогает решить задачу получения события загрузки компонента. Ссылка на видео: https://youtu.be/097plGqjP0U

Кроме того, самая часто встречающая реализация — это ngModel. Это тема для отдельной статьи.

Регистрация нескольких зависимостей с одинаковым ключом

 Так же хотелось бы обратить внимание на дополнительное свойство multi. Приведу пример, который часто может быть необходим:

{ provide: HTTP_INTERCEPTORS, useClass: HttpInterceptorService1, multi: true },

{ provide: HTTP_INTERCEPTORS, useClass: HttpInterceptorService2, multi: true }

Если не указывать свойство multi, то в результате бы работал только HttpInterceptorService2. Свойство multi даёт нам возможность, чтобы одна зависимость не переписывала другу, если ключ совпадает, а накапливала зависимости в массиве.

И если получить зависимость по ключу, то в результате будет массив зависимостей.

const interceptors = injector.get(HTTP_INTERCEPTORS);

// interceptors = [экземпляр HttpInterceptorService1, экземпляр HttpInterceptorService2]

Регистрация providedIn

Такой способ даёт возможность зависимости зарегистрировать саму себя. Зависимость может зарегистрировать себя либо в виде сервиса, помеченного декоратором @Injectable,либо при определении токена InjectionToken.

Таким способом можно зарегистрировать зависимость на уровнях:

• 'platform'

• 'root'

• 'any'

• или указать конкретный тип для регистрации, например, компонент или модуль

@Injectable({providedIn: 'root'})
export class OptionsService { } 

@Injectable({ providedIn: AppModule })
export class OptionsService { } 

@Injectable({ providedIn: 'any' })
export class OptionsService { }

'any' является особым уровнем регистрации. Этот уровень позволяет создавать отдельный экземпляр зависимости для каждого «лениво загружаемого модуля» (lazy-loaded module)

 Обязательно при регистрации токена необходимо указать фабрику

export const API_URL_MY_TOKEN = new InjectionToken<string>('API_URL_MY_TOKEN',
  {
    providedIn: 'root',
    factory: () => 'http://localhost/test:5000'
  });

Управление доступом «Внедрения зависимостей» занимаются специальные декораторы 

• @Self()

 Этот декоратор будет брать зависимость только этого же компонента/директивы/модуля, в котором требуется получить зависимость. 

@Component({
        selector: 'car-di',
        template: ``
  // На уровне компонента
  providers: [OptionsService]
})
export class CarComponent
{
  constructor(@Self() public options: OptionsService){}
}

Если зависимость не будет зарегистрирована в этом же компоненте, то получим ошибку.

• @Optional()

export class CarComponent
{
  constructor(@Optional() public options: OptionsService)
  {
  }
}

Если зависимость OptionsService не найдена, то options === null никаких ошибок сгенерировано не будет. Так же этот декоратор можно применять с любыми другими декораторами уровня доступа.

• @SkipSelf()

Этот декоратор пропускает зарегистрированную зависимость у самого компонента и ищет зависимость выше по иерархии.

export class CarComponent
{
  constructor(@SkipSelf() public options: OptionsService)
  {
  }
}

• @Host()

@Directive({ selector: '[ad-car]' })
export class CarDirective
{
  constructor(@Host() public options: OptionsService)
  {
  }
}

Специально пример с декоратором, чтобы пояснить чем отличается от @Self().

@Host() указывает, что искать нужно у родительского компонента

Хотелось бы добавить из своего опыта то, что специализированные декораторы применяются редко, сам чаще всего применяю декоратор @Optional. Но возможность иметь полный контроль добавляет плюсов в копилку Angular.

В качестве постскриптума. Механизм «Внедрения зависимостей» в Angular достаточно объёмный, но если разобраться — ничего сложного в нём нет. В этой статье показаны все варианты регистрации и внедрения зависимостей, приведены примеры кода, которые надеюсь раскроют принципы «Внедрения зависимостей». Если возникли вопросы — задавайте в комментариях.