Инструменты — справочник

1. go-команды и окружение

GOTOOLCHAIN управляет выбором тулчейна. Начиная с Go 1.21 строка go в go.mod — строгий минимум: если модулю нужна более новая версия, go скачает и запустит её. GOTOOLCHAIN=local запрещает переключение, GOTOOLCHAIN=go1.27.0 фиксирует версию.

go env GOMOD GOPATH GOBIN GOTOOLCHAIN
go help mod tidy
go doc fmt.Printf

2. Модули и версии

Модуль — набор пакетов с общим go.mod. Версии зависимостей выбираются по принципу минимальной версии (MVS): побеждает самая высокая из минимально требуемых, а не самая свежая.

module example.com/billing

go 1.27

toolchain go1.27.0

require (
    github.com/jackc/pgx/v5 v5.12.0
    golang.org/x/sync v0.19.0
)

require github.com/jackc/puddle/v2 v2.2.2 // indirect

replace example.com/legacy => ../legacy

tool golang.org/x/tools/cmd/stringer

go mod tidy приводит go.mod и go.sum в соответствие с импортами. С Go 1.23 есть go mod tidy -diff: показать изменения и не писать файлы. С Go 1.27 для модулей с go 1.27 tidy схлопывает дублирующиеся блоки require в два: прямые и косвенные.

go mod init example.com/billing
go mod tidy -diff
go get github.com/jackc/pgx/v5@v5.12.0
go get -u ./...
go get -tool golang.org/x/tools/cmd/stringer
go install tool

go mod why -m golang.org/x/sync
go mod graph | head

Приватные модули: GOPRIVATE задаёт шаблоны путей, для которых не используются публичные прокси и проверка sumdb; GONOPROXY и GONOSUMDB уточняют поведение по отдельности. GOAUTH [1.24] настраивает аутентификацию для закрытых хостов.

3. Workspaces

Workspace объединяет несколько модулей в одну сборку без replace на каждый. Файл go.work лежит над модулями и действует, пока GOWORK не указывает на другой файл или off.

go work init ./api ./worker ./shared

# go.work
go 1.27

use (
    ./api
    ./worker
    ./shared
)

go.work обычно не коммитят: он описывает локальную раскладку каталогов. В CI собирают модули по отдельности или генерируют workspace явно.

4. Тесты

Тест — функция TestXxx(t *testing.T) в файле _test.go. Пакет теста может быть тем же (package store) или внешним (package store_test); внешний видит только экспортированное.

func TestParseAmount(t *testing.T) {
    tests := []struct {
        name    string
        in      string
        want    int64
        wantErr bool
    }{
        {"целое", "42", 42, false},
        {"пусто", "", 0, true},
        {"буквы", "abc", 0, true},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            t.Parallel()

            got, err := ParseAmount(tt.in)
            if (err != nil) != tt.wantErr {
                t.Fatalf("err = %v, wantErr %v", err, tt.wantErr)
            }
            if got != tt.want {
                t.Fatalf("got %d, want %d", got, tt.want)
            }
        })
    }
}

Примеры (ExampleXxx) проверяются go test: комментарий // Output: задаёт ожидаемый вывод.

func ExampleCut() {
    before, after, _ := strings.Cut("a=b", "=")
    fmt.Println(before, after)
    // Output: a b
}

5. Fuzzing

Fuzz-тест объявляется как FuzzXxx(f *testing.F). Семена добавляют f.Add, тело проверки — f.Fuzz. Генератор сам подбирает входы, а найденный падающий пример сохраняется в testdata/fuzz и дальше запускается как обычный тест.

func FuzzParseAmount(f *testing.F) {
    f.Add("42")
    f.Add("")
    f.Add("-7")

    f.Fuzz(func(t *testing.T, s string) {
        got, err := ParseAmount(s)
        if err != nil {
            return
        }
        if got < 0 && !strings.HasPrefix(s, "-") {
            t.Fatalf("negative result for %q", s)
        }
    })
}

go test -fuzz=FuzzParseAmount -fuzztime=30s ./...
go test -run=FuzzParseAmount ./...   # только сохранённые примеры

За один запуск исполняется один fuzz-таргет. Fuzzing не заменяет примеры и табличные тесты: он ищет неожиданные входы, а не проверяет сценарии.

6. Бенчмарки

Бенчмарк — BenchmarkXxx(b *testing.B). Каркас вызывает функцию несколько раз, подбирая b.N так, чтобы измерение было устойчивым. Внутри цикла не должно быть подготовки, которую не надо измерять.

func BenchmarkParseAmount(b *testing.B) {
    b.ReportAllocs()

    for i := 0; i < b.N; i++ {
        _, _ = ParseAmount("12345")
    }
}

func BenchmarkEncode(b *testing.B) {
    data := buildPayload()
    b.ResetTimer()

    for i := 0; i < b.N; i++ {
        _ = encode(data)
    }
}

go test -bench . -benchmem -count=5 | tee bench.txt
benchstat bench.txt

benchstat — отдельный инструмент golang.org/x/perf/cmd/benchstat; он сравнивает два набора и показывает, значимо ли изменение. Один прогон бенчмарка ничего не доказывает.

7. Статический анализ

go vet ./...
staticcheck ./...
golangci-lint run ./...
govulncheck ./...
gofmt -l .
go fix ./...

go vet входит в тулчейн и запускается в go test для части проверок. staticcheck и golangci-lint ставятся отдельно; версия линтера фиксируется в CI, иначе новые правила внезапно ломают сборку.

8. Race detector

Детектор гонок встроен в тулчейн и включается флагом -race. Он находит конфликтующие обращения, которые реально произошли во время запуска; ненайденная гонка не означает, что её нет.

go test -race ./...
go run -race ./cmd/api
go build -race -o api-race ./cmd/api

9. Профилирование и отладка

go test -bench . -cpuprofile cpu.out -memprofile mem.out
go tool pprof -http=:8080 cpu.out

dlv debug ./cmd/api
dlv test ./internal/store

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

10. Сборка и релиз

Build constraints задаются директивой //go:build в начале файла; несколько условий объединяются &&, || и !. Флаг -tags включает дополнительные метки.

//go:build linux && amd64

package platform

go build -tags=integration ./...

go tool dist list | grep linux

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
  go build -trimpath \
  -ldflags="-s -w -X main.version=$(git describe --tags)" \
  -o bin/api ./cmd/api

С Go 1.24 go build сам вшивает версию main-модуля из тега или коммита VCS и добавляет суффикс +dirty при незакоммиченных изменениях. Отключить это можно -buildvcs=false.

go version -m bin/api

Для воспроизводимой сборки фиксируют версию Go, зависимости в go.sum, -trimpath и отсутствие локальных replace. go:embed вшивает статические файлы в бинарник; подробности — в листе «Стандартная библиотека».

11. Первоисточники

• go command — все подкоманды и флаги
• Go Modules Reference — go.mod, MVS, replace, retract, tool
• Go Toolchains — GOTOOLCHAIN, переключение версий
• Testing — тесты, примеры, покрытие
• Fuzzing — FuzzXxx, корпус, -fuzztime
• pkg.go.dev/testing — T, B, F, Run, Cleanup
• pkg.go.dev/cmd/vet — анализаторы go vet
• staticcheck.dev — проверки SA, S, ST, QF
• govulncheck — поиск уязвимостей
• Delve — отладчик
• Release notes Go 1.21 — go как строгий минимум, автоматический выбор тулчейна
• Release notes Go 1.24 — tool-директива, go get -tool, go build -json
• Release notes Go 1.26 — переписанный go fix
• Release notes Go 1.27 — go mod tidy схлопывает блоки require