Зависимости

Разрабатывать сложные проекты со множеством тем, справочников и скриптовых расширений может быть неудобно и неэффективно, если хранить весь код проекта в одном сценарии. Вместо этого JAICP позволяет разбивать код сценария на изолированные составные части и подключать их в основной сценарий как зависимости. Такой подход имеет ряд преимуществ:

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

Зависимости можно подключить двумя способами:

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

подсказка

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

Локальные модули

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

Конфигурация

Зависимости указываются в разделе dependencies конфигурационного файла chatbot.yaml. Для локальных модулей должны быть указаны поля:

Поле	Описание	Значение
`name`	Имя, по которому зависимость подключается в сценарий	Название директории зависимости
`type`	Тип зависимости	`module`

Структура проекта

Предположим, что имеется существующий проект, состоящий из двух файлов:

main.sc — основной сценарий.
offtopic.sc — «болталка» бота: ответы на часто задаваемые вопросы не по теме.

Пример файла offtopic.sc:

patterns:
    $you = (~ты/~вы)

theme: /

    state: WhatCanYouDo
        q!: * {~что * [$you] * (~уметь/научил*/способ*)} *
        q!: * ([~что] $you/что-то) [еще] * (уме*/мож*/научил*/способ*) [делать] *
        q!: * как* * $you * [поставлен*/установлен*] (сервис*/программ*) *
        a: Я умею отвечать на вопросы.

Структура директории проекта имеет следующий вид:

├── chatbot.yaml
├── src
│   ├── main.sc
│   └── offtopic.sc
└── test
    └── test.xml

Если «болталку» планируется расширять новой функциональностью, например специализированной темой о вымышленной биографии бота или своими функциями для обработки данных, целесообразно вынести ее в отдельный модуль, независимый от основного сценария.

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

├── main
│   ├── chatbot.yaml
│   ├── src
│   │   └── main.sc
│   └── test
│       └── test.xml
└── offtopic
    └── src
        └── offtopic.sc

подсказка

В зависимостях не требуется наличие конфигурационного файла chatbot.yaml и XML-тестов.

Подключение зависимости

Перейдите в меню редактирования проекта. На вкладке Размещение смените значение поля Путь на название новой корневой директории проекта — main.

предупреждение

Если поле Путь не отображается на вкладке, обратитесь к своему аккаунт-менеджеру.

Укажите в chatbot.yaml раздел dependencies, если его еще нет. Добавьте зависимость с типом module и именем, соответствующим названию новой директории:
```
dependencies:
  - name: offtopic
    type: module
```

В файле main.sc импортируйте нужный файл из зависимости при помощи тега require:

require: offtopic.sc
    module = offtopic

theme: /

    state: You
        q!: * $you *
        a: Я понял, что вы ко мне обратились, но не понял, зачем.

    state: CatchAll
        q!: *
        a: Извините, я вас не понял.

Теперь в основном сценарии доступно содержимое подключенного файла: стейт WhatCanYouDo и именованный паттерн $you.

Внешние зависимости

Если модуль содержит типовую функциональность, которая может потребоваться во множестве разных проектов, ее целесообразно вынести в отдельный Git-репозиторий. Далее такой модуль можно переиспользовать, подключив его в нужный проект как внешнюю зависимость. Например, в такие зависимости могут быть вынесены готовые фрагменты сценариев, часто используемые функции и справочники.

Конфигурация

Зависимости указываются в разделе dependencies конфигурационного файла chatbot.yaml. Для внешних зависимостей должны быть указаны поля:

Поле	Описание	Значение
`name`	Имя, по которому зависимость подключается в сценарий	Произвольная строка
`type`	Тип зависимости	`git`
`url`	Адрес внешнего репозитория	Строка, начинающаяся с `https://`, `git://` или `file://`
`version`	Название нужной ветки в репозитории	`<имя_ветки>` или `heads/<имя_ветки>`
`loginSecretKey`	Логин от учетной записи с доступом к репозиторию	Название токена, где хранится значение `loginSecretKey`
`tokenSecretKey`	Персональный токен для доступа к репозиторию	Название токена, где хранится значение `tokenSecretKey`

осторожно

Поля loginSecretKey и tokenSecretKey нужны только в том случае, если зависимость размещена в приватном репозитории. Также учитывайте следующие требования:

В качестве значения tokenSecretKey нельзя использовать пароль от учетной записи. Вместо него вам нужно выпустить персональный токен с доступом на чтение нужного репозитория. Подробнее о том, как получить токен в Bitbucket, GitHub и GitLab.
Для безопасности ваших данных ни логин, ни токен нельзя записывать непосредственно в chatbot.yaml. Вместо этого их нужно хранить в хранилище токенов JAICP. В качестве значений loginSecretKey и tokenSecretKey используйте названия токенов, где хранятся нужные значения.

Структура проекта

Рассмотрим пример файла offtopic.sc, приведенный выше.

Создайте директорию под новый репозиторий.
В ней создайте поддиректорию src, в которую поместите offtopic.sc:
```
└── src
    └── offtopic.sc
```
Создайте в корневой директории Git-репозиторий и зафиксируйте изменения.
Опубликуйте репозиторий на любом внешнем хостинге, например Bitbucket, GitHub или GitLab.

Подключение зависимости

Если репозиторий с кодом зависимости приватный, перейдите в раздел Токены и переменные и создайте два токена под логин и персональный токен: например, GITHUB_LOGIN_SECRET и GITHUB_TOKEN_SECRET.

Укажите в chatbot.yaml раздел dependencies, если его еще нет. Добавьте зависимость с типом git и параметрами подключения к репозиторию:

dependencies:
  - name: offtopic
    type: git
    url: https://github.com/example/offtopic
    version: master
    # Если репозиторий приватный:
    loginSecretKey: GITHUB_LOGIN_SECRET
    tokenSecretKey: GITHUB_TOKEN_SECRET

В файле main.sc импортируйте нужный файл из зависимости при помощи тега require:
```
require: offtopic.sc
    module = offtopic
```

Теперь в основном сценарии доступно содержимое подключенного файла.

подсказка

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

Зависимости

Локальные модули​

Конфигурация​

Структура проекта​

Подключение зависимости​

Внешние зависимости​

Конфигурация​

Структура проекта​

Подключение зависимости​

Локальные модули

Конфигурация

Структура проекта

Подключение зависимости

Внешние зависимости

Конфигурация

Структура проекта

Подключение зависимости