Метапрограммирование в Go

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

Но задачи, ради которых в других языках существует метапрограммирование, никуда не делись. Сериализовать любую структуру в JSON. Провалидировать поля по описанию. Разложить строку из базы по полям. Сгенерировать мок для интерфейса. Прокинуть конфиг из переменных окружения. Go отвечает на них тремя механизмами с очень разной ценой — плюс двумя аварийными люками для выхода за пределы языка.

Три уровня и порядок выбора

Порядок принципиален: идти сверху вниз и останавливаться на первом подходящем. Рефлексия — не «продвинутый способ», а последнее средство, когда типы становятся известны только в рантайме.

Рефлексия: три закона

Рефлексия в Go описана Робом Пайком в классической статье The Laws of Reflection. Три закона стоит выучить дословно.

Закон первый: рефлексия идёт от интерфейсного значения к объекту рефлексии. Интерфейсное значение внутри — это пара «(динамический тип, значение)». reflect.TypeOf и reflect.ValueOf просто достают из этой пары обе половины.

Закон второй: от объекта рефлексии можно вернуться к интерфейсному значению — через Value.Interface().

Закон третий: чтобы менять объект рефлексии, значение должно быть адресуемым (settable). Копию менять бессмысленно, поэтому в reflect.ValueOf передают указатель, а потом берут Elem().

Ключевое различие, которое путают: Type — это про описание типа, Kind — про его категорию. У типа type UserID int64 имя UserID, а Kind — reflect.Int64. Рефлексивный код почти всегда ветвится по Kind, а не по Type.

Практический пример: маппер конфигурации из окружения

Тридцать строк, которые заменяют ручной разбор десятков переменных — и хорошо показывают, как устроены библиотеки вроде caarlos0/env из главы про архитектуру.

// LoadEnv заполняет поля структуры из переменных окружения по тегу `env`.
// cfg обязан быть указателем на структуру — иначе поля не будут settable.
func LoadEnv(cfg any) error {
	v := reflect.ValueOf(cfg)
	if v.Kind() != reflect.Ptr || v.Elem().Kind() != reflect.Struct {
		return errors.New("LoadEnv: нужен указатель на структуру")
	}
	v = v.Elem()          // третий закон: разыменовали — получили адресуемое значение
	t := v.Type()

	for i := 0; i < t.NumField(); i++ {
		field := t.Field(i)
		key, ok := field.Tag.Lookup("env")     // Lookup отличает "нет тега" от "пустой тег"
		if !ok {
			continue
		}
		raw, present := os.LookupEnv(key)
		if !present {
			if def, hasDef := field.Tag.Lookup("default"); hasDef {
				raw = def
			} else {
				continue
			}
		}
		fv := v.Field(i)
		if !fv.CanSet() {                      // неэкспортированное поле менять нельзя
			return fmt.Errorf("поле %s неэкспортировано", field.Name)
		}
		switch fv.Kind() {
		case reflect.String:
			fv.SetString(raw)
		case reflect.Int, reflect.Int64:
			// time.Duration — тоже Int64, различаем по типу
			if fv.Type() == reflect.TypeOf(time.Duration(0)) {
				d, err := time.ParseDuration(raw)
				if err != nil {
					return fmt.Errorf("%s: %w", key, err)
				}
				fv.SetInt(int64(d))
				continue
			}
			n, err := strconv.ParseInt(raw, 10, 64)
			if err != nil {
				return fmt.Errorf("%s: %w", key, err)
			}
			fv.SetInt(n)
		case reflect.Bool:
			b, err := strconv.ParseBool(raw)
			if err != nil {
				return fmt.Errorf("%s: %w", key, err)
			}
			fv.SetBool(b)
		default:
			return fmt.Errorf("%s: неподдерживаемый тип %s", field.Name, fv.Kind())
		}
	}
	return nil
}

type Config struct {
	Addr    string        `env:"APP_ADDR" default:":8080"`
	DBURL   string        `env:"DATABASE_URL"`
	Debug   bool          `env:"DEBUG" default:"false"`
	Timeout time.Duration `env:"HTTP_TIMEOUT" default:"30s"`
}

Разберите этот код внимательно — в нём собраны все грабли рефлексии сразу: проверка Kind, разыменование указателя, CanSet, различение time.Duration и обычного int64, невозможность тронуть неэкспортированные поля.

Цена рефлексии

Конкретные цифры зависят от задачи, но порядок такой: рефлексивный доступ к полю в десятки раз медленнее прямого, а рефлексивный вызов метода — в сотни. Причины:

• Каждое обращение — это поиск метаданных и проверки в рантайме.
• Value.Interface() почти всегда даёт аллокацию в куче (упаковка в интерфейс — из главы про рантайм).
• Инлайнинг невозможен: компилятор не видит, что вы вызываете.
• Ошибки типов переезжают из компиляции в рантайм и вылезают паникой у пользователя.

Отсюда правило: рефлексия допустима на границе системы, но не внутри неё. Разобрать конфиг при старте, сериализовать ответ, провалидировать входящий DTO — да. Использовать в цикле обработки миллиона записей — нет: там нужна кодогенерация.

Полезный приём для библиотек — «рефлексия один раз»: при первом обращении к типу разобрать его структуру и закешировать в map[reflect.Type]*layout, а дальше работать по готовому плану. Так устроены быстрые сериализаторы.

Теги структур: мини-DSL, который никто не проверяет

Тег — это просто строка, лежащая в метаданных поля. Соглашение о формате (ключ:"значение" через пробел) поддерживается всеми библиотеками:

type Order struct {
	ID       int64     `json:"id" db:"id"`
	UserID   int64     `json:"user_id" db:"user_id" validate:"required"`
	Total    float64   `json:"total" db:"total" validate:"gte=0"`
	Comment  string    `json:"comment,omitempty" db:"comment" validate:"max=500"`
	Internal string    `json:"-" db:"-"`
}

Главная опасность: опечатка в теге ничего не ломает на компиляции. Написали json:"user_ID" вместо user_id — код собрался, тесты, если их нет на сериализацию, прошли, а API отдал не то поле. Защита:

• go vet содержит анализатор structtag, ловящий синтаксически неверные теги и дубли ключей — держите его в CI (см. главу про инструменты).
• Пишите тест «сериализовать эталонную структуру и сравнить с golden-файлом» — приём из главы про тестирование. Он ловит любые изменения контракта.

Свой тег читается через field.Tag.Get("mytag"), а Lookup дополнительно отличает отсутствующий тег от пустого.

go generate: главный путь Go

Философия языка: лучше сгенерировать обычный Go-код, чем колдовать в рантайме. Сгенерированный код читается, отлаживается, инлайнится и проверяется компилятором — все преимущества рефлексии без её цены.

Механизм примитивен до изящества. Комментарий специального вида:

//go:generate stringer -type=Status

type Status int

const (
	Pending Status = iota
	Active
	Closed
)

Команда go generate ./... находит такие комментарии и выполняет их как команды. Компилятор про них ничего не знает — это отдельный шаг, запускаемый человеком или CI. В результате появляется файл status_string.go с методом String(), который делает то же, что рефлексивный вариант, но в сотни раз быстрее и без аллокаций.

Экосистема генераторов покрывает почти всю рутину:

Правила гигиены, выработанные сообществом:

• Коммитьте сгенерированный код в репозиторий. Тогда go build работает без установленных генераторов, IDE видит символы, а go install вашего пакета не требует шаманства.
• Заголовок «Code generated by … DO NOT EDIT.» в первой строке файла — это соглашение, которое понимают линтеры, git diff и подсветка на GitHub.
• Отдельные файлы (*_gen.go, mocks/), никакого смешивания с рукописным кодом.
• Фиксируйте версии генераторов. С Go 1.24 для этого есть директива tool в go.mod и команда go tool; раньше применялся приём с файлом tools.go под build-тегом.
• Проверяйте в CI, что генерация актуальна:

go generate ./...
git diff --exit-code || { echo "Сгенерированный код устарел: запустите go generate"; exit 1; }

Этот трёхстрочный шаг ловит самую частую проблему кодогенерации — расхождение между схемой и сгенерированным кодом.

unsafe: аварийный люк в модель памяти

Пакет unsafe выводит вас из-под гарантий языка. Он нужен в трёх ситуациях: интеграция с C, преобразования без копирования в горячих парсерах и низкоуровневые трюки в библиотеках рантайм-уровня. Во всех остальных случаях его наличие в диффе — повод для тяжёлого разговора на ревью.

Конверсия строка ↔ байты без копирования

Обычное []byte(s) копирует данные, потому что строки в Go неизменяемы, а срезы — нет. На горячем пути парсера это заметно. С Go 1.20 у операции есть легальная форма:

// Строка из байтов без копирования. Требование: b больше НИКТО не изменит.
func unsafeString(b []byte) string {
	return unsafe.String(unsafe.SliceData(b), len(b))
}

// Байты из строки без копирования. Требование: результат ТОЛЬКО для чтения.
func unsafeBytes(s string) []byte {
	return unsafe.Slice(unsafe.StringData(s), len(s))
}

Опасность буквальна: запись в такой срез нарушает неизменяемость строки. Строки-константы лежат в неизменяемой секции бинарника, и попытка записи — падение процесса; строка из кучи «мутирует» задним числом, а вместе с ней — все, кто её держит, включая ключи карт. Отсюда и правило: применяйте такое только внутри одной функции, где видно весь жизненный цикл данных, и обязательно прикройте фаззингом (глава 05).

Размер, выравнивание и порядок полей

unsafe.Sizeof, Alignof и Offsetof — единственная безопасная часть пакета: они вычисляются на этапе компиляции и ничего не нарушают. Практическая польза — увидеть, сколько памяти тратится на выравнивание.

type Bad struct {
	Active  bool   // 1 байт + 7 байт выравнивания
	Count   int64  // 8 байт
	Deleted bool   // 1 байт + 7 байт хвостового выравнивания
}                  // unsafe.Sizeof(Bad{}) == 24

type Good struct {
	Count   int64  // 8 байт
	Active  bool   // 1 байт
	Deleted bool   // 1 байт + 6 байт хвоста
}                  // unsafe.Sizeof(Good{}) == 16

Одна перестановка полей — минус треть памяти. На структуре, которой в памяти миллионы экземпляров, это гигабайты. Искать такое вручную не нужно: анализатор fieldalignment из golang.org/x/tools находит все случаи автоматически. Но и здесь мера: ради читаемости порядок полей менять стоит только там, где счёт идёт на миллионы объектов.

Правила и проверки

unsafe.Pointer — универсальный указатель, но конвертации разрешены не любые. Главное правило, которое нарушают чаще всего: преобразование Pointer → uintptr и обратно допустимо только внутри одного выражения. uintptr — обычное число, GC его не видит; если между конверсиями произойдёт сборка мусора или рост стека, вы получите указатель в никуда.

Инструменты, которые страхуют:

• go vet с анализатором unsafeptr — ловит классические нарушения.
• Сборка с -race включает checkptr — рантайм-проверки корректности unsafe-конверсий.
• Фаззинг и бенчмарк, доказывающий, что выигрыш вообще есть.

Отдельно про //go:linkname — директиву, позволяющую подцепиться к приватной функции чужого пакета. Это лежит за пределами любых гарантий совместимости, ломается при обновлении Go, и в свежих версиях линкер намеренно ограничил такие трюки. Знать о ней стоит, чтобы опознать в чужом коде источник будущей боли.

cgo: мост в мир C

package main

/*
#include <stdlib.h>
#include <string.h>

static int sum(int a, int b) { return a + b; }
*/
import "C"                    // ВАЖНО: строго следующей строкой после комментария
import "unsafe"

func main() {
	println(int(C.sum(2, 3)))

	// Строка Go → строка C: ВЫДЕЛЯЕТСЯ ПАМЯТЬ В C-КУЧЕ
	cs := C.CString("привет")
	defer C.free(unsafe.Pointer(cs))   // освобождать обязаны вы, GC сюда не ходит
	_ = C.strlen(cs)
}

Что происходит при вызове

Из диаграммы видны все издержки:

• Смена стека. Стеки горутин растут копированием (см. главу про рантайм), а код на C этого не переживёт — значит, нужен системный стек. Один вызов стоит порядка десятков-сотен наносекунд против единиц у обычного вызова Go, и инлайн невозможен.
• Горутина не вытесняется, пока внутри C. Долгий C-вызов держит поток ОС.
• Память C невидима для GC. C.CString, C.malloc — освобождаете вы. Утечки здесь классические.
• Передача указателей ограничена правилами: код на C не имеет права сохранять указатель на память Go после возврата. Рантайм частично проверяет это (cgocheck), но полагаться на проверки не стоит.

Настоящая цена — за пределами производительности

Дэйв Чейни сформулировал это как «cgo is not Go». Включая cgo, вы теряете:

• Кросс-компиляцию одной командой — теперь нужен кросс-тулчейн C под каждую цель.
• CGO_ENABLED=0 и статический бинарник — а с ним и образ scratch/distroless из главы про деплой. Появляется зависимость от версии libc на хосте.
• Скорость сборки — компилируется ещё и C.
• Часть инструментов — стеки C не видны в pprof-профилях Go, детектор гонок не следит за памятью C.

Поэтому в Go-сообществе действует сильная норма: сначала ищите чистую Go-реализацию. Для SQLite есть modernc.org/sqlite (транспиляция C в Go, без cgo), для DNS — miekg/dns, для криптографии — стандартная библиотека. Альтернативы cgo, если своей реализации нет: вынести C-часть в отдельный процесс и общаться через stdin/stdout или сокет; скомпилировать её в WebAssembly и запустить через wazero без cgo; в крайнем случае — принять цену осознанно.

Обратное направление тоже работает: go build -buildmode=c-archive и -buildmode=c-shared превращают пакет Go в библиотеку для C, Python или Rust. Про устройство FFI с другой стороны — глава про unsafe и FFI в треке Rust.

Go и WebAssembly

Ещё одна форма выхода за пределы платформы — компиляция в WebAssembly:

GOOS=js GOARCH=wasm go build -o app.wasm ./cmd/web     # для браузера
GOOS=wasip1 GOARCH=wasm go build -o app.wasm ./cmd/cli # WASI, Go 1.21+

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

Типичные ошибки

• Рефлексия там, где хватило бы интерфейса или дженерика. Проверьте по схеме в начале главы.
• Рефлексия в горячем цикле без кеширования разбора типа.
• reflect.ValueOf(cfg) без указателя — поля не settable, изменения молча теряются.
• Опечатка в теге структуры, не покрытая тестом.
• Сгенерированный код не в репозитории — сборка перестаёт быть воспроизводимой.
• Забытая перегенерация после изменения схемы: лечится проверкой git diff --exit-code в CI.
• unsafe без бенчмарка, доказывающего необходимость.
• Запись в срез, полученный из строки через unsafe.
• cgo ради удобства, а не необходимости: теряется статическая сборка и кросс-компиляция.
• C.CString без defer C.free — утечка, которую не покажет ни один Go-профилировщик.

Мини-итог

• Порядок выбора: интерфейс → дженерик → кодогенерация → рефлексия. Останавливайтесь на первом подходящем.
• Рефлексия работает через пару «(тип, значение)» интерфейса; менять можно только адресуемое, поэтому передают указатель.
• Цена рефлексии — десятки-сотни раз медленнее, ошибки в рантайме; место ей на границах системы.
• Теги — соглашение без проверок компилятором; страхуйтесь go vet и golden-тестами.
• go generate — основной путь Go: генерируемый код коммитится, версии инструментов фиксируются, актуальность проверяется в CI.
• unsafe оправдан редко и только за безопасным API, с фаззингом и бенчмарком.
• cgo стоит дороже, чем кажется: платите кросс-компиляцией, статической сборкой и наблюдаемостью.

Источники

• The Laws of Reflection — Роб Пайк, обязательное чтение.
• Generating code — официальное введение в go generate.
• Документация reflect и unsafe — в последней перечислены допустимые шаблоны конверсий.
• cgo documentation и cgo is not Go.
• WebAssembly wiki — сборка под браузер и WASI.

Что дальше

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

13. CLI-приложения на Go