Import path vs package name

1. Откуда путаница: импортируем одно, пишем другое

Когда вы только начинаете писать на Go, импорт выглядит как простая магия: написал import "fmt" — и можно звать fmt.Println. Но в какой-то момент вы увидите import "math/rand", а в коде внезапно будет rand.Intn(...). Или ещё веселее: вы захотите использовать и "math/rand", и "crypto/rand", и окажется, что оба пакета «в коде» называются rand.

Чтобы перестать «учить импорты наизусть» и начать уверенно читать чужой код, нужно разложить на две отдельные сущности:

• import path — строка в кавычках, по которой Go находит пакет;
• package name — имя, которым вы пользуетесь в коде как префиксом перед точкой ..

Дальше мы будем разбирать это на примерах из стандартной библиотеки и параллельно чуть-чуть улучшим наше учебное консольное приложение.

2. Import path: адрес, по которому Go ищет пакет

Import path — это то, что стоит в кавычках в import. Важная мысль: import path нужен компилятору и инструментам, а не вам «для красоты». Он отвечает на вопрос: «где лежит исходный код пакета, который я хочу подключить?».

Как выглядит import path

Вот типичные import path в стандартной библиотеке:

• "fmt"
• "strconv"
• "strings"
• "math/rand"
• "crypto/rand"
• "net/http"
• "encoding/json"

Обратите внимание: иногда это одно слово ("fmt"), а иногда это путь с / ("math/rand"). Это не означает «папка в вашей системе прямо сейчас» (хотя исторически и организационно это связано). В вашей голове import path должен жить как «уникальный адрес пакета».

Зачем этот адрес должен быть уникальным

В Go есть идея, что один import path должен однозначно указывать на один смысловой пакет. Иначе вы не сможете понять, что именно подключено и почему оно работает именно так. Вокруг этого сформировалось правило совместимости импорта: если меняем пакет несовместимо, обычно меняем и import path (в модулях это стало ещё более заметно).

Мы не уходим сегодня в Go Modules, версии и команды — нам важна только идея: import path — это идентификатор зависимости, а не «имя переменной».

Мини-схема: что делает Go, когда видит import

flowchart LR
    A["Файл main.go"] --> B["import 'math/rand'"]
    B --> C["Go находит пакет по import path"]
    C --> D["Пакет объявляет своё имя: package rand"]
    D --> E["В коде мы пишем rand.Intn(...)"]

Ключевой момент: import path участвует в поиске пакета, а то, как вы к нему обращаетесь в коде, определяется именем пакета, а не строкой пути.

3. Package name: имя, которым вы пишете pkg.Something

Package name — это то, что стоит в исходниках пакета в строке package .... Именно это имя становится «префиксом» перед точкой в вашем коде.

Например, когда вы пишете:

fmt.Println("hi")

fmt — это package name, а Println — экспортированная функция внутри пакета.

Важная деталь, которая ломает мозг один раз

Package name не обязан совпадать с import path. Чаще всего совпадает с последним сегментом пути, и поэтому кажется, что это одно и то же. Но вообще это разные сущности:

• import path: "math/rand"
• package name: rand

То есть строка "math/rand" — это не то, что вы пишете слева от точки.

Таблица: разница на ладони

4. Примеры из стандартной библиотеки

Сейчас сделаем несколько небольших примеров (по 5–10 строк), чтобы вы натренировали зрение: увидел import "..." — понял, что это адрес; увидел something.X — понял, что something это package name (или алиас, но алиасы подробно будут отдельной темой).

Пример: math/rand → rand

package main

import (
	"fmt"
	"math/rand"
)

func main() {
	fmt.Println(rand.Intn(10)) // например: 7
}

Здесь важно проговорить вслух: мы импортировали по пути "math/rand", но в коде используем имя пакета rand.

Пример: encoding/json → json

package main

import (
	"encoding/json"
	"fmt"
)

func main() {
	b, _ := json.Marshal(map[string]int{"tasks": 3})
	fmt.Println(string(b)) // {"tasks":3}
}

Мы ещё не обсуждаем глубоко map и JSON как тему (это будет позже), но пример показывает главное: import path — "encoding/json", а package name — json. И именно json появляется слева от точки.

Пример: net/http → http

package main

import (
	"fmt"
	"net/http"
)

func main() {
	fmt.Println(http.MethodGet) // GET
}

Опять: import path "net/http", в коде http.MethodGet.

Почему обычно всё совпадает

Фраза, которая спасает от будущих паник: в Go очень много держится на соглашениях, и одно из них — «package name обычно совпадает с последним сегментом import path».

Это удобно по трём причинам.

• Код проще читать: увидел "encoding/json" — ожидаешь json.*.
• IDE и инструменты автоматом подставляют нужные импорты.
• Человеку не приходится запоминать лишние соответствия.

Но важно оставаться в реальности: это всё ещё два разных механизма. И когда вы встретите код, где package name «неожиданное» (или конфликтует), вы не должны чувствовать, что мир сломался. Мир не сломался — просто вы перестали жить в примерах для новичков.

Мини-проблема: crypto/rand и math/rand

Вот тут начинается самое интересное, потому что это практически идеальная демонстрация «import path vs package name».

• "math/rand" — генератор псевдослучайных чисел (быстро, удобно, но не для криптографии).
• "crypto/rand" — криптографически стойкие случайные байты (медленнее, зато подходит для ключей и токенов).

И угадайте, как называются пакеты в коде? Оба — rand.

Попробуем наивно импортировать оба:

package main

import (
	"crypto/rand"
	"math/rand"
)

func main() {}

Такой код не соберётся, потому что в одном файле нельзя иметь два пакета с одинаковым именем импорта (а имя импорта по умолчанию — это package name). То есть import path разные, а package name одинаковое — конфликт.

И это важная мысль: конфликт происходит на уровне package name, потому что именно им вы пользуетесь в коде (rand.Something), и компилятору нужно однозначно понимать, какой rand вы имеете в виду.

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

5. Мини-проект StudyBuddy: осознанные импорты

Чтобы тема не осталась теорией, давайте продолжим нашу учебную консольную программу. Пусть она называется StudyBuddy: маленький помощник, который спрашивает имя и количество решённых задач, а потом печатает короткий отчёт и «мотивационную фразу».

Нам понадобятся пакеты:

• fmt для ввода/вывода,
• strconv — мы уже умеем, но здесь можно и без него,
• math/rand и time — чтобы выбрать случайную фразу.

Шаг: каркас и понятные импорты

package main

import (
	"fmt"
	"math/rand"
	"time"
)

func main() {
	fmt.Println("StudyBuddy started") // StudyBuddy started
	_ = rand.Intn(10)
	_ = time.Now()
}

Обратите внимание: "math/rand" — это import path, а rand.Intn — package name rand. То же самое с "time" → time.Now.

Шаг: функция, которая возвращает фразу

Мы уже умеем писать функции, поэтому сделаем аккуратно:

package main

import (
	"math/rand"
)

func pickPhrase() string {
	phrases := []string{"Держись!", "Ты молодец!", "Ещё чуть-чуть!"}
	return phrases[rand.Intn(len(phrases))]
}

Если вы ещё не проходили срезы ([]string) в вашем потоке обучения — воспринимайте это как «мини-демо» и не пугайтесь. Можно заменить на switch и три варианта, но тогда пример будет менее живым. Главная мысль всё равно про rand.Intn: имя rand приходит из package name.

Шаг: time как seed, чтобы не получать одно и то же

package main

import (
	"math/rand"
	"time"
)

func initRandom() {
	rand.Seed(time.Now().UnixNano())
}

Да, это уже похоже на «магические заклинания», но зато очень наглядно показывает, что вы берёте маленькие кусочки функциональности из разных пакетов. И каждый кусочек подключается через import path, а используется через package name.

Шаг: собираем вместе, без перегруза

package main

import (
	"fmt"
	"math/rand"
	"time"
)

func main() {
	rand.Seed(time.Now().UnixNano())

	var name string
	var solved int

	fmt.Print("Name and solved: ")
	fmt.Scan(&name, &solved)

	fmt.Printf("%s solved %d tasks. %s\n", name, solved, pickPhrase())
}

Если вы запустите и введёте:

Name and solved: Ana 5

то получите что-то вроде:

// Ana solved 5 tasks. Ты молодец!

Тут мы «размазали» ответственность по пакетам. И это нормально: Go как раз и предполагает, что вы чаще «склеиваете» программу из пакетов, чем пишете всё с нуля.

Откуда берутся import path своих пакетов

В стандартной библиотеке import path короткие и фиксированные: "fmt", "strings", "net/http". Но в реальных проектах вы увидите импорты вида "github.com/someone/project/pkg/...". Это не «мода» и не «понты», а способ сделать import path уникальным в мире.

Исторически и концептуально это связано с тем, что import path должен однозначно идентифицировать пакет, а при развитии экосистемы появились правила совместимости импортов и механизмы управления зависимостями. В рассуждениях о модулях и «уникальности пакетов» эта идея звучит прямо: если вы меняете несовместимо — меняйте путь, иначе вы ломаете сборки и людей.

Сегодня нам достаточно держать в голове простую картинку: у ваших пакетов import path начинается с «префикса проекта», а package name внутри них — это то, что написано в package ....

6. Типичные ошибки при работе с import path и package name

Ошибка №1: думать, что import "math/rand" означает, что в коде надо писать math/rand.Intn.
Это очень человеческая ошибка: мозг видит путь и хочет использовать его как имя. Но Go так не работает: слева от точки всегда стоит идентификатор (package name или alias), а не строковый путь. Поэтому rand.Intn, а не «путь с косой чертой».

Ошибка №2: путать «что в кавычках» и «что слева от точки» и пытаться переименовывать пакет, меняя строку пути.
Иногда новичок думает: «хочу, чтобы пакет назывался random — сейчас напишу import "math/random"». Но import path должен указывать на реально существующий пакет. Если такого пути нет — компилятор не волшебник. Переименовывание делается другим механизмом (мы ещё дойдём до него), а не выдумыванием новых путей.

Ошибка №3: не понимать, почему конфликтуют "crypto/rand" и "math/rand".
Кажется: «пути разные — чего компилятор придирается?» А компилятор придирается к тому, что в коде оба пакета будут называться одинаково: rand. Конфликт именно в package name, а не в import path. Когда вы это понимаете, проблема перестаёт быть мистикой и становится обычной инженерной задачей.

Ошибка №4: считать, что package name всегда равен последней части import path.
В стандартной библиотеке это почти всегда так, поэтому мозг привыкает. Но это соглашение, а не закон. Правильная привычка чтения Go-кода такая: import path нужен, чтобы найти пакет; как он называется в коде — определяется package ... внутри него (или alias’ом импорта).

Ошибка №5: «а зачем вообще пакеты, можно же всё в одном файле».
Можно — пока проект маленький. Но как только появляется больше логики, больше функций и больше ответственности, пакеты становятся способом держать порядок. Они не «усложняют жизнь», они защищают вас от ситуации «всё связано со всем, и любая правка ломает всё». Сначала кажется, что пакеты — бюрократия. Потом вы пишете проект на 20 файлов — и начинаете уважать бюрократию.