Зависимости
Разрабатывать сложные проекты со множеством тем, справочников и скриптовых расширений может быть неудобно и неэффективно, если хранить весь код проекта в одном сценарии. Вместо этого 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
Теперь в основном сценарии доступно содержимое подключенного файла.