Переход на Go 1.27: что сломается и что внедрить в первую очередь

Go 1.27 вышла в августе 2026 года, и для большинства модулей обновление сводится к изменению одной строки в go.mod и прогону go fix — но некоторые изменения действуют незаметно. Ниже описано, что именно ломается и что стоит внедрить в первую очередь.

Главными нововведениями являются структурные изменения: encoding/json теперь работает на основе новой реализации json/v2, пакет uuid вошел в стандартную библиотеку, и методы наконец-то могут объявлять собственные параметры типов. Ни одно из этих изменений не требует переписывания кода, и команда Go сохранила обычное обещание совместимости — почти все компилируется и работает без изменений.

Тем не менее, не все изменения безобидны. Несколько параметров GODEBUG теперь вызывают сбой сборки при старых значениях, compress/flate генерирует другие байты, go test применяет новую проверку stdversion, а имена символов, генерируемых компилятором, изменились. Если вам нужно освежить синтаксис тех частей, которые остались без изменений, шпаргалка по Go по-прежнему актуальна; это руководство охватывает остальное, включая команды и способы исправления для каждого пункта.

Путь обновления в одной диаграмме

Команда Go рекомендует последовательность: сначала сборка, затем исправление. go fix переписывает код под новые API и идиомы, но только чистая сборка покажет, затронули ли вас изменения на уровне времени выполнения.

Начните с самого тулчейна. Если вы управляете тулчейнами через команду go, либо зафиксируйте версию в go.mod, либо установите её явно:

go install golang.org/dl/go1.27@latest
go1.27 download
go1.27 version

Альтернативно, установите GOTOOLCHAIN=go1.27.0 в окружении или добавьте toolchain go1.27.0 в go.mod и позвольте команде go загрузить её. Полемика о структуре рабочего пространства Go, описанная в статье Структура рабочего пространства Go, объясняет, как строки go и toolchain взаимодействуют в нескольких модулях; краткая версия для одного модуля приведена ниже.

Шаг 1: повышение версии go и очистка удаленных настроек GODEBUG

go mod edit -go=1.27
go mod tidy
go build ./...

Повышение директивы go включает новые языковые функции (генерические методы, ключи полей в литералах структур, более широкий вывод типов функций) и заставляет команду go строго относиться к настройкам GODEBUG, поддержка которых была удалена. В Go 1.27 эти настройки были окончательно удалены:

• asynctimerchan — каналы таймеров и тикеров теперь всегда небуферизованы
• gotypesalias
• tlsunsafeekm, tlsrsakex, tls3des, tls10server
• x509keypairleaf

Новое правило: команда go все еще принимает эти настройки в go.mod (записи godebug) или в исходном коде (комментарии //go:debug), если они установлены на финальное значение по умолчанию, существовавшее до удаления. Старое значение — то, которое отключало изменение поведения — вызывает сбой сборки:

//go:debug asynctimerchan=0  // ошибка сборки: старое значение удаленной настройки
//go:debug asynctimerchan=1  // принимается, но лучше удалить строку

Если ваша сборка падает здесь, значит код полагался на буферизованные каналы таймеров из версий Go до 1.23. Исправление лежит в коде, а не в конфигурации: проверьте использование Timer.Stop и Timer.Reset в соответствии с паттернами контекста, отмены и таймаутов, которые зависят от синхронных каналов. Тот же поиск применим к настройкам, связанным с TLS — все, что фиксирует tls3des=1 или tls10server=1, поддерживало старые криптосуиты, и Go 1.27 отказывается их компилировать.

Шаг 2: запуск go test — ловушка stdversion

go build и go test больше не согласуются. go test в Go 1.27 по умолчанию выполняет проверку vet stdversion, которая сообщает о символах стандартной библиотеки, слишком новых для версии go, действующей в файле.

// go.mod все еще говорит "go 1.26"
func Base(p string) string {
    _, file, ok := strings.CutLast(p, "/") // добавлено в Go 1.27
    if !ok {
        return p
    }
    return file
}

С тулчейном 1.27 go build завершается успешно — компилятор знает strings.CutLast — но go test падает на шаге vet, потому что go.mod все еще объявляет 1.26. С реальным тулчейном 1.26 файл вообще не собрался бы. Урок здесь процедурный: никогда не валидируйте обновление только с помощью go build; запускайте полный набор тестов, а затем повышайте версию go. Набор проверок vet в go test также обнаружил новую проблему с printf: fmt.Errorf("...: %w", p), где p — это *E, а E реализует error, теперь выдает предупреждение, потому что оборачивание указателя приводит к сшибкам в проверках errors.Is. Этот режим отказа проявляется в коде обработки ошибок именно так, как описано в паттернах архитектуры обработки ошибок в Go — проверяйте тип операнда, а не только формат-строку.

encoding/json: движок v2 под капотом

Крупнейшее внутреннее изменение: encoding/json/v2 (экспериментальный с Go 1.25 как GOEXPERIMENT=jsonv2) стал официальным, и классический пакет encoding/json теперь поддерживается реализацией v2. Для вызовов v1 поведение сохраняется — nil-сlices по-прежнему кодируются как null, ключи мап по-прежнему сортируются — с одним видимым отличием: точный текст некоторых сообщений об ошибках изменился. Если тесты или мониторинг сопоставляют строки ошибок, ожидайте отличий.

Три вещи все еще могут пойти не так:

1. Текст ошибок. Любые утверждения strings.Contains(err.Error(), ...), основанные на старом текстовом оформлении v1, требуют обновления.
2. Пути, чувствительные к производительности, могут измениться. Раз marshalling стал быстрее, но переписывание меняет то, какие операции выделяют память; бенчмарки, отмеченные в CI, покажут это.
3. Экстренный выход для совместимости. GOEXPERIMENT=nojsonv2 восстанавливает исходную реализацию v1 во время сборки. Это временное решение — планируйте его удаление, а не использование в продакшене.

Второстепенный эффект для золотых тестов: энкодер compress/flate изменился в том же релизе, поэтому выходные данные archive/zip, compress/gzip, compress/zlib и image/png могут отличаться от версий Go 1.26 байт в байт, хотя декодируются идентично. Перегенерируйте сжатые фикстуры, а не закрепляйте старые байты.

Осознанный переход на API v2

API v2 — это отдельный импорт (encoding/json/v2) с функциями Marshal, Unmarshal и системой опций. Поддерживаемый путь миграции — сначала заставить вызовы v2 вести себя как v1, а затем выборочно ужесточить настройки:

import (
    "encoding/json/v2"
    "encoding/json/jsontext"
)

// Шаг 1: идентичное поведение с encoding/json — безопасное, механическое изменение
out, err := jsonv2.Marshal(v, jsonv2.DefaultOptionsV1())

// Шаг 2: включать один дефолт v2 за раз
out, err := jsonv2.Marshal(v,
    jsonv2.DefaultOptionsV1(),
    jsonv2.FormatNilSliceAsNull(false)) // nil-slices теперь кодируются как []

Как только вы уберете DefaultOptionsV1, вступают в силу дефолты v2, которые строже и более интероперабельны, чем в v1:

Неотсортированные ключи мап — это то, что удивит тесты с золотыми файлами: v2 пропускает сортировку, потому что она стоит дорого. Когда вам нужна стабильная keluarка — фикстуры, snapshot-тесты, хешированные представления — передайте json.Deterministic(true), что восстанавливает отсортированную keluarку для мап и структур. Модели из статьи Сравнение ORM используют теги json; эти теги продолжают работать в v2, но опция тега format была удалена во время эксперимента, а inline переименована в embed, поэтому прогнитеруйте определения моделей на наличие обоих перед миграцией. Для низкоуровневых задач — стриминг, по-токенная обработка, пользовательская обработка синтаксиса — сопровождающий пакет encoding/json/jsontext предоставляет конечный автомат Encoder/Decoder для JSON-текста.

uuid в stdlib: отказ от github.com/google/uuid

Go 1.27 добавляет uuid в стандартную библиотеку, реализовывая RFC 9562. API покрывает общие случаи:

id := uuid.New()    // в настоящее время эквивалентно NewV4
v7 := uuid.NewV7()  // сортируемое по времени, 48-битный таймстемп + случайность
u, err := uuid.Parse("550e8400-e29b-41d4-a716-446655440000")

github.com/google/uuid — второй по популярности Go-модуль, поэтому эта миграция важна при больших масштабах. Два API близки — типы являются значениями [16]byte, сравнимыми с помощью == и пригодными для использования как ключи мап, String(), MarshalText/UnmarshalText обеспечивают корректное преобразование — и проектом-источником готовятся shim’ы go:fix inline, чтобы go fix мог переписать вызовы uuid.NewV4() на стандартный пакет и удалить зависимость.

Интересное решение по внедрению связано с NewV7. UUID версии 7 встраивают миллисекундный таймстемп в старшие биты, поэтому значения сортируются в порядке создания (за исключением случаев, когда системные часы идут назад). Для первичных ключей баз данных это означает лучшую локальность B-деревьев, чем у случайных UUIDv4, и бесплатную сортировку вроде created_at прямо в идентификаторе — то же свойство, которое обсуждается в контексте ключей, сортируемых по времени, в мульти-тенантных моделях данных.

Изменения языка: генерические методы и другие

Генерические методы — самая востребованная языковая функция этого релиза: объявление метода теперь может содержать собственные параметры типов.

// Go 1.27: math/rand/v2 получил генерический метод наряду с функцией
func (r *Rand) N[Int intType](n Int) Int

Два ограничения сохраняют систему типов разрешимой: методы интерфейсов не могут объявлять параметры типов, и методы интерфейсов не могут быть реализованы генерическими методами. Наряду с этим, ключи литералов структур теперь могут быть любым валидным селектором поля (а не только именами полей верхнего уровня), и вывод типов функций обобщен на все контексты, где генерическая функция присваивается переменной соответствующего типа функции. Ни одно из этих изменений не ломает существующий код; они устраняют обходные пути — пакетные генерические вспомогательные функции и явные инстанции.

go fix получил модернизаторы для смежных задач очистки: atomictypes, embedlit, slicesbackward и unsafefuncs. Одно предостережение из практических лабораторий по обновлению: запускайте go fix -fix=atomictypes осознанно, а не массово на библиотеках, так как это может изменить типы пакетных переменных, на которые ссылаются другие пакеты. Модернизатор waitgroup был переименован в waitgroupgo; обратите внимание, что sync.WaitGroup.Go (из версии 1.25) уже покрывает большую часть того, что он обнаруживает, — см. паттерны ограниченной конкурентности о том, как он вписывается в остановку пулов воркеров.

Что незаметно ломается

Это те изменения, которые компилируются нормально, но все равно стоят день релиза:

• Имена символов функциональных литералов. Компилятор теперь генерирует более простые, независимые от инлайнинга имена для замыканий и может объединять идентичные функциональные литералы. Тесты, утверждающие имена символов в трейсбэках или профилях, упадут; код, сравнивающий указатели на код функций для равенства, раскрывается в больше случаев.
• Выравнивание gofmt. Исправление логики выравнивания по столбцам (ранее она варьировалась в зависимости от архитектуры CPU) перепечатывает небольшое количество уже отформатированных файлов. Ожидайте диффы только с пробелами в коммите gofmt ./... после обновления.
• go mod tidy переписывает go.mod. Для модулей с go 1.27, tidy теперь объединяет дублирующиеся блоки require не более чем в два блока (прямые, непрямые), сохраняя комментарии. Проверьте дифф вашего go.mod и разрешите любые остатки конфликтов слияния до коммита релиза, а не после.
• Метки трейсбэков. Трейсбэки для модулей с go 1.27 включают метки горутин runtime/pprof в заголовочной строке; отключите их с помощью GODEBUG=tracebacklabels=0, если метки содержат конфиденциальные данные.
• go tool trace привязывается к localhost. -http=:6060 теперь слушает только localhost; явно передавайте -http=0.0.0.0:6060, если вам нужен удаленный доступ (и помните, что порт профилирования на общем хосте — риск — см. рабочий процесс профилирования в продакшене для усиленной настройки).

Эксперименты, за которыми стоит следить

Два экспериментальных пакета вышли в 1.27, оба включаются с помощью GOEXPERIMENT=simd во время сборки:

• simd — портативный, независимый от размера вектора API (Int8s, Float32s, …), который маппится на аппаратные инструкции там, где они доступны. Поддерживает AVX/AVX2/AVX-512 на amd64, NEON на arm64 и WebAssembly SIMD. Стандартная библиотека уже использует этот механизм внутренне: реализация карт Swiss Table в Go от этого выигрывает.
• simd/archsimd — слой, специфичный для архитектуры, для кода, которому нужно знать ширину вектора.

С точки зрения криптографии, crypto/mldsa реализует пост-квантовую схему подписи ML-DSA из FIPS 204 в трех наборах параметров (MLDSA44, MLDSA65, MLDSA87), интегрирована в crypto/x509 и предлагается как схемы подписи TLS 1.3. Гибридный пост-квантовый обмен ключами теперь может быть принудительно включен через Config.CurvePreferences, даже если заданы fallback’ы GODEBUG tlsmlkem/tlssecpmlkem. Ни одно из них не является пунктом миграции сегодня, но оба формируют поверхность конфигурации TLS, в которую вырастут ваши сервисы.

Новые API, которые стоит внедрить сразу

Несколько добавлений решают повседневные проблемы и не стоят ничего:

// strings.CutLast / bytes.CutLast — замена танцам с LastIndex
before, after, found := strings.CutLast("a/b/c.tar.gz", ".")

// httptest.NewTestServer — фиктивная сеть в памяти, автоочистка
srv := httptest.NewTestServer(t, mux) // нет реального порта, нет defer srv.Close()

httptest.NewTestServer создает httptest.Server, базирующийся на в-памяти сети, а не на TCP-слушателе, и регистрирует собственный t.Cleanup. Его реальная польза — в паре с testing/synctest: HTTP-обмены выполняются в синтетическом времени, что делает тесты таймаутов и повторных попыток быстрыми и детерминированными — комбинация продемонстрирована в статье тестирование конкурентности с synctest.

Чек-лист обновления

Порядок важнее пунктов; каждый шаг предполагает, что предыдущий выполнен успешно.

Заключительные заметки

Сбои в Go 1.27 группируются вокруг краев, к которым большинство программ никогда не прикасаются — удаленные opt-out’ы GODEBUG, утверждения об именах символов, сжатые байтовые фикстуры — в то время как выигрыши приходят там, где живет каждая программа: более быстрый JSON, стандартные UUID, генерические методы. Чистое обновление — это в основном дисциплина: go build, затем go test, затем go fix, в этом порядке, с повышением строки go перед запуском тестов, а не после. Аварийный выход nojsonv2 и правило принятия asynctimerchan на финальном дефолте покупают время, но оба запланированы к исчезновению, поэтому рассматривайте это обновление как дедлайн для отложенных исправлений, унаследованных от 1.23–1.26.