Telegram Bot на Kotlin: Командуем

Предудыщая часть: Telegram Bot на Kotlin: Введение

Это промежуточная часть туториала о том, как можно создавать телеграм ботов на базе библиотек plagubot и tgbotapi. Конкретно в данной получасти речь пойдет про достаточно простой по-сравнению с планируемыми плагин для регистрации команд на старте и их установке/очистке далее в рантайме.

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

Оглавление

• Введение

• Командуем

• Дратути

• ... и в продакшн

• Шпаргалка

Итак, задача

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

• BotCommandScope

• LanguageCode (в идеале с возможностью использовать весь спектр ietf кодов)

Базовое решение

Поскольку нам нужно на старте откуда-то брать команды, которые бот ставит изначально, самым простым вариантом будет использование DI для получения всех команд от других плагинов и частей приложения. При этом в этих самых других плагинах и частях приложения достаточно будет зарегистрировать команду с привязкой к нужному типу и рандомным идентификатором (чтобы DI не ругался на конфликт типов):

// Примерно так мы будем забирать команды внутри плагина с командами
koin.getAll<CommandType>().distinct()...
// А так команды будут укладываться в DI в других плагинах
single(named(uuid4().toString())) { /* Creating of CommandType */ }

Кроме того, нужно будет обеспечить возможность добавлять/убирать текущие команды бота. Для этого можно будет использовать какой-то простой set/unset интерфейс вроде:

interface CommandsKeeper {
  suspend fun addCommand(command: CommandType)
  suspend fun removeCommand(command: CommandType)
}

Ну и последнее - сам плагин. По-сути, на старте он должен собирать все команды, зарегистрированные в DI , самостоятельно класть их в CommandsKeeper и как-то слушать изменения команд и их обновлять.

Кусочки пазла

Поскольку в самой Telegram Bot API нет сущности, которая содержала бы сразу и команду с описанием, и её скоуп, и код языка, такую сущность нам придётся сделать самим. По понятным причинам, это будет достаточно простой дата класс с тремя полями:

data class BotCommandFullInfo(
    val command: BotCommand,
    val scope: BotCommandScope = BotCommandScope.Default,
    val languageCode: String? = null
) {
    val key: Pair<BotCommandScope, String?>? = if (scope == BotCommandScope.Default && languageCode == null) {
      	null
    } else {
      	Pair(scope, languageCode)
    }
}

Для CommandsKeeper'а можно сделать простейшую реализацию на базе мапы, в которой ключами будет контекст набора команд - command scope и language code. Пример базовой реализации на основании интерфейса, представленного выше:

class CommandsKeeper(
    // Получаем в конструкторе команды для установки на старте
    val preset: List<BotCommandFullInfo>
) {
    // Этот Flow можно будет использовать для получения обновлений набора команд для каждого ключевого набора
    internal val onScopeChanged = MutableSharedFlow<Pair<BotCommandScope, String?>?>()

    // Тут можно почитать про groupBy: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/group-by.html
    // Создаёт мапу с ключами из scope и languageCode и значениями - списками команд с этими ключами
    private val scopesCommands: MutableMap<Pair<BotCommandScope, String?>?, MutableSet<BotCommand>> = preset.groupBy {
        it.key
    }.mapValues { (_, v) -> // Заменяем значения в мапе
        // Создаём список команд, доставая их из BotCommandFullInfo и превращаем в set для исключения повторений
        v.map { it.command }.toMutableSet()
    }.toMutableMap() // Превращаем в изменяемую мапу

    // Этот Mutex будет использоваться для исключения параллельного доступа к scopesCommands
    private val mutationsMutext = Mutex()

    // Включение информации о команде
    suspend fun addCommand (command: BotCommandFullInfo) {
        val added = mutationsMutex.withLock { // Блокируем изменение набора команд
            // Получаем существующий сет по ключу ЛИБО создаем новый сет, кладем его в мапу и используем этот сет
            val set = scopesCommands.getOrPut(command.key) { mutableSetOf() }
            // Добавляем команду в сет, add возвращает boolean
            set.add(command.command)
        }
        if (added) {
            // Уведомляем об изменении набора команд для ключа
            onScopeChanged.emit(command.key)
        }
    }

    suspend fun removeCommand (command: BotCommandFullInfo) {
        val removed = mutationsMutex.withLock { // Блокируем изменение набора команд
            // Получаем существующий сет по ключу
            // ЛИБО считаем, что команду нельзя удалить и возвращаем из withLock false,
            // который будет установлен в переменную removed
            val set = scopesCommands.get(command.key) ?: return@withLock false
            // Убираем команду из сета, remove возвращает boolean
            set.remove(command.command)
        }
        if (removed) {
            // Уведомляем об изменении набора команд для ключа
            onScopeChanged.emit(command.key)
        }
    }

		internal fun getKeys(): List<Pair<BotCommandScope, String?>?> {
        // Возвращаем ключи
        return scopesCommands.keys.toList()
    }

    internal fun get(key: Pair<BotCommandScope, String?>?): List<BotCommand> {
        // Получаем известные команды, конвертируем в список ЛИБО возвращаем пустой список
        return scopesCommands.get(key) ?.toList() ?: emptyList()
    }
}

По-сути у нас получился достаточно простой по своей сути класс: мы можем добавить (addCommand) или убрать (removeCommand) команду в других плагинах, а внутри проекта командного плагина мы можем получить набор команд для контекста и подписаться на изменения команд. Всё это приправляется синхронизациями в моменты установки/удаления команды

Самый жирный кусочек

Как можно догадаться, самым жирным кусочком на этом пироге будет сам плагин. Тем не менее, по-сути, он очень простой: создание CommandsKeeper и регистрация в DI , установка команд бота в момент начала его установки и их отслеживание во время работы бота. Далее представлен скелет нашего плагина:

@Serializable
object CommandsPlugin : Plugin {
    override fun Module.setupDI(database: Database, params: JsonObject) {}

    override suspend fun BehaviourContext.setupBotPlugin(koin: Koin) {}
}

То есть в плагине у нас на базовом уровне плагину не нужно ничего, кроме переопределения методов плагина. А теперь добавим создание и регистрацию CommandsKeeper в setupDI:

override fun Module.setupDI(database: Database, params: JsonObject) {
    // Регистрируем единственный CommandsKeeper инстанс
    single {
        // Создаем инстанс CommandsKeeperImpl
        CommandsKeeper(
            // Получаем все зарегистрированные экземпляры BotCommandFullInfo и исключаем повторения
          	getAll<BotCommandFullInfo>().distinct()
        )
    }
}

Больше в DI мы ничего регистрировать не будем. Поскольку мы обозначили актуализацию команд в двух местах, а именно при инициализации бота и изменении набора команд, будет уместно выделить установку команд и удаление команд при их отсутствии в отдельную функцию:

private suspend fun BehaviourContext.setScopeCommands(scope: BotCommandScope, languageCode: String?, commands: List<BotCommand>) {
    if (commands.isEmpty()) {
        // Удаляем команды для scope и languageCode
        deleteMyCommands(
            scope,
            languageCode
        )
    } else {
        // Устанавливаем команды для scope и languageCode
        setMyCommands(
            // Берем только уникальные команды и берем первые 100 команд, если их больше
          	commands.distinctBy { it.command }.take(botCommandsLimit.last + 1),
          	scope,
          	languageCode
        )
    }
}

Ну и работа в рамках бота:

override suspend fun BehaviourContext.setupBotPlugin(koin: Koin) {
    // Получаем CommandsKeeper, который регистрировали в DI выше
    val commandsKeeper = koin.get<CommandsKeeper>()

    // Подписываемся на изменения набора команд. it тут - Pair<BotCommandScope, String?>?
    commandsKeeper.onScopeChanged.subscribeSafelyWithoutExceptions(scope) {
      // Получаем набор команд по ключам
      val commands = commandsKeeper.getCommands(it)

      // Устанавливаем команды
      setScopeCommands(it, commands)
    }

    // Получаем известные на момент старта бота ключи (пары scope и languageCode) и для каждого актуализируем набор команд
    commandsKeeper.getKeys().forEach {
      // Получаем набор команд по ключам
      val commands = commandsKeeper.getCommands(it)

      // Устанавливаем команды
      setScopeCommands(it, commands)
    }
}

В целом, это всё :)

Итоги

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