CyberGocybergodev/env

Русский

简体中文
English
한국어
日本語

Русский

简体中文
English
한국어
日本語

Тема

Русский

简体中文
English
한국어
日本語

Config API ​

Полный справочник параметров конфигурации структуры Config.

Определение структуры ​

Config использует вложенные структуры для организации конфигурации, при этом обеспечивая обратную совместимость через продвижение полей Go:

go
type Config struct {
    FileConfig       // Поведение загрузки файлов
    ValidationConfig // Валидация ключей и значений
    LimitsConfig     // Ограничения размера и количества
    JSONConfig       // Параметры разбора JSON
    YAMLConfig       // Параметры разбора YAML
    ParsingConfig    // Общее поведение разбора
    ComponentConfig  // Пользовательские компоненты и расширенные настройки
}

Два способа доступа:

go
// Старый способ (через продвижение полей, всё ещё действителен)
cfg.Filenames = []string{".env"}
cfg.MaxFileSize = 1024

// Новый способ (рекомендуется, более понятный)
cfg.FileConfig.Filenames = []string{".env"}
cfg.LimitsConfig.MaxFileSize = 1024

Вложенные структуры ​

go
// FileConfig управляет поведением загрузки файлов
type FileConfig struct {
    Filenames         []string // Список файлов для загрузки
    FailOnMissingFile bool     // Возвращать ли ошибку при отсутствии файла
    OverwriteExisting bool     // Перезаписывать ли существующие переменные окружения
    AutoApply         bool     // Автоматически применять к os.Environ
}

// ValidationConfig управляет валидацией ключей и значений
type ValidationConfig struct {
    RequiredKeys   []string       // Список обязательных имён ключей
    AllowedKeys    []string       // Белый список разрешённых ключей
    ForbiddenKeys  []string       // Дополнительный список запрещённых ключей
    KeyPattern     *regexp.Regexp // Шаблон соответствия имени ключа
    ValidateValues bool           // Проверять безопасность значений
    ValidateUTF8   bool           // Валидация значений как допустимый UTF-8
}

// LimitsConfig управляет ограничениями размера и количества
type LimitsConfig struct {
    MaxFileSize       int64 // Максимальное количество байт на файл
    MaxVariables      int   // Максимальное количество переменных на файл
    MaxLineLength     int   // Максимальная длина строки
    MaxKeyLength      int   // Максимальная длина имени ключа
    MaxValueLength    int   // Максимальная длина значения
    MaxExpansionDepth int   // Максимальная глубина подстановки переменных
}

// JSONConfig управляет поведением разбора JSON
type JSONConfig struct {
    JSONNullAsEmpty    bool // null преобразуется в пустую строку
    JSONNumberAsString bool // числа преобразуются в строки
    JSONBoolAsString   bool // логические значения преобразуются в строки
    JSONMaxDepth       int  // максимальная глубина вложенности
}

// YAMLConfig управляет поведением разбора YAML
type YAMLConfig struct {
    YAMLNullAsEmpty    bool // null/~ преобразуется в пустую строку
    YAMLNumberAsString bool // числа преобразуются в строки
    YAMLBoolAsString   bool // логические значения преобразуются в строки
    YAMLMaxDepth       int  // максимальная глубина вложенности
}

// ParsingConfig управляет общим поведением разбора
type ParsingConfig struct {
    AllowExportPrefix bool // Разрешить синтаксис export KEY=value
    AllowYamlSyntax   bool // Разрешить значения в стиле YAML
    ExpandVariables   bool // Раскрывать ссылки ${VAR}
}

// ComponentConfig — пользовательские компоненты и расширенные настройки
type ComponentConfig struct {
    CustomValidator Validator        // Пользовательский валидатор ключей/значений
    CustomExpander  VariableExpander // Пользовательский раскрыватель переменных
    CustomAuditor   AuditLogger      // Пользовательский регистратор аудита
    FileSystem      FileSystem       // Пользовательская файловая система (для тестирования)
    AuditHandler    AuditHandler     // Пользовательский обработчик аудита
    AuditEnabled    bool             // Включить аудитный лог
    Prefix          string           // Обрабатывать только переменные с этим префиксом
}

Поля конфигурации ​

Обработка файлов ​

Эти поля управляют поведением загрузки файлов.

Filenames []string ​

Список путей к файлам для загрузки. По умолчанию [".env"].

go
cfg.Filenames = []string{".env", ".env.local"}

FailOnMissingFile bool ​

Возвращать ли ошибку при отсутствии файла. По умолчанию false (тихий пропуск).

go
cfg.FailOnMissingFile = true  // Возвращать ошибку при отсутствии файла

OverwriteExisting bool ​

Перезаписывать ли существующие переменные окружения. По умолчанию false.

go
cfg.OverwriteExisting = true  // Разрешить перезапись

AutoApply bool ​

Автоматически применять к системному окружению (os.Environ) после загрузки. По умолчанию false.

go
cfg.AutoApply = true  // Автоматически применять после загрузки

Внимание

Пакетная функция Load() автоматически устанавливает AutoApply = true. При создании Loader через New() необходимо установить вручную.

Подстановка переменных ​

ExpandVariables bool ​

Включает подстановку переменных с синтаксисом ${VAR}. По умолчанию true.

go
cfg.ExpandVariables = true

Поддерживаемый синтаксис подстановки:

СинтаксисОписание
${VAR}Ссылка на переменную
${VAR:-default}Использовать значение по умолчанию, если переменная не существует или пуста
${VAR:=default}Установить значение по умолчанию, если переменная не существует или пуста
${VAR:?error}Вернуть ошибку, если переменная не существует или пуста

Ограничения безопасности ​

MaxFileSize int64 ​

Максимальное количество байт на файл. По умолчанию 2MB, жёсткий предел 100MB.

go
cfg.MaxFileSize = 10 * 1024 * 1024 // 10 MB
ПараметрПо умолчаниюЖёсткий предел
MaxFileSize2MB (2097152)100MB

MaxLineLength int ​

Максимальная длина строки. По умолчанию 1024, жёсткий предел 64KB.

go
cfg.MaxLineLength = 2048
ПараметрПо умолчаниюЖёсткий предел
MaxLineLength102465536 (64KB)

MaxKeyLength int ​

Максимальная длина имени ключа. По умолчанию 64, жёсткий предел 1024.

go
cfg.MaxKeyLength = 128
ПараметрПо умолчаниюЖёсткий предел
MaxKeyLength641024

MaxValueLength int ​

Максимальная длина значения. По умолчанию 4096, жёсткий предел 1MB.

go
cfg.MaxValueLength = 8192
ПараметрПо умолчаниюЖёсткий предел
MaxValueLength40961048576 (1MB)

MaxVariables int ​

Максимальное количество переменных на файл. По умолчанию 500, жёсткий предел 10000.

go
cfg.MaxVariables = 1000
ПараметрПо умолчаниюЖёсткий предел
MaxVariables50010000

MaxExpansionDepth int ​

Максимальная глубина подстановки переменных. По умолчанию 5, жёсткий предел 20.

go
cfg.MaxExpansionDepth = 10
ПараметрПо умолчаниюЖёсткий предел
MaxExpansionDepth520

Валидация ключей ​

KeyPattern *regexp.Regexp ​

Пользовательский шаблон соответствия имени ключа. По умолчанию nil (используется быстрая побайтовая валидация).

Оптимизация производительности

Значение nil включает быструю побайтовую валидацию (примерно 10-кратное повышение производительности). Правило валидации по умолчанию: начинается с буквы, содержит только буквы, цифры и подчёркивания.

go
import "regexp"

// Пользовательский шаблон
cfg.KeyPattern = regexp.MustCompile(`^[A-Z][A-Z0-9_]*$`)

AllowedKeys []string ​

Белый список разрешённых ключей. Если пуст, разрешены все ключи (кроме запрещённых).

go
cfg.AllowedKeys = []string{"APP_NAME", "APP_VERSION", "PORT"}

ForbiddenKeys []string ​

Дополнительный список запрещённых ключей (добавляется к встроенным).

go
cfg.ForbiddenKeys = []string{"CUSTOM_DANGEROUS_VAR"}

Встроенные запрещённые ключи

Библиотека встроенно запрещает PATH, LD_PRELOAD, LD_LIBRARY_PATH, DYLD_INSERT_LIBRARIES и другие системно-важные переменные. Подробнее в Константы и ошибки.

RequiredKeys []string ​

Список обязательных ключей. Проверяется при вызове Validate().

go
cfg.RequiredKeys = []string{"DB_HOST", "API_KEY"}

ValidateValues bool ​

Проверка безопасности значений (управляющие символы, нулевые байты и т.д.). По умолчанию true.

Рекомендация по безопасности

Рекомендуется всегда держать включённым. Отключайте только в особых случаях (например, при необходимости хранения значений с управляющими символами).

go
cfg.ValidateValues = true  // Включено по умолчанию

ValidateUTF8 bool ​

Проверяет, является ли значение допустимым UTF-8. По умолчанию false.

go
cfg.ValidateUTF8 = true  // Включить UTF-8 валидацию

Параметры разбора ​

AllowExportPrefix bool ​

Разрешает синтаксис export KEY=value. По умолчанию true.

go
cfg.AllowExportPrefix = false  // Запретить префикс export

AllowYamlSyntax bool ​

Разрешает синтаксис в стиле YAML (KEY: value). По умолчанию false.

go
cfg.AllowYamlSyntax = true

Параметры JSON ​

JSONNullAsEmpty bool ​

Значение JSON null преобразуется в пустую строку. По умолчанию true.

go
cfg.JSONNullAsEmpty = true

JSONNumberAsString bool ​

Числа JSON преобразуются в строки. По умолчанию true.

go
cfg.JSONNumberAsString = true

JSONBoolAsString bool ​

Логические значения JSON преобразуются в строки. По умолчанию true.

go
cfg.JSONBoolAsString = true

JSONMaxDepth int ​

Максимальная глубина вложенности JSON. По умолчанию 10.

go
cfg.JSONMaxDepth = 20

Параметры YAML ​

YAMLNullAsEmpty bool ​

Значения YAML null/~ преобразуются в пустую строку. По умолчанию true.

go
cfg.YAMLNullAsEmpty = true

YAMLNumberAsString bool ​

Числа YAML преобразуются в строки. По умолчанию true.

go
cfg.YAMLNumberAsString = true

YAMLBoolAsString bool ​

Логические значения YAML преобразуются в строки. По умолчанию true.

go
cfg.YAMLBoolAsString = true

YAMLMaxDepth int ​

Максимальная глубина вложенности YAML. По умолчанию 10.

go
cfg.YAMLMaxDepth = 15

Аудит ​

AuditEnabled bool ​

Включает аудитный лог. По умолчанию false.

go
cfg.AuditEnabled = true

AuditHandler AuditHandler ​

Пользовательский обработчик аудита.

go
cfg.AuditHandler = env.NewJSONAuditHandler(os.Stdout)

Подробнее

Аудитный лог - полное описание конфигурации аудита.

Дополнительные параметры ​

Prefix string ​

Обрабатывать только переменные с этим префиксом. По умолчанию "" (обрабатывать все переменные).

go
cfg.Prefix = "MYAPP_"  // Загружать только переменные, начинающиеся с MYAPP_

FileSystem FileSystem ​

Пользовательский интерфейс файловой системы (для тестирования).

go
cfg.FileSystem = &MockFileSystem{}

CustomValidator Validator ​

Пользовательский валидатор ключей/значений. Переопределяет встроенный валидатор.

go
cfg.CustomValidator = &MyValidator{}

CustomExpander VariableExpander ​

Пользовательский раскрыватель переменных. Переопределяет встроенный раскрыватель.

go
cfg.CustomExpander = &MyExpander{}

CustomAuditor AuditLogger ​

Пользовательский регистратор аудита. Переопределяет встроенный регистратор.

go
cfg.CustomAuditor = &MyAuditLogger{}

Фабричные функции ​

DefaultConfig ​

go
func DefaultConfig() Config

Возвращает безопасную конфигурацию по умолчанию.

Значения по умолчанию:

ПолеЗначение
Filenames[".env"]
FailOnMissingFilefalse
OverwriteExistingfalse
AutoApplyfalse
ExpandVariablestrue
MaxFileSize2MB
MaxLineLength1024
MaxKeyLength64
MaxValueLength4096
MaxVariables500
MaxExpansionDepth5
ValidateValuestrue
KeyPatternnil (быстрая валидация)
AllowExportPrefixtrue
AllowYamlSyntaxfalse
JSONNullAsEmptytrue
JSONNumberAsStringtrue
JSONBoolAsStringtrue
JSONMaxDepth10
YAMLNullAsEmptytrue
YAMLNumberAsStringtrue
YAMLBoolAsStringtrue
YAMLMaxDepth10
ValidateUTF8false
AuditEnabledfalse
Prefix""

DevelopmentConfig ​

go
func DevelopmentConfig() Config

Возвращает конфигурацию для среды разработки (мягкие ограничения).

Различия от конфигурации по умолчанию:

  • OverwriteExisting: true
  • AllowYamlSyntax: true
  • MaxFileSize: 10MB

Гарантия безопасности

ValidateValues остаётся true во всех предустановках (как значение по умолчанию), обеспечивая безопасность независимо от среды.

go
cfg := env.DevelopmentConfig()
cfg.Filenames = []string{".env.development"}
loader, _ := env.New(cfg)

TestingConfig ​

go
func TestingConfig() Config

Возвращает конфигурацию для среды тестирования.

Различия от конфигурации по умолчанию:

  • OverwriteExisting: true
  • MaxFileSize: 64KB
  • MaxVariables: 50
go
func TestSomething(t *testing.T) {
    cfg := env.TestingConfig()
    cfg.Filenames = []string{".env.test"}
    loader, _ := env.New(cfg)
    defer loader.Close()
}

ProductionConfig ​

go
func ProductionConfig() Config

Возвращает конфигурацию для производственной среды (строгая валидация + аудит).

Различия от конфигурации по умолчанию:

  • FailOnMissingFile: true
  • AuditEnabled: true
  • MaxFileSize: 64KB
  • MaxVariables: 50
go
cfg := env.ProductionConfig()
cfg.RequiredKeys = []string{"DB_HOST", "API_KEY"}
cfg.AuditHandler = env.NewJSONAuditHandler(os.Stdout)
loader, _ := env.New(cfg)

Подробное сравнение предустановок ​

ФункцияDefaultDevelopmentTestingProduction
Перезапись существующих переменныхНетДаДаНет
Ошибка при отсутствии файлаНетНетНетДа
Аудитный логНетНетНетДа
YAML синтаксисНетДаНетНет
Ограничение размера файла2MB10MB64KB64KB
Максимальное количество переменных5005005050
Проверка запрещённых ключейДаДаДаДа
Валидация значенийДаДаДаДа

Рекомендации по выбору

  • Среда разработки: Используйте DevelopmentConfig() с мягкими ограничениями для быстрой итерации
  • Среда тестирования: Используйте TestingConfig() с разрешённой перезаписью для изоляции тестов
  • Производственная среда: Используйте ProductionConfig() с включённым аудитом и строгой валидацией

Методы ​

Validate ​

go
func (c *Config) Validate() error

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

go
cfg := env.DefaultConfig()
cfg.MaxFileSize = 1000

if err := cfg.Validate(); err != nil {
    // Конфигурация недействительна
}

Правила валидации:

  • Все ограничения должны иметь положительные значения
  • Все ограничения не могут превышать жёсткий предел
  • KeyPattern если не nil, должно соответствовать допустимому имени ключа (например, TEST_KEY), не должно соответствовать пустой строке или ключам, начинающимся с цифры
  • JSONMaxDepth и YAMLMaxDepth должно быть от 1 до 100

IsZero ​

go
func (c *Config) IsZero() bool

Проверяет, является ли Config неинициализированным нулевым значением. Используется для определения, следует ли использовать DefaultConfig().

Возвращает:

  • bool - Является ли нулевой конфигурацией

Область обнаружения:

  • Числовые ограничения (MaxFileSize, MaxVariables и т.д.)
  • Логические поля (ValidateValues, AutoApply и т.д.)
  • Поля указателей/интерфейсов (KeyPattern, FileSystem и т.д.)
  • Поля срезов (Filenames, RequiredKeys и т.д.)

Внимание

Частично инициализированный Config может не быть обнаружен как нулевое значение. Рекомендуется всегда начинать с DefaultConfig() для пользовательской конфигурации:

go
// Рекомендуется
cfg := env.DefaultConfig()
cfg.Filenames = []string{".env.production"}

// Не рекомендуется (некоторые поля — нулевые значения)
var cfg env.Config
cfg.Filenames = []string{".env.production"}

Примеры использования ​

Базовая конфигурация ​

go
cfg := env.DefaultConfig()
cfg.Filenames = []string{".env", ".env.local"}
cfg.OverwriteExisting = true

loader, err := env.New(cfg)
if err != nil {
    log.Fatal(err)
}
defer loader.Close()

Конфигурация производственной среды ​

go
cfg := env.ProductionConfig()
cfg.RequiredKeys = []string{"DB_HOST", "DB_PORT", "API_KEY"}
cfg.AuditHandler = env.NewJSONAuditHandler(os.Stdout)

loader, err := env.New(cfg)
if err != nil {
    log.Fatal(err)
}
defer loader.Close()

if err := loader.LoadFiles(".env"); err != nil {
    log.Fatal(err)
}

if err := loader.Validate(); err != nil {
    log.Fatal("Отсутствует обязательная конфигурация:", err)
}

Использование фильтрации по префиксу ​

go
cfg := env.DefaultConfig()
cfg.Prefix = "MYAPP_"  // Загружать только MYAPP_KEY1, MYAPP_KEY2 и т.д.
cfg.Filenames = []string{".env"}

loader, _ := env.New(cfg)
// Loader содержит только переменные, начинающиеся с MYAPP_

Пользовательская валидация ​

go
import "regexp"

cfg := env.DefaultConfig()
// Разрешить только ключи, начинающиеся с заглавной буквы
cfg.KeyPattern = regexp.MustCompile(`^[A-Z][A-Z0-9_]*$`)
// Добавить пользовательский запрещённый ключ
cfg.ForbiddenKeys = []string{"DEBUG", "TRACE"}

loader, _ := env.New(cfg)

Связанная документация ​