.. _root_dependency_injection:

Внедрение зависимостей
=======================

Внедрение зависимостей (Dependency Injection, DI) — это паттерн проектирования, который помогает писать слабосвязанный, легко тестируемый и расширяемый код. Вместо того чтобы хендлеры сами создавали нужные им объекты (зависимости) они лишь объявляют о необходимости в их получении, а ``Argenta`` "внедряет" их в хендлеры в момент вызова.

``Argenta`` использует популярную библиотеку ``dishka`` для реализации DI, что позволяет вам декларативно объявлять зависимости прямо в сигнатурах ваших хендлеров.
Более подробно про ``DI``, ``IoC``, ``API`` создания провайдеров и другое вы можете прочитать тут_.

.. _тут : https://dishka.readthedocs.io/en/stable/di_intro.html

Основная идея
-------------

Представьте, что вашему хендлеру для работы нужен доступ к базе данных. Вместо того чтобы импортировать и инициализировать соединение внутри функции, вы просто объявляете его как аргумент с тайп-хинтом:

.. note::
   ``argenta.di.FromDishka`` это алиас к ``dishka.FromDishka``, они полностью взаимозаменяемы.

.. literalinclude:: ../code_snippets/dependency_injection_example_sample.py
   :language: python
   :linenos:

``Argenta`` -> ``dishka`` зарезолвит тайпхинты и внедрит зависимость с возвращаемым типом ``Connection``, прежде чем использовать зависимость её нужно создать, для этого нужно создать соответствующий провайдер.

.. literalinclude:: ../code_snippets/dependency_injection_example_sample2.py
   :language: python
   :linenos:
   
После создания провайдера, его нужно зарегистрировать в оркестраторе.

.. literalinclude:: ../code_snippets/dependency_injection_example_sample3.py
   :language: python
   :linenos:

Как это работает?
-----------------

В основе DI в Argente лежат **провайдеры** и **контейнер**.

*   **Провайдер (Provider)** — это "рецепт", который объясняет, как создавать и настраивать ту или иную зависимость (например, подключение к БД, API-клиент или любой другой сервис).
*   **Контейнер (IoC Container)** — это "фабрика", которая хранит все рецепты (провайдеры) и по запросу создаёт и выдаёт готовые зависимости.

Встроенные провайдеры
-----------------------

``Argenta`` поставляется с предопределённым провайдером, который даёт доступ к важным системным зависимостям без какой-либо настройки. К примеру вы можете получить объект ``ArgSpace``, который представляет из себя распаршенные аргументы командной строки при запуске приложения.

Краткий сэмпл кода, который получает объект ``ArgSpace`` и выводит в консоль аргумент с именем "type":

.. literalinclude:: ../code_snippets/dependency_injection_example_sample4.py
   :language: python
   :linenos:

Обмен данными между хендлерами
------------------------------

Помимо DI, хендлеры могут общаться друг с другом в контексте приложения через **объект контекста** (в ``Argenta`` эту роль выполняет объект ``Response``).

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

.. seealso::

   Подробнее об этом можно прочитать в разделе :ref:`root_api_response`.