Bot TODOLIST

Это демо-бот, который может работать как чат-бот и как мини-приложение.

1. Установка и запуск бота

1.1. Скачайте репозиторий:

git clone git@github.com:max-messenger/max-bot-example-todolist.git

1.2. В корне проекта запустите локально docker-compose:

docker-compose up -d

1.3. Подготовьте конфигурационный файл — скопируйте его в корень проекта:

cp config/todolist/config.tmpl.yaml .

1.4. Соберите проект:

// Параметр -o определяет название файла.
go build -o todo-app ./cmd/todolist

В результате будет собран исполняемый бинарный файл проекта.

Приложение создаётся через фабрику в файле app.go: возвращается объект fx.App. Менять ничего не нужно, модули добавляются в файле fx.go:

func CreateApp(cfgName string) *fx.App {
    box := gibs.NewBox(
        Modules,
        gibs.WithAppName("todolist"),
        gibs.WithConfigFile(cfgName),
    )

    return box.CreateApp()
}

1.5. Запустите бота:

// Параметр -c указывает файл.
./todo-app -c config.yaml

2. Работа TODOLIST в чате

Бот позволяет планировать дела и работает по принципу «задачника». Для начала работы откройте чат с ботом. Здесь вы можете:

• Вызвать список функций бота — команда /info
• Добавлять записи — команда /create
• Просматривать все добавленные записи — команда /list
• Удалять записи из списка — команда /delete
• Получить свои user_id и chat_id — команда /myid

3. Работа TODOLIST в мини-приложении

Для вызова мини-приложения с планировщиком дел зайдите в чат с ботом и нажмите Открыть. Здесь вы можете:

• В поле ввода напечатать текст и нажать Добавить — добавленная задача отобразится в списке с чекбоксом. Ограничений по количеству задач в списке и количеству символов в одной задаче нет
• Перевести задачу в статус выполненной, установив чекбокс
• Удалить задачу из списка
• Отфильтровать список задач по Выполненным или Невыполненным. По умолчанию задан фильтр Все

В конце списка отображается количество активных задач.

Основные рекомендации по разработке сервисов с использованием TODOLIST смотрите в guidelines

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

Если установка прошла успешно, появится папка internal/app со следующей структурой:

internal/app
├── clients          - клиенты для работы с внешними сервисами (http, grpc, bots)
│   ├── maxbot       - клиент MAX, подключение к боту и получение/отправка сообщений
│   └── fx.go        - модули clients
├── domain           - доменные модели для общения между сервисами
├── repository
│   ├── staterepo    - репозиторий для хранения состояния пользователя
│   ├── todorepo     - репозиторий для хранения todo
│   └── fx.go        - модули repository
├── router           - HTTP API сервиса
│   ├── todolistctrl - контроллер для todolist
│   └── webhookctrl  - контроллер для webhook нужен для получения сообщений из бота в режиме webhook
├── services
│   ├── analytic     - сервис для отправки аналитики в kafka
│   ├── bot          - сервис для обработки сообщений из бота
│   ├── todolist     - сервис для работы с todo
│   └── fx.go        - модули services
└── subscriber       - подписки на события из бота, сюда можно добавлять свои подписки, например из kafka

5. Описание модулей проекта

5.1 Модули по умолчанию

В проекте используются следующие дефолтные модули:

var defaultModules = fx.Options(
    grace.Module, // модуль для запуска приложения в фоне.
    health.Module, // модуль для проверки статуса приложения.
    server.Module, // модуль для запуска сервиса в http.
    info.Module, // модуль для получения информации о приложении.
    telemetry.Module, // модуль для получения метрик в prometheus, otel и профайлинг.
)

HTTP-сервис для проверки статуса приложения и сбора метрик запускается отдельно — по умолчанию на порту 8082.

5.2 Состав модулей в Package

Включает набор модулей для работы приложения, http, grpc-сервер, сбор трейсов и метрик, логи, http middleware, marshaler.

Часть модулей добавлена в проект по умолчанию. Другие модули добавьте в файле internal/app/fx.go:

var Modules = fx.Options(
    //.....
    moduleName.Module, 
    //.....
)

Модифицировать код внутри pkg не надо. Если требуются доработки, обращайтесь к мейнтейнеру.

Background Tasker(bgtasker)

Модуль для запуска фоновых задач в приложении.

Grace

Модуль для управления жизненным циклом сервисов с поддержкой graceful shutdown. Есть в шаблоне проекта.

HTTP

Модуль для работы с http-сервисами. В основном это набор middleware для запуска сервисов в http.

Health

Модуль для получения информации о состоянии приложения. Есть в шаблоне проекта, работает на системном порту /health.

Info

Модуль для получения информации о приложении через HTTP endpoint. Есть в шаблоне проекта, работает на системном порту /info.

Telemetry

Модуль для настройки отправки трейсов, а также хелперов для сбора метрик. Есть в шаблоне проекта.

Server

Модуль для запуска сервисов в http и grpc. По умолчанию включены сервисы для обработки запросов информации о приложении и метрик. Есть в шаблоне проекта.

RateLimiter

Модуль для работы с лимитером на основе кеша и redis. Подключить можно через fx.

5.2.1 Состав модулей Connections

Набор модулей для работы с различными базами данных и сервисами, postgres, redis cluster, kafka, grpc.

Каждый модуль подключается через fx.

GRPC Clients

Модуль для работы с grpc-клиентами, реализованный через модель пулов, где для каждого коннекта предусмотрен свой конфиг и объект grpc-клиента.

Kafka

Модуль для работы с kafka, реализованный через модель пулов, где для каждого коннекта предусмотрен свой конфиг.

Redis

Модуль для работы с redis, реализованный через модель пулов, где для каждого коннекта предусмотрен свой конфиг и объект universal redis клиента.

Postgres

Модуль для работы с postgres, реализованный через модель пулов, где для каждого коннекта предусмотрен свой конфиг и объект postgres-клиента.