Флаги командной строки в Go: что нужно знать до начала

Что получится и сколько времени займёт

К концу этого гайда у вас будет CLI-утилита на Go, которая принимает строковые, числовые и булевы флаги, выводит справку по -help и корректно сообщает об ошибках. Весь путь — от пустого файла до рабочего бинарника — занимает около десяти минут. Код написан для Go 1.22, но пакет flag стабилен начиная с Go 1.0, поэтому примеры сработают и на более ранних версиях.

Что нужно иметь до начала

• Установленный Go версии 1.18 или выше (проверьте командой go version).
• Любой текстовый редактор или IDE с поддержкой Go — VS Code с расширением Go, GoLand, даже Vim с vim-go.
• Терминал, в котором вы можете запустить go run.
• Инициализированный модуль: выполните go mod init cliflags в пустой директории.

Шаг 1 — объявляем флаги

Пакет flag предлагает два способа объявить флаг: функцию, возвращающую указатель, и функцию, записывающую значение по переданному указателю. Начнём с первого — он короче.

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

package main

import (
	"flag"
	"fmt"
)

func main() {
	// Строковый флаг: имя, значение по умолчанию, описание
	host := flag.String("host", "localhost", "адрес сервера")

	// Числовой флаг
	port := flag.Int("port", 8080, "порт сервера")

	// Булев флаг
	verbose := flag.Bool("verbose", false, "подробный вывод")

	// Обязательный вызов — без него флаги не прочитаются
	flag.Parse()

	fmt.Printf("host=%s port=%d verbose=%t\n", *host, *port, *verbose)
}

Проверка: запустите в терминале:

go run main.go -host=example.com -port=3000 -verbose

Должна появиться строка:

host=example.com port=3000 verbose=true

Если вывод совпал — шаг пройден.

Почему указатели

flag.String, flag.Int и flag.Bool возвращают *string, *int, *bool. Значение заполняется только после вызова flag.Parse(), поэтому обращаться к *host до парсинга бессмысленно — там будет значение по умолчанию, а не то, что передал пользователь.

Шаг 2 — альтернативный способ: запись по адресу

Если вам удобнее работать с обычными переменными, а не разыменовывать указатели, используйте flag.StringVar, flag.IntVar, flag.BoolVar:

package main

import (
	"flag"
	"fmt"
)

func main() {
	var host string
	var port int
	var verbose bool

	flag.StringVar(&host, "host", "localhost", "адрес сервера")
	flag.IntVar(&port, "port", 8080, "порт сервера")
	flag.BoolVar(&verbose, "verbose", false, "подробный вывод")

	flag.Parse()

	fmt.Printf("host=%s port=%d verbose=%t\n", host, port, verbose)
}

Проверка: результат тот же, но host — уже string, а не *string.

Шаг 3 — позиционные аргументы после флагов

Всё, что идёт после последнего распознанного флага (или после --), попадает в flag.Args(). Это полезно, когда утилита принимает и флаги, и список файлов:

flag.Parse()
files := flag.Args() // []string с оставшимися аргументами
fmt.Println("файлы:", files)

Проверка:

go run main.go -verbose file1.txt file2.txt

Вывод должен содержать файлы: [file1.txt file2.txt].

Важный нюанс: пакет flag прекращает разбор флагов при первом аргументе, который не начинается с дефиса. Поэтому go run main.go file1.txt -verbose не включит verbose — флаг окажется в flag.Args(). Это принципиальное отличие от GNU-стиля разбора, где флаги и аргументы можно смешивать.

Шаг 4 — обработка ошибок и справка

По умолчанию, если пользователь передаст неизвестный флаг или флаг с невалидным значением (например, буквы вместо числа для -port), программа напечатает ошибку, покажет справку и завершится с кодом 2. Это поведение управляется через flag.CommandLine.ErrorHandling.

Три варианта обработки ошибок:

Чтобы переопределить текст справки, назначьте свою функцию на flag.Usage:

flag.Usage = func() {
	fmt.Fprintf(flag.CommandLine.Output(),
		"Использование: myapp [флаги] [файлы...]\n\nФлаги:\n")
	flag.PrintDefaults()
}

Проверка: запустите go run main.go -help — должен появиться ваш текст, а не стандартный.

Шаг 5 — собственный тип флага

Пакет flag позволяет создать флаг любого типа. Достаточно реализовать интерфейс flag.Value с двумя методами: String() string и Set(string) error. Пример — флаг, принимающий список значений через запятую:

package main

import (
	"flag"
	"fmt"
	"strings"
)

// stringList реализует flag.Value для списка строк
type stringList []string

func (s *stringList) String() string {
	return strings.Join(*s, ",")
}

func (s *stringList) Set(value string) error {
	*s = strings.Split(value, ",")
	return nil
}

func main() {
	var tags stringList
	flag.Var(&tags, "tags", "теги через запятую: go,cli,tools")
	flag.Parse()

	fmt.Printf("теги: %v (всего %d)\n", tags, len(tags))
}

Проверка:

go run main.go -tags=go,cli,tools

Ожидаемый вывод: теги: [go cli tools] (всего 3).

Если не получилось

1. Флаги не читаются, значения по умолчанию. Убедитесь, что flag.Parse() вызывается до обращения к значениям. Это самая частая ошибка — объявить флаги и забыть вызвать парсинг.
2. flag provided but not defined: -host. Флаг объявлен после вызова flag.Parse(), либо опечатка в имени. Все объявления должны идти до Parse().
3. invalid value "abc" for flag -port: parse error. Пользователь передал строку в числовой флаг. Это штатное поведение — программа покажет ошибку и справку.
4. Флаг -verbose не работает после имени файла. Пакет flag прекращает разбор при первом не-флаговом аргументе. Флаги должны идти перед позиционными аргументами.
5. go run main.go — ошибка компиляции. Проверьте, что файл начинается с package main и содержит func main(). Убедитесь, что go mod init выполнен в текущей директории.

Сноска: CLI (Command Line Interface) — интерфейс командной строки, способ взаимодействия с программой через текстовые команды в терминале, без графического интерфейса.

Что делать дальше

Пакет flag покрывает базовые сценарии, но у него есть ограничения: нет поддержки подкоманд (вроде git commit), нет автоматического чтения переменных окружения, нет GNU-стиля с двойным дефисом (--host) и коротких однобуквенных флагов (-h). Для простых утилит этого достаточно. Если нужны подкоманды или сложная структура — изучите документацию сторонних пакетов вроде cobra или urfave/cli; но начинайте с flag, чтобы понимать, что именно эти библиотеки абстрагируют.

Следующий практический шаг: напишите утилиту, которая принимает флаг -config с путём к файлу конфигурации и переопределяет отдельные параметры флагами. Это классический паттерн «конфиг + флаги», и пакет flag справляется с ним без сторонних зависимостей.