Модуль aconf

Назначение

Пакет aconf загружает и валидирует конфигурацию сервиса из переменных среды окружения.

API

Пакет предоставляет метод для загрузки конфигурации из переменных окружения в структуру, содержащую корректные теги.

Также есть метод для загрузки переменных окружения из файла (преимущественно для тестирования) и метод генерации дефолтного .env файла непосредственно из исходника на Go.

В cmd есть утилита,которая парсит исходник на Go и создает список переменных окружения для сервиса.

func Load(v any) error

Load принимает в качестве единственного аргумента указатель на структуру, в поля которой нужно считать значения из переменных окружения. О том, какие теги задавать структуре, чтобы переменные окружения корректно считывались - см. ниже.

После считывания переменных окружения происходит валидация структуры библиотекой validator. Чтобы поля структуры конфигурации провалидировались, нужно добавить к ним теги validate:. Подробности допустимого синтаксиса в тегах validate: см. по ссылке выше.

Важно обратить внимание, что если методу Load передать саму структуру (а не указатель) или указатель на другой тип, не являющийся структурой (slice, например), вернется ошибка.

func PreloadEnvsFile(path string) error

PreloadEnvsFile принимает путь до файла, где должны находиться строки c переменными окружения, и задает их в текущем окружении. Может быть полезно для тестов. Если не указать путь до файла, будет предпринята попытка прочитать файл .env из текущей директории.

Пример содержимого файла:

FIELD_A_STRING=goodbye
FIELD_A_INTEGER=10
SLICE='13,42,1984'
MAP='hello:1,world:2'

func ConfFileToEnvSlice(filename, structname string) ([]string, error)

ConfFileToEnvSlice принимает имя файла исходного текста на Go и имя структуры по тегам которой нужно сгенерировать переменные окружения для конфигурации. Возвращает массив строк, в которых переменным окружения присвоены значения из тега env:, указанные в default, например для env:"MY_ENV, default=1" вернется строка MY_ENV=1. Если default не указан, то вернется строка, указывающая на тип, который должен быть задан для переменной, например MY_ENV=int.

Добавление тегов к структуре конфигурации

Для корректной записи значений переменных окружения в соответствующие поля структуры конфигурации структуре нужно добавить теги env: к нужным полям.

Содержимое тега должно отвечать следующим требованиям:

Первое значение - имя переменной окружения, из которой читаются данные для соответствующего поля. Если имя отсутствует и отсутствует директива prefix (см. ниже) - это ошибка.
Для вложенной структуры можно не указывать имя переменной, но можно (не обязательно) указать директиву prefix=XXX_. В этом случае значение для полей вложенной структуры будет читаться из переменной XXX_NAME, где NAME - имя переменной окружения, указанное в теге env: поля вложенной структуры.
В тэге можно указать значение по умолчанию для поля с помощью директивы default. Например, env:"SOME_ENV, default=42"

Разберем пример.

type Config struct {
    Address string  		`env:"ADDR" validate:"required,hostname_port"`
	DB1 DB 					`env:", prefix=DB1_"`
	DB2 DB					`env:", prefix=DB2_"`
	Workers Workers
}

type DB struct {
	Host    string `env:"HOST" validate:"required"`
	Port    string `env:"PORT" validate:"required"`
}

type Workers struct {
	Pub int `env:"WORKERS_PUB, default=5"`
	Sub int `env:"WORKERS_SUB, default=5"`
}

Для поля Address значение будет считано из переменной окружения ADDR и будет произведена валидация, что считанное значение можно интерпретировать как host:port.

Для полей DB1 и DB2 нет имени переменной, но есть префиксы DB1_ и DB2_, поэтому значение для Config.DB1.Host будет читаться из переменной DB1_HOST, а значение для Config.DB2.Host - из переменной DB2_HOST, то есть произойдет конкатенация префиксов и мен переменных, указанных в тегах env: для полей вложенной структуры.

При этом для поля Workers в конфиге не указан prefix, поэтому значения для полей вложенной структуры Workers будут читаться из переменных WORKERS_PUB и WORKERS_SUB без префикса, то есть используются непосредственно имена,указанные в тэге env: вложенной структуры.

Подробнее про допустимый синтаксис в тэге env: можно почитать в документации репозитория go-envconfig.

Определение среды выполнения

Модуль также содержит функции для проверки, в какой среде запущен сервис: IsProduction(), IsStaging(), IsDevelopment(), IsLocal()

Если при запуске не была указана переменная GO_ENVIRONMENT, то по умолчанию среда будет Local, если переменная была, то проверяется её название (production, staging, development, local соответственно, регистр не важен)

Для получения текущей среды выполнения в пакете есть функция GetEnvironment()

Генерация .env файла из исходного кода на Go

В пакете присутствует утилита генерации .env файла из исходника на Go.

Она читает исходный текст на Go, ищет в нем структуру по заданному имени, обходит ее поля и генерирует значение переменных для полей структуры (включая вложенные структуры), где был тэг env. Если в тэге env указано значение по умолчанию (default='xxx'), то используется это значение без изменений. Если значение по умолчанию не указано, то будет подставлено имя типа поля (например, int, string etc.).

Как это работает:

$go install git.astralnalog.ru/utils/aconf/v3/cmd/[email protected] $conf2env -struct testConf -file my_config.go

FIELD_A_INTEGER=1
FIELD_A_STRING=hello
FIELD_B_INTEGER=1
FIELD_B_STRING=hello
MAP='a:1,b:2'
SLICE='1,2,3'

# README