Установка: kafka-go и локальный брокер

Установка kafka-go выглядит стандартно для Go-модулей: создаём модуль командой go mod init и добавляем зависимость github.com/segmentio/kafka-go через go get — импорт-путь совпадает с репозиторием, никаких спецдвижений. Библиотека написана на чистом Go: внутри нет ни строчки cgo, поэтому сборка не требует GCC и системных заголовков, кросс-компиляция из macOS в Linux работает из коробки, а итоговый бинарник — обычный статичный файл, как у любого сервиса на стандартной библиотеке. Это не мелочь: альтернативный клиент confluent-kafka-go тянет за собой C-библиотеку librdkafka, и его сборка в Alpine-образе превращается в отдельный проект. Версия фиксируется в go.mod как обычно; библиотека живёт по классическому тегированию v1 и спокойно обновляется между минорами. Если рядом в проекте уже лежат модули из курсов по базовому Go, ничего перенастраивать не нужно — kafka-go встанет в тот же go.mod и тот же кэш модулей. Проверка сборки проста: импортируйте пакет в любой файл и выполните go build — компилятор подтянет модуль и честно покажет ошибку, если версия не сошлась. Всё это делает kafka-go особенно удобной для CI: сборка тестового образа не тянет ни C-инструментарий, ни системных зависимостей.

Современный Kafka не требует ZooKeeper: со версии 2.8 доступен режим KRaft, где кворум метаданных живёт внутри самих брокеров, а с третьей версии он стал основным путём. Для разработки берём single-node конфиг: один контейнер одновременно и брокер, и контроллер. Минимальный docker-compose.yml для образа bitnami/kafka выглядит так, как в блоке ниже, и в нём важно понимать три переменные. PROCESS_ROLES и CONTROLLER_QUORUM_VOTERS включают KRaft-режим для одиночного узла. LISTENERS описывает, на каких портах брокер принимает соединения: 9092 — клиентский, 9093 — внутренний для контроллера. А ADVERTISED_LISTENERS — адрес, который брокер сообщает клиентам в ответе «я здесь»: если написать там имя контейнера, ваш Go-код с хоста получит недостижимый адрес — классическая ловушка, ниже отдельный коллаут. Тома наружу выносим и порт 9092; данные живут в именованном томе kafka_data, поэтому рестарты и пересоздание контейнера учебный топик не стирают. Файл целиком копируется в проект без правок: все переменные обязательны, и их сокращение — самый быстрый способ получить брокер, который поднимается, но не отвечает.

Топик в Kafka не создаётся автоматически первой записью — по умолчанию брокер отвечает ошибкой на запись в несуществующий канал, и это осознанная защита от опечаток. Создать топик можно двумя путями. Первый — консольная утилита kafka-topics.sh внутри контейнера: она нужна один раз, чтобы поднять топик orders с тремя партициями и фактором репликации 1. Второй — из кода, и это то, что делают сервисы при старте: kafka-go открывает Admin API через структуру kafka.Client с адресом кластера в поле Addr, а создание топиков — её метод CreateTopics. Он принимает контекст и CreateTopicsRequest со срезом TopicConfig; в каждом конфиге важны три поля: имя, NumPartitions и ReplicationFactor — для локального брокера реплика всегда одна, потому что брокер один. Полное управление топиками из Go — конфиги, изменение числа партиций, удаление — отдельный урок про Admin API, а здесь Client.CreateTopics выполняет роль init-миграции: сервис стартует, гарантирует нужный топик и работает дальше. В командной работе создание топиков обычно выносят в скрипт деплоя, чтобы код и инфраструктура не спорили, кто автор канала. В учебном проекте проще держать клиента и запрос в main.go перед стартом продюсера: против чистого брокера сервис сам себя готовит, а против уже настроенного просто повторяет знание о топике.

Прежде чем писать Go-код, стоит убедиться, что канал жив, — и для этого в образе есть консольные утилиты, которые сами же и пригодятся при отладке весь курс. kafka-console-producer.sh читает строки из стандартного ввода и отправляет каждую как сообщение: набрали текст, нажали Enter — уехало. kafka-console-consumer.sh с флагом --from-beginning вычитывает топик с самого старого живого оффсета и печатает сообщения в терминал, оставаясь висеть и показывать новые. Запустив оба в двух терминалах, вы увидите круговорот: строка ушла из продюсера — появилась у консьюмера. Эта пара — быстрее любой диагностики: если консольные утилиты внутри контейнера ходят, а Go-код нет, проблема в адресе с хоста, то есть в advertised listeners; если и консоль молчит, смотрите, жив ли контейнер и существует ли топик. Утилиты принимают те же --bootstrap-server, что и клиент: единственная точка правды — адрес брокера. Оба инструмента живут в том же образе, что и брокер, поэтому работают даже там, где нет ни Go, ни вашего кода: удобно проверять окружение до репродукции бага. Если консьюмер печатает ваши строки — канал исправен, и любую следующую проблему стоит искать в коде, а не в окружении.

Код этого курса — сетевой по определению, и честная оговорка будет звучать одинаково в каждом уроке: песочница сайта не умеет сеть и TCP-сокеты, поэтому kafka-код запускается локально против брокера в Docker, а интерактивы песочницы показывают тематические программы на чистом Go, обычно эмулирующие нужную механику — от хэша ключа до батчей. Такой формат не потеря: механики партиционирования и адресации удобнее щупать интерактивами, а ход сообщений в живом брокере — это десять минут подъёма окружения один раз. С этого урока у вас есть всё: клиент в go.mod, брокер на localhost:9092, топик с тремя партициями и утилиты, чтобы заглянуть внутрь в любую секунду. Дальше каждый урок будет давать код, который стоит против этой площадки: скопировали — запустили — увидели своими глазами. Именно на этом цикле Kafka перестаёт быть набором терминов и становится инструментом, который вы читаете и отлаживаете без страха. К этому же уроку стоит вернуться при смене машины: чек-лист выше — самодостаточная инструкция восстановления окружения за пять минут.