go generate: польза, прозрачность

1. Введение

Если вы когда-нибудь писали одно и то же два раза, вы уже на пути к генерации кода. Обычно это начинается невинно: «ну сейчас я быстренько сделаю String() на switch», потом появляется второй enum, потом третий, потом вы переименовали значение, забыли обновить строку, и вот у вас баг, который очень сложно найти, потому что он выглядит как «просто неправильный текст». В этот момент вы начинаете понимать, что ручной boilerplate — это не геройство, а технический долг, замаскированный под продуктивность.

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

И сразу важная мысль дня: генерация — это не «магия», а просто автоматизация скучных повторов. Если генерация начинает менять смысл программы в зависимости от фазы луны и текущего времени — это уже не генерация, а сюжет для хоррора.

2. Как работает go generate

Важно понимать механику без мистики: go generate сканирует исходники Go и ищет строки-комментарии специального формата. Для каждой найденной директивы он запускает указанную команду. При этом go generate — это не часть go build, он ничего не «догонит сам» и не делает анализ зависимостей. Его нужно запускать явно, когда вы решили обновить сгенерированные файлы.

Это разделяет мир на две понятные фазы: «я изменил входные данные» и «я запустил генерацию, получил обновлённый результат». Такой подход в Go выбран специально: чтобы сборка оставалась предсказуемой и быстрой, а генерация — осознанной.

Чтобы картина была совсем ясной, представьте типичный цикл работы как схему:

flowchart TD
    A[Правим исходники: enum, теги, схемы] --> B[Запускаем go generate]
    B --> C[Обновились *_gen.go / *_string.go]
    C --> D[go test]
    D --> E[Коммит: исходники + сгенерированные файлы]

И ещё один принципиальный момент: go generate задуман прежде всего для автора пакета, а не для пользователя вашей библиотеки. Поэтому сгенерированные файлы обычно коммитят в репозиторий, чтобы клиенту не нужно было иметь все генераторы у себя.

Директива //go:generate

С директивами у Go подход простой: чтобы строка считалась директивой, она должна начинаться ровно с //go:generate — без пробела после //. Если написать // go:generate, вы просто оставите комментарий «для будущих археологов», а команда не запустится. Этот строгий формат — часть идеи «никакой магии»: либо директива распознана однозначно, либо нет.

Обычно директиву размещают рядом с тем местом, ради которого генерация нужна. Не «в каком-то отдельном файле генерации на 300 строк», а прямо возле типа, констант или структуры, которые являются источником правды. Тогда читатель видит: вот тип, вот константы, вот команда, которая генерирует поддержку.

Мини-пример «как выглядит директива» (пока без привязки к нашему проекту):

package todo

//go:generate stringer -type=Status
type Status int

Команда, которую вы укажете после //go:generate, запускается как внешняя программа. Часто это один из трёх вариантов: отдельная утилита (например, stringer), go run ./internal/... для запуска вашего генератора, или что-то вроде goyacc для генерации парсеров. Сам факт, что Go не ограничивает вас одной-единственной утилитой, и делает go generate универсальным.

Запускать генерацию можно точечно (в текущем пакете) или рекурсивно по проекту. На практике обычно используют одну из команд: go generate (текущая папка) или go generate ./... (все пакеты рекурсивно). В этой лекции мы держим в голове второй вариант как «обновить всё».

3. Пример: Status и генерация String() через stringer

Сейчас соберём кусочек нашего учебного приложения (пакет todo) так, чтобы он был максимально жизненным: у задачи есть статус, и нам хочется печатать этот статус по-человечески. Можно, конечно, всегда печатать числа… но тогда ваш CLI будет выглядеть как бухгалтерия на минималках.

Начнём с простого Status на базе int и набора констант через iota:

package todo

// Status describes the lifecycle state of a task.
type Status int

const (
	StatusUnknown Status = iota
	StatusOpen
	StatusDone
)

Теперь наивный путь: написать метод String() руками. Это честно, работает, и на первых порах даже полезно, чтобы понять механику:

package todo

import "fmt"

// String returns a human-readable status name.
func (s Status) String() string {
	switch s {
	case StatusOpen:
		return "open"
	case StatusDone:
		return "done"
	default:
		return fmt.Sprintf("Status(%d)", s)
	}
}

Проблема здесь не в том, что код плохой. Проблема в том, что он быстро перестаёт быть «одним разом»: добавили StatusArchived, переименовали StatusOpen в StatusActive, поменяли порядок — и вы обязаны помнить, что String() нужно обновить синхронно. И вот тут генерация — идеальный инструмент: это механическая работа, которую компьютер сделает стабильнее вас.

Подключаем stringer через go generate

У Go есть популярная утилита stringer (из репозитория golang.org/x/tools), которая как раз генерирует String() для наборов целочисленных констант. Важно: stringer не часть стандартной библиотеки, но он «родной по духу» и широко используется.

Добавим директиву рядом с типом:

package todo

//go:generate stringer -type=Status

type Status int

const (
	StatusUnknown Status = iota
	StatusOpen
	StatusDone
)

Теперь, когда вы выполните go generate в этом пакете, stringer создаст файл (обычно с суффиксом _string.go) со сгенерированным методом String().

Проверяем эффект в маленьком коде

Чтобы почувствовать пользу, давайте сделаем мини-фрагмент, который печатает статус. Это может быть кусочек main вашего CLI или просто временный эксперимент:

package main

import (
	"fmt"

	"example.com/todoapp/todo"
)

func main() {
	st := todo.StatusDone
	fmt.Println(st) // StatusDone (после генерации stringer)
}

До генерации fmt.Println(st) печатал бы число (2), если String() нет. После генерации fmt увидит метод String() и выведет строку. И да, это тот случай, когда «красивый вывод» — не косметика, а удобство отладки и UX.

4. Как жить со сгенерированными файлами

Когда генератор создаёт файл, он обычно добавляет в шапку предупреждение вида Code generated ... DO NOT EDIT.. Это не угроза, а забота о вашей психике: чтобы вы не потратили час на правку файла, который через минуту будет перегенерирован и перезаписан. В примере с stringer это считается хорошим тоном: сгенерированный файл начинается с такой строки.

Выглядеть это может примерно так (упрощённо, чтобы не утонуть в деталях реализации stringer):

// Code generated by stringer -type=Status; DO NOT EDIT.

package todo

func (s Status) String() string {
	// ... generated mapping ...
	return ""
}

Теперь про главный организационный момент: что делать с этим файлом в git? В Go принято хранить сгенерированные файлы рядом с исходниками, если они нужны для сборки или использования пакета, потому что клиент вашего пакета не обязан уметь запускать ваши генераторы. Это делает проект менее «хрупким»: сборка зависит от исходников и уже сгенерированного результата, а не от наличия инструментов на машине пользователя.

Отсюда вытекает требование детерминированности: если два разработчика запустят go generate на одной и той же версии исходников, результат должен быть одинаковым. Иначе git-дифф превращается в шум, а команда — в клуб «у кого сегодня получилось».

Практически детерминированность обычно ломают три вещи: генерация, зависящая от текущего времени; генерация, зависящая от случайности; генерация, зависящая от окружения (пути, локаль, версии утилит). Поэтому «здоровая» генерация старается быть максимально чистой: одинаковый вход → одинаковый выход.

5. Как не сделать проект «магическим»

Самая частая беда с go generate не техническая, а организационная: вы добавили генерацию, всё работало, а через месяц никто не помнит, что её нужно запускать, какой версией инструмента, и почему у вас вообще появился файл something_gen.go, который нельзя трогать. Чтобы этого не случилось, нужно соблюдать несколько простых правил, которые звучат скучно, но спасают проект от «паранормальных явлений».

Первое правило — генерация должна быть явной и не притворяться частью сборки. Это философия go generate как команды: она специально не встроена в go build. Тогда у вас всегда есть понятный вопрос: «ты запускал генерацию?» — и понятный ответ: «да/нет».

Второе правило — команда генерации должна быть видна в коде, рядом с источником данных. Именно поэтому директива размещается рядом с Status, а не «где-то в папке scripts». Когда вы читаете тип, вы сразу видите «ага, тут stringer, значит String() генерируется».

Третье правило — генерация должна обслуживать то, что действительно механическое. String() для enum — отличный пример: оно не добавляет бизнес-смысл, оно просто избавляет вас от рутины и синхронизации строк с константами.

Четвёртое правило — документируйте запуск генерации там, где люди реально смотрят. Обычно это README и/или doc.go. Если в пакете есть генерация, в README проекта вполне уместна короткая секция «Development», где сказано: «после изменения статусов выполните go generate ./...».

Пятое правило — держите примеры и тесты на стороне правды. Example-тесты хороши тем, что они не дают документации протухнуть: если вы показываете в примере fmt.Println(StatusDone), то при поломке генерации пример начнёт падать (или хотя бы перестанет соответствовать ожидаемому выводу). Это ровно та идея «документация, которую можно выполнить», ради которой вообще существуют examples.

Вот маленький Example, который можно положить в status_example_test.go и тем самым «прибить гвоздями» ожидания от генерации:

package todo

import "fmt"

func ExampleStatus_String() {
	fmt.Println(StatusDone)
	// Output: StatusDone
}

Да, stringer по умолчанию печатает имя константы (StatusDone), а не "done". И это нормально: генератор делает ровно то, что обещает. Если вам нужно «done/open», это уже отдельная политика отображения (её можно сделать вручную, а stringer оставить для технической отладки). Важно, что пример фиксирует контракт и становится проверяемым.

6. Типичные ошибки при использовании go generate

Ошибка №1: ожидать, что генерация произойдёт «сама при go build».
Это, пожалуй, самая массовая ловушка. После пары дней в Go мозг привыкает: «я написал код — оно собралось». Но go generate специально не встроен в сборку и должен запускаться отдельно, без автоматического анализа зависимостей. Если забыть об этом, вы получите ситуацию «у меня всё работает, а у коллеги не компилируется», потому что у вас локально лежит свежий generated-файл.

Ошибка №2: написать // go:generate и удивляться, почему ничего не происходит.
Директива распознаётся только в строгом формате //go:generate. Никаких «ну вы же поняли, что я имел в виду». Go здесь как компилятор: он не читает мысли, он читает символы. Это неприятно ровно один раз, а потом вы начинаете любить предсказуемость.

Ошибка №3: править сгенерированный файл руками.
Сгенерированный файл часто начинается с «DO NOT EDIT» не из вредности. Если вы поправили его вручную, а потом кто-то запустил go generate, ваша правка исчезнет без следов, как будто её никогда не было. Правильная точка изменений — либо входные данные (enum/константы), либо параметры генератора, либо сам генератор.

Ошибка №4: сделать генерацию недетерминированной.
Если генерация добавляет текущую дату, случайные числа, порядок обхода map или зависимость от локали, вы получите бесконечные диффы и конфликтующие коммиты. Сама идея «скучный код генерирует машина» предполагает повторяемость. В противном случае вы меняете один вид боли на другой, просто более экзотический.

Ошибка №5: спрятать генерацию и оторвать её от смысла.
Когда директива стоит далеко от типа, ради которого она нужна, новый разработчик будет воспринимать генерацию как внезапное природное явление: «в папке есть какой-то файл _string.go, наверное, его принёс ветер». Гораздо лучше держать //go:generate рядом с источником данных (в нашем примере — рядом с Status), чтобы связь читалась глазами.