github.com/acme/billing/         ← модуль (тут go.mod)
├── go.mod  go.sum
├── main.go                      ← пакет main
├── invoice/                     ← пакет invoice
│   ├── invoice.go
│   ├── total.go                 ← тот же пакет: файлы в одной папке
│   └── pdf/                     ← ДРУГОЙ пакет invoice/pdf
└── internal/store/              ← пакет store, виден только внутри модуля

# Путь импорта = путь модуля + относительный путь директории:
import "github.com/acme/billing/invoice/pdf"

Несколько модулей в репозитории

Технически можно: положи go.mod в подпапку, и она станет отдельным модулем (её содержимое автоматически исключается из родительского). Но цена высокая: теги превращаются в subdir/v1.2.0, версии расходятся, релиз усложняется. На практике так делают ради двух вещей: (1) вынести пакет с тяжёлыми зависимостями (например, gRPC-контракты), чтобы потребители не тянули лишнего; (2) отделить примеры или e2e-тесты. В остальных случаях: один репозиторий, один модуль.

module github.com/acme/billing

go 1.24.0                       // языковая версия для всех пакетов модуля
toolchain go1.24.3              // какой тулчейн скачать, если локальный младше

require (
    github.com/jackc/pgx/v5 v5.6.0
    go.uber.org/zap         v1.27.0
)
require github.com/pkg/errors v0.9.1 // indirect

replace github.com/broken/lib => ../fork      // подмена источника или версии
exclude github.com/bad/lib v1.2.3             // «эту версию не рассматривать»
retract [v1.0.0, v1.0.4]                      // отозвать свои выпущенные версии
tool golang.org/x/tools/cmd/stringer          // Go 1.24: инструменты как зависимости

Директива go - три факта

• Задаёт, какие языковые фичи разрешены и по какой семантике работает код. Пример: go 1.22 включает новую семантику переменной цикла, а модуль с go 1.21 в том же билде продолжает работать по-старому. Семантику определяет модуль, а не версия тулчейна.
• С Go 1.21 она жёсткая: тулчейн младше указанного откажется собирать, а не выдаст предупреждение. При GOTOOLCHAIN=auto нужная версия скачается сама.
• Собрать модуль с go 1.19 новым компилятором можно и нужно: обратная совместимость соблюдается.

replace vs exclude vs retract

github.com/jackc/pgx/v5 v5.6.0        h1:SWJzexB...   # хеш дерева файлов модуля
github.com/jackc/pgx/v5 v5.6.0/go.mod h1:DNZ/vlr...   # хеш только его go.mod

Почему две строки

Чтобы посчитать граф зависимостей, MVS нужны только go.mod-файлы всех участников, сам код скачивать не обязательно. Поэтому хеш go.mod хранится отдельно. Отсюда же модули в go.sum, чей код в сборку не попал: их go.mod участвовал в вычислении версий. Чистить руками не надо, для этого есть go mod tidy.

Чем это отличается от package-lock.json

Checksum database

sum.golang.org ведёт прозрачный лог на дереве Меркла, только на добавление, по устройству похожий на Certificate Transparency. Он закрывает дыру, которую go.sum не закрывает: go.sum защищает тебя после того, как ты один раз зафиксировал хеш, а sumdb защищает первое скачивание, чтобы никто не подсунул тебе одну версию контента, а всему миру другую. Побочный, но важный эффект: теги становятся неизменяемыми де-факто.

# Что делать при SECURITY ERROR: checksum mismatch
# 1. Не делать go clean -modcache и не стирать go.sum «чтобы заработало»
# 2. Понять, чей хеш не сошёлся:
go mod download -x github.com/x/y
curl -s https://sum.golang.org/lookup/github.com/x/y@v1.2.3   # хеш, который видят все

# 3. Три реальные причины по убыванию частоты:
#    а) автор переписал тег (git tag -f + push --force), а модуль берут мимо прокси: писать автору, пинить другую версию
#    б) в корпоративном прокси лежит подменённый/битый артефакт: чистить прокси
#    в) go.sum поехал при мерже: восстановить и пересобрать (go mod tidy)

# Приватные модули настраиваются одной переменной:
go env -w GOPRIVATE=github.com/acme   # выключает и прокси, и sumdb для этих путей
git config --global url."git@github.com:".insteadOf "https://github.com/"

// v0 и v1 - без суффикса
import "github.com/acme/lib"          // v0.x.x или v1.x.x

// v2+ - суффикс обязателен и в go.mod, и в импорте
import "github.com/acme/lib/v2"       // module github.com/acme/lib/v2

// Побочный эффект: обе версии живут рядом, это разные модули
import (
    pgx4 "github.com/jackc/pgx/v4"
    pgx5 "github.com/jackc/pgx/v5"
)
// Так большой сервис переводят по пакету за раз, а не одним коммитом.

Три формы версии, которые надо узнавать

Как выпускают v2

# Вариант 1 - подпапка (major subdirectory)
mkdir v2 && cp *.go v2/ && cd v2    # v1 остаётся в корне для старых импортов
go mod init github.com/acme/lib/v2      # плюс переписать все внутренние импорты на /v2
git add . && git commit -m "v2" && git tag v2.0.0 && git push origin main v2.0.0

# Вариант 2 - ветка (major branch)
git checkout -b v2
# в go.mod: module github.com/acme/lib/v2, внутренние импорты тоже на /v2
git commit -am "v2" && git tag v2.0.0 && git push origin v2 v2.0.0

Алгоритм в трёх шагах

1. Обойти граф: go.mod главного модуля → go.mod его зависимостей → и так далее (нужны только go.mod-файлы, код не скачивается).
2. Для каждого пути модуля собрать множество требуемых версий.
3. Выбрать из множества максимальную. На выходе build list.

# main → A v1.2.0 → C v1.1.0
# main → B v1.5.0 → C v1.3.0
# В репозитории уже есть C v1.9.0
#
# Go:  требования на C = {v1.1.0, v1.3.0} → берём v1.3.0
# npm: диапазоны ^1.1.0 и ^1.3.0 → берём самое свежее в пересечении, v1.9.0

go list -m all                   # итоговый build list
go mod graph                     # весь граф требований
go mod why -m github.com/x/y     # зачем модуль в сборке: цепочка импортов
go list -m -u all                # какие обновления доступны

Плюсы и минусы - оба надо назвать

• + High-fidelity builds. Набор версий определяет только содержимое go.mod в графе, ни дата сборки, ни состояние реестра на него не влияют.
• + Нет «фантомных» апдейтов. Новая версия зависимости не приедет, пока кто-то явно не поднимет требование. Атака «выпустить вредоносный патч и ждать, пока CI сам подтянет» в Go не работает.
• + Простота. Нет NP-полного солвера, нет «resolution hell», нет протухшего лока.
• − Обновления только вручную. Патчи безопасности сами не приезжают: нужен go get -u, Renovate/Dependabot и govulncheck в CI.
• − Ответственность распределена. Если популярная библиотека требует старую версию с CVE, поднимать придётся в каждом потребителе через go get или exclude.

Цепочка загрузки

1. Локальный кэш $GOMODCACHE (по умолчанию $GOPATH/pkg/mod). Распакованные модули read-only плюс подкаталог cache/download, зеркало прокси в том же формате.
2. Прокси из GOPROXY задаётся списком через запятую, по умолчанию https://proxy.golang.org,direct. Прокси иммутабелен: раз опубликованную версию не изменить, а удаление тега в репозитории её из прокси обычно не убирает.
3. direct отправляет прямо в VCS (git clone). Срабатывает, если модуль не нашёлся в прокси или путь попал в GONOPROXY.

go mod vendor         # ./vendor + vendor/modules.txt
# go build сам включает -mod=vendor, если vendor/ существует и go >= 1.14
go build -mod=mod     # явно игнорировать vendor
go mod verify         # проверить, что кэш не меняли после скачивания (с go.sum не сверяет)
go mod download       # только скачать
go clean -modcache    # снести кэш целиком

# Воспроизводимая сборка в CI
go build -mod=readonly ./...   # запретить неявную правку go.mod (дефолт с 1.16)
go mod tidy -diff              # Go 1.23: упасть, если tidy что-то изменил бы

Три причины запрета

• Компиляция. Каждый пакет компилируется ровно один раз, результат ложится в архив и переиспользуется. Ациклический граф даёт топологический порядок и параллельную сборку независимых веток. Циклы потребовали бы компилировать группу пакетов совместно, и любая правка пересобирала бы всю группу.
• Инициализация. Порядок init() задаёт топологическая сортировка. В цикле «кто первый» не определено.
• Дизайн. Цикл почти всегда значит, что граница между пакетами проведена неправильно.

Четыре способа разорвать

// package order объявляет то, что ему нужно, и ничего не импортирует из user
type UserGetter interface {
    Get(ctx context.Context, id int64) (User, error)
}

type Service struct {
    users UserGetter
}
func New(users UserGetter) *Service { return &Service{users: users} }

func (s *Service) Create(ctx context.Context, uid int64) error {
    u, err := s.users.Get(ctx, uid)      // цикла нет: импорта user тут нет
    ...
}

// package user просто имеет подходящий метод, про интерфейс не знает
func (s *Store) Get(ctx context.Context, id int64) (order.User, error) { ... }

// package main - единственное место, где встречаются оба
svc := order.New(user.NewStore(db))

github.com/acme/app/
├── cmd/api/           → может импортировать internal/*   (внутри acme/app)
├── pkg/client/        → может импортировать internal/*   (внутри acme/app)
└── internal/
    ├── store/         ← родитель internal = github.com/acme/app
    └── auth/
        └── internal/jwt/   ← родитель = .../app/internal/auth
                             → виден ТОЛЬКО из auth и его поддерева

# А так не скомпилируется:
# package github.com/other/svc
import "github.com/acme/app/internal/store"
# → use of internal package github.com/acme/app/internal/store not allowed

Что важно понимать

• Уровень internal может быть любым и вложенным, поэтому внутри модуля строится настоящая иерархия видимости, а не один плоский «приватный» слой.
• Правило работает и в стандартной библиотеке, по тому же принципу: net/http/internal, crypto/internal/....
• Ограничение действует на уровне путей импорта, а не модулей. Если два модуля лежат в одном дереве путей, internal между ними пропустит. Случай редкий, но в монорепо встречается.
• Это единственный механизм видимости на уровне пакетов. Всё остальное сводится к заглавной или строчной букве идентификатора внутри одного пакета.

Полный список правил

1. Рантайм поднимается раньше всего: планировщик, аллокатор, GC, обработка сигналов.
2. Импортируемые пакеты: рекурсивно и полностью, в порядке топологической сортировки графа импортов. Цикл невозможен, поэтому порядок всегда определён.
3. Переменные уровня пакета: в порядке зависимостей между ними. Порядок объявления в файле важен только между независимыми переменными: из готовых к инициализации берётся первая по объявлению. Цикл в зависимостях переменных даёт ошибку компиляции initialization cycle.
4. Все init() пакета. Их может быть несколько в одном файле и несколько файлов. Порядок между файлами не гарантирован спецификацией, но go build передаёт файлы отсортированными по имени.
5. init() нельзя вызвать вручную, нельзя взять его адрес, у него нет параметров и результата.
6. Только после инициализации всех пакетов запускается main.main().

package main

var a = b + 1        // третьей: зависит от b
var b = f()          // второй:  зависит от c через f()
func f() int { return c }
var c = 1            // первой:  ни от чего не зависит

func init() { fmt.Println("init 1", a, b, c) }
func init() { fmt.Println("init 2") }     // обе выполнятся, сверху вниз

func main() { fmt.Println("main", a) }
// вывод:
// init 1 2 1 1     (c = 1 → b = f() = 1 → a = b+1 = 2)
// init 2
// main 2

Чем плохи init()

• Нельзя вернуть ошибку. На сбой остаётся только паника или log.Fatal: падение на старте без контекста и без выполнения defer-ов.
• Нельзя передать параметры. Конфиг берётся из глобальных переменных или прямо из os.Getenv, и зависимость становится скрытой.
• Ломают тесты. init выполняется при любом запуске тестов пакета. Пакет, который в init ходит в базу или читает файл, делает свои тесты нелокальными и нестабильными.
• Порядок неочевиден. Читая код, ты не видишь, что до него отработали три init из зависимостей.
• Транзитивные побочные эффекты. Классика: кто-то в глубине зависимостей импортировал net/http/pprof, и твой публичный сервер на дефолтном мультиплексоре отдаёт /debug/pprof/ наружу.
• Замедляют старт. Всё это происходит до main и до готовности readiness-пробы.

// Плохо
var db *sql.DB
func init() {
    var err error
    db, err = sql.Open("postgres", os.Getenv("DSN"))
    if err != nil { log.Fatal(err) }
}

// Хорошо: явный конструктор, ошибка возвращается, вызывается из main
func NewDB(ctx context.Context, dsn string) (*sql.DB, error) {
    db, err := sql.Open("postgres", dsn)
    if err != nil { return nil, fmt.Errorf("open db: %w", err) }
    if err := db.PingContext(ctx); err != nil { return nil, fmt.Errorf("ping db: %w", err) }
    return db, nil
}

// Дорогой объект создают лениво через sync.Once, а не в init
var Client = sync.OnceValue(buildClient)   // Go 1.21

# Минимальный набор в CI
gofmt -l .                     # пусто = ок
go vet ./...
go test -race -count=1 ./...
go mod tidy -diff              # Go 1.23
golangci-lint run --timeout=5m
govulncheck ./...

//go:generate mockgen -source=$GOFILE -destination=mocks/store_mock.go -package=mocks
//go:generate stringer -type=Status -linecomment

type Status int
const (
    StatusNew  Status = iota // new
    StatusPaid               // paid
)

// Go 1.24: инструменты фиксируются прямо в go.mod
//   go get -tool golang.org/x/tools/cmd/stringer
//   go tool stringer -type=Status
// Раньше нужен был файл tools.go с build-тегом //go:build tools
// и пустыми импортами, только чтобы версии инструментов попали в go.mod.

//go:build linux && amd64 && !nocgo

package storage
// Синтаксис с Go 1.17; старая форма // +build до сих пор встречается в чужом коде.
// Строка обязана идти до package; пустую строку после неё gofmt поставит сам.
// Поддерживает && || ! и скобки.

# Неявные теги по имени файла работают без строки //go:build
store_linux.go           # GOOS=linux (и android)
store_windows_amd64.go   # GOOS=windows и GOARCH=amd64
store_test.go            # только при go test

# Свои теги
go build -tags="integration,e2e" ./...
go test  -tags=integration ./...

# Кросс-компиляция
GOOS=linux   GOARCH=amd64 go build -o app .
GOOS=darwin  GOARCH=arm64 go build -o app-mac .
GOOS=windows GOARCH=amd64 go build -o app.exe .
go tool dist list                      # все поддерживаемые пары

# Прод-сборка контейнерного бинаря
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
  go build -trimpath -ldflags="-s -w -X main.version=$(git describe --tags)" -o /app .

/*
#cgo LDFLAGS: -lz
#include <zlib.h>
*/
import "C"        // псевдопакет: строка import "C" должна идти сразу за комментарием

func Version() string {
    return C.GoString(C.zlibVersion())   // конверсии C.GoString / C.CString
}
// C.CString выделяет память malloc'ом, освобождать её надо вручную:
//   p := C.CString(s); defer C.free(unsafe.Pointer(p))

Цена - по пунктам

Когда CGO всё-таки нужен

• Библиотека существует только на C и переписывать её нереально: ffmpeg, OpenCV, librdkafka, ODBC-драйверы, аппаратные SDK.
• Системные API без Go-обёртки.
• Постепенная миграция legacy C-кодовой базы.

Go 1.22 (февраль 2024)

• Переменная цикла теперь своя на каждой итерации. Классическая ловушка с замыканиями и &v исчезла. Включает её строка go 1.22 в go.mod: решает модуль, а не версия тулчейна, чтобы старый код не сломался молча.
• Паттерны в http.ServeMux: "GET /users/{id}", r.PathValue("id"), многосегментный {path...}. Приоритет считается по специфичности, а конфликтующие паттерны паникуют при регистрации.
• for i := range 10: range по целому.
• math/rand/v2, первый /v2 внутри самой stdlib; slices.Concat; PGO-сборки быстрее на 2–14%.

Go 1.23 (август 2024)

• Итераторы: range над функцией + пакет iter (Seq[V], Seq2[K,V], Pull). Тело цикла становится колбэком yield, а break превращается в false из yield.
• Итераторные функции в slices/maps: slices.Sorted(maps.Keys(m)), slices.All, slices.Values, slices.Collect.
• Таймеры переделаны: канал Timer/Ticker теперь без буфера, и неостановленные таймеры собираются GC, поэтому классическая утечка time.After внутри select в цикле больше не утекает.
• Пакет unique для интернирования значений.

Go 1.24 (февраль 2025)

• Swiss Tables, новая реализация мап: группы слотов с control word, на amd64 поиск через SIMD. До 60% быстрее на микробенчмарках, около 1,5% по реальным приложениям, меньше памяти. Для кода прозрачно. Плюс новая реализация sync.Map и аллокатор мелких объектов.
• Generic type aliases: type Set[T comparable] = map[T]struct{}.
• tool-директива в go.mod и команда go tool: хак с tools.go и build-тегом больше не нужен.
• testing.B.Loop: for b.Loop() вместо for i := 0; i < b.N; i++. Setup не попадает в замер, а аргументы и результат защищены от выбрасывания оптимизатором.
• os.Root: операции с файлами, ограниченные деревом директории (защита от path traversal); пакет weak; runtime.AddCleanup вместо SetFinalizer.

Go 1.25 (август 2025)

• WaitGroup.Go: wg.Go(func(){...}) вместо связки Add(1) + go + defer Done(). Убирает целый класс ошибок с забытым Done и рассинхроном счётчика.
• Container-aware GOMAXPROCS: рантайм читает CPU-лимит cgroup и подстраивается динамически. Библиотека automaxprocs, которую раньше тащили в каждый сервис, стала не нужна.
• testing/synctest, стабильный пакет для детерминированных тестов конкурентного кода с «виртуальным» временем.
• Экспериментальные на тот момент: сборщик Green Tea (GOEXPERIMENT=greenteagc) и encoding/json/v2. Оба с тех пор стали дефолтными, см. 1.26 и 1.27. Плюс flight recorder в runtime/trace.
• net/http.CrossOriginProtection, штатная CSRF-защита на Fetch metadata (Sec-Fetch-Site), без токенов и кук.

Go 1.26 (февраль 2026)

• Green Tea GC включён по умолчанию. Минус 10–40% накладных расходов сборщика, плюс примерно ещё 10% на свежих amd64 (Intel Ice Lake, AMD Zen 4+) за счёт векторных инструкций. Откат: GOEXPERIMENT=nogreenteagc.
• Два изменения в самом языке. Первое: new теперь принимает выражение, а не один лишь тип: p := new(compute()), r := Req{Limit: new(50)}. Самописный func ptr[T any](v T) *T больше не нужен. Второе: дженерик-тип может ссылаться на себя в собственном констрейнте: type Adder[A Adder[A]] interface{ Add(A) A }.
• errors.AsType[T](err) (T, bool), дженерик-версия errors.As: типобезопасно, быстрее и без объявления переменной заранее. Плюс slog.NewMultiHandler и io.ReadAll примерно вдвое быстрее.
• Экспериментальный профиль goroutineleak (GOEXPERIMENT=goroutineleakprofile) находит горутины, заблокированные на примитивах, до которых уже никто не дотянется. Вызовы cgo подешевели примерно на 30%.
• Мелочи, на которых ловят: редирект ServeMux на завершающий слэш стал 307 вместо 301; os/signal.NotifyContext отменяет контекст через CancelCauseFunc, так что context.Cause покажет, какой сигнал пришёл; go fix переписан в набор «модернизаторов»; go mod init в 1.26.0 стал писать версию на минор ниже, но в 1.26.1 это откатили, и он снова пишет версию тулчейна целиком, вместе с патчем: go 1.27.1 на go1.27.1.

Go 1.27 (август 2026) - текущая

• У методов появились собственные параметры типа, то есть снято ограничение, которое годами называли главным недостатком дженериков в Go: func (b *Box) MapTo[T any](f func(int) T) []T. Запрет остался только на стыке с интерфейсами: у метода интерфейса параметров типа быть не может, а дженерик-метод не засчитывается в реализацию интерфейса, иначе интерфейс нельзя проверить статически и собрать itab. Пример в stdlib: дженерик-метод Rand.N() в math/rand/v2.
• encoding/json/v2 стал отдельным пакетом, и на нём же теперь реализован старый encoding/json (откат: GOEXPERIMENT=nojsonv2). Но поведение v1 сохранили специально: проверено на go1.27.0, json.Unmarshal по-прежнему молча ест и {"a":1,"a":2}, и невалидный UTF-8. Строгость появляется только при явном импорте v2, поэтому апгрейд тулчейна ничего не ломает, а вот переход на v2 «сломает» приём кривого JSON, который раньше проглатывался. Unmarshal заметно быстрее. Рядом лежит низкоуровневый encoding/json/jsontext; опции тега format и unknown убраны, inline переименован в embed.
• Пакет uuid в стандартной библиотеке (RFC 9562): New(), NewV4(), NewV7(), Parse. NewV7 сортируется по времени, ровно то, что нужно для первичных ключей в БД. Внешний github.com/google/uuid больше не обязателен.
• Профиль goroutineleak стал общедоступным: виден в pprof.Profiles() и по /debug/pprof/goroutineleak. Штатный инструмент поиска утечек горутин в проде, а раньше обходились runtime.NumGoroutine и goleak в тестах.
• Ещё из полезного: strings.CutLast / bytes.CutLast; testing/synctest.Sleep; Server.MaxHeaderValueCount против заголовочного флуда; часть мелких аллокаций (<80 байт) дешевле до 30%; метки горутин из runtime/pprof попадают в заголовки трейсбеков, и падение сразу показывает, какой запрос обрабатывала горутина. Удалён GODEBUG=asynctimerchan: каналы таймеров теперь всегда небуферизованные.