Go modules: go mod init, tidy и зависимости

Go modules — это система, через которую Go понимает имя проекта, версию языка и внешние зависимости. Если вы уже запускали go mod init, то видели файл go.mod. В этом уроке разберем его спокойно: создадим модуль, добавим пакет, посмотрим на go.sum и поймем, зачем нужна команда go mod tidy

Главная цель: перестать воспринимать go.mod как служебный шум. Это карта вашего проекта для инструментов Go

Что получится в конце

Мы создадим проект, подключим внешний пакет для UUID и выведем идентификатор задачи:

task id: 6f1f4e30-7c0f-4f2a-8c1c-18d0a80c4fb7

Конкретный UUID будет другим. Важнее, что проект научится использовать внешнюю зависимость

Создаем модуль

mkdir go-modules-demo
cd go-modules-demo
go mod init example.com/go-modules-demo

После этого появится go.mod:

module example.com/go-modules-demo

go 1.26

Версия Go у вас может отличаться. Строка module задает путь модуля. Для учебного проекта нормально использовать example.com/.... Для реального открытого модуля обычно указывают путь репозитория, например github.com/user/project

Добавляем первый файл

Создайте main.go:

package main

import "fmt"

func main() {
    fmt.Println("Go modules работают")
}

Запустите:

go run .

Пока внешних зависимостей нет, go.mod остается коротким

Подключаем внешний пакет

Добавим пакет github.com/google/uuid:

go get github.com/google/uuid

Теперь измените main.go:

package main

import (
    "fmt"

    "github.com/google/uuid"
)

func main() {
    taskID := uuid.NewString()
    fmt.Println("task id:", taskID)
}

Запустите:

go run .

Go скачает зависимость, соберет проект и выведет UUID

Что изменилось в go.mod

После go get в go.mod появится строка примерно такого вида:

require github.com/google/uuid v1.6.0

Версия может быть другой. Смысл строки: проект требует конкретный модуль в конкретной версии

Go modules помогают делать сборку повторяемой. Когда другой разработчик скачает проект и запустит его, Go будет понимать, какие зависимости нужны

Зачем нужен go.sum

Рядом появится go.sum. Его часто путают с lock-файлом из других экосистем, но лучше воспринимать его как файл с контрольными суммами модулей. Он помогает Go проверять, что скачанные зависимости совпадают с ожидаемыми

Не удаляйте go.sum просто потому, что он выглядит непонятно. В обычном проекте его хранят в репозитории вместе с go.mod

Что делает go mod tidy

Команда:

go mod tidy

приводит зависимости в порядок: добавляет недостающие и удаляет лишние

Проверим. Удалите использование uuid из main.go:

package main

import "fmt"

func main() {
    fmt.Println("без внешней зависимости")
}

Теперь выполните:

go mod tidy

Если пакет github.com/google/uuid больше нигде не используется, Go уберет его из go.mod

Практическое правило: после заметного изменения импортов запускайте go mod tidy, особенно перед коммитом или публикацией

go get и версии

Чтобы обновить зависимость, используют go get с версией:

go get github.com/google/uuid@latest

или конкретно:

go get github.com/google/uuid@v1.6.0

Новичку не нужно сразу изучать все тонкости semantic versioning, pseudo-versions и replace. Для первых проектов достаточно понимать: go.mod хранит требования, go get меняет зависимости, go mod tidy чистит список

Как читать module path

Строка:

module example.com/go-modules-demo

не обязана быть настоящим сайтом для локального урока. Но в опубликованных модулях путь важен: он показывает, откуда модуль импортируется

Например, если модуль лежит на GitHub, путь обычно похож на:

module github.com/dinar/go-api

Тогда другой проект сможет импортировать пакеты из него по этому пути

Частые ошибки

go.mod file not found. Вы запускаете команду не в папке модуля. Перейдите в проект или выполните go mod init

package is not in std. Часто значит, что импорт написан неверно или зависимость не добавлена. Проверьте путь импорта и выполните go mod tidy

module declares its path as …, but was required as … Путь модуля в go.mod не совпадает с тем, как вы его импортируете. Это бывает при переезде репозитория или неправильном module path

Случайно удалили go.sum. Обычно можно восстановить через go mod tidy, но лучше не удалять его вручную без причины

Что может быть еще интересно по этой теме

Нужно ли запускать go mod init в каждом проекте? Да, если это отдельный Go-проект. Один модуль — одна самостоятельная область зависимостей

Можно ли писать Go без внешних зависимостей? Да. Стандартная библиотека Go сильная, особенно для HTTP, JSON, файлов и тестов. Но реальные проекты часто подключают драйверы баз данных и вспомогательные пакеты

Чем go get отличается от go install? В современных версиях Go go get управляет зависимостями модуля, а go install package@version чаще используют для установки инструментов

Нужно ли коммитить go.mod и go.sum? Да. Эти файлы нужны, чтобы проект собирался предсказуемо на другой машине

Что открыть дальше

• HTTP server на Go: первый API без фреймворка — пример проекта, который пока обходится стандартной библиотекой.
• Go и PostgreSQL: мини-API с базой данных — там modules понадобятся для драйвера базы данных.
• Goroutines и channels: первая параллельность в Go — отдельная сильная сторона языка.
• Ошибки в Go: error, panic и recover без суеты — полезно для работы с внешними пакетами и зависимостями.