Бот на Go в MAX: документация учит языку, примеры не собираются

Учебник внутри инструкции: страница объясняет сам язык

Страница называется «Настройка сценариев работы бота с помощью библиотеки Golang» и открывается рекомендацией: «рекомендуем использовать нашу официальную библиотеку MAX Bot API». Дальше читателя ждёт не справочник по методам мессенджера, а вводный курс: что делает команда go mod init, как устроен файл go.mod, зачем каждому файлу ключевое слово package.

Для продуктовой документации это редкий жанр: соседние страницы того же раздела рассказывают про API мессенджера, а эта — про устройство чужого языка программирования. Заканчивается урок бодро: «Поздравляем, вы написали первого бота!» Проблема в том, что два из трёх примеров с этой страницы не собираются.

Три примера кода — собирается один

На странице три блока кода на Go и два на Bash. Судьба каждого из трёх:

• Первый — классический hello world: пакет main, импорт "fmt", одна строка вывода. Собирается и работает.
• Второй создаёт объект API: maxbot.New(os.Getenv("TOKEN")). В импортах при этом только "fmt" и сама библиотека — пакета "os" нет, и компилятор Go останавливается на первом же os.Getenv с ошибкой «undefined: os». Мы проверили всю страницу: вызовов os.Getenv на ней два, строки "os" в импортах — ноль.
• Третий, финальный, добавляет обработчик обновлений — и вместе с ним context.WithCancel, os.Signal, signal.Notify и тип schemes.MessageCreatedUpdate. Ни один из четырёх пакетов не импортирован. Бонус — комментарий, оборванный на полуслове: // создам. Что именно автор собирался создать, история умалчивает.

Команда запуска тоже не доведена: пример предлагает выполнить go run — и всё. Без имени файла или точки в конце инструмент Go откажется работать: ему не сказали, что запускать.

Невидимая опечатка в имени языка

Дважды страница называет язык словом, в котором первая буква — латинская G, а вторая — кириллическая «о». На экране такое слово неотличимо от честного латинского Go, но для поиска это два разных слова: браузерный поиск по латинскому «Go» оба гибридных вхождения пропустит. Для сравнения: полностью латинское написание Go встречается на странице четыре раза — то есть треть упоминаний имени языка набрана со скрытой кириллицей.

Это продолжение знакомой семьи опечаток dev.max.ru: мы уже находили в документации латинские буквы внутри русских слов. Здесь зеркальный случай — кириллица внутри английского слова, и заметить её без побуквенной проверки невозможно.

Репозиторий живёт — но другой версией

Сама библиотека при этом никак не заслуживает упрёков. Официальный репозиторий max-messenger/max-bot-api-client-go на GitHub жив и ухожен: 88 звёзд, ноль открытых issues, последний пуш — 7 августа 2026 года, за считаные дни до наших замеров. Страница документации честно говорит: «Расширенную версию библиотеки с примерами реализации смотрите на GitHub» — и это единственная её рекомендация, которая работает без оговорок.

Но между страницей и репозиторием пролегла мажорная версия. Ветка репозитория по умолчанию называется v2, и образцовый пример импортирует модуль по пути max-bot-api-client-go/v2. Документация же ставит библиотеку командой go get github.com/max-messenger/max-bot-api-client-go — без суффикса /v2. В мире модулей Go это не мелочь: путь без /v2 приводит другую мажорную версию пакета, со старыми сигнатурами.

Разница видна прямо в коде. На странице конструктор называется New и возвращает одно значение: api := maxbot.New(os.Getenv("TOKEN")). В примере из репозитория у конструктора другое имя и два результата: api, err := maxbot.NewApi(os.Getenv("BOT_TOKEN"), opts...). Даже переменная окружения с токеном называется по-разному — BOT_TOKEN вместо TOKEN. Скопировать пример со страницы и «долечить» его импортами недостаточно: с библиотекой v2 он всё равно не совпадёт по интерфейсу.

README спорит с документацией о рождении бота

README репозитория вежлив к новичкам: «Если вы новичок, то можете прочитать официальную документацию, написанную разработчиками Max». Но собственный «Быстрый старт» он излагает по-своему: откройте диалог с MasterBot, «следуйте инструкциям и создайте нового бота», и «После создания бота MasterBot отправит вам токен».

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

Мелкий, но характерный штрих: ссылка «Документация» в README ведёт в ветку master — при том что веткой по умолчанию репозиторий назначил v2.

В чём все согласны: токен — в переменные окружения

Единственный пункт, где страница, README и пример репозитория говорят в один голос, — обращение с токеном. Документация формулирует прямо: «Мы рекомендуем передавать токен через переменные окружения», потому что «использовать токен в коде — плохая практика». Пример репозитория так и устроен, README отдаёт выдачу токена мастер-боту — в код секрет не попадает нигде.

Пользовательской справки всё это не касается вовсе: из её 192 статей слово «библиотека» не встречается ни в одной, как и «Golang», как и «компилировать». Справка описывает ботов глазами пользователя — например, как вести групповые чаты, — а вся разработка целиком живёт на dev.max.ru. Тем важнее, чтобы эта единственная точка входа собиралась без ошибок.

Частые вопросы