Config API
Config 구조체의 전체 설정 옵션 참조입니다.
구조체 정의
Config 는 중첩 구조체를 사용하여 설정을 구성하며, Go 의 필드 승격을 통해 하위 호환성을 유지합니다:
type Config struct {
FileConfig // 파일 로드 동작
ValidationConfig // 키 및 값 검증
LimitsConfig // 크기 및 수량 제한
JSONConfig // JSON 파싱 옵션
YAMLConfig // YAML 파싱 옵션
ParsingConfig // 일반 파싱 동작
ComponentConfig // 사용자 정의 컴포넌트 및 고급 옵션
}두 가지 접근 방식:
// 이전 방식 (필드 승격을 통해, 여전히 유효)
cfg.Filenames = []string{".env"}
cfg.MaxFileSize = 1024
// 새로운 방식 (권장, 더 명확)
cfg.FileConfig.Filenames = []string{".env"}
cfg.LimitsConfig.MaxFileSize = 1024중첩 구조체
// 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"].
cfg.Filenames = []string{".env", ".env.local"}FailOnMissingFile bool
파일이 존재하지 않을 때 오류를 반환할지 여부입니다. 기본값 false (조용히 건너뜀).
cfg.FailOnMissingFile = true // 파일이 없으면 오류 발생OverwriteExisting bool
이미 존재하는 환경 변수를 덮어쓸지 여부입니다. 기본값 false.
cfg.OverwriteExisting = true // 덮어쓰기 허용AutoApply bool
로드 후 시스템 환경 (os.Environ) 에 자동으로 적용합니다. 기본값 false.
cfg.AutoApply = true // 로드 후 자동 적용참고
패키지 수준 Load() 함수는 자동으로 AutoApply = true를 설정합니다. New()로 Loader 를 생성할 때는 수동으로 설정해야 합니다.
변수 확장
ExpandVariables bool
${VAR} 구문 변수 확장을 활성화합니다. 기본값 true.
cfg.ExpandVariables = true지원되는 확장 구문:
| 구문 | 설명 |
|---|---|
${VAR} | 변수 참조 |
${VAR:-default} | 변수가 존재하지 않거나 비어 있을 때 기본값 사용 |
${VAR:=default} | 변수가 존재하지 않거나 비어 있을 때 기본값 설정 |
${VAR:?error} | 변수가 존재하지 않거나 비어 있을 때 오류 발생 |
보안 제한
MaxFileSize int64
단일 파일의 최대 바이트 수입니다. 기본값 2MB, 하드 상한선 100MB.
cfg.MaxFileSize = 10 * 1024 * 1024 // 10 MB| 설정 | 기본값 | 하드 상한선 |
|---|---|---|
MaxFileSize | 2MB (2097152) | 100MB |
MaxLineLength int
단일 행의 최대 길이입니다. 기본값 1024, 하드 상한선 64KB.
cfg.MaxLineLength = 2048| 설정 | 기본값 | 하드 상한선 |
|---|---|---|
MaxLineLength | 1024 | 65536 (64KB) |
MaxKeyLength int
키 이름의 최대 길이입니다. 기본값 64, 하드 상한선 1024.
cfg.MaxKeyLength = 128| 설정 | 기본값 | 하드 상한선 |
|---|---|---|
MaxKeyLength | 64 | 1024 |
MaxValueLength int
값의 최대 길이입니다. 기본값 4096, 하드 상한선 1MB.
cfg.MaxValueLength = 8192| 설정 | 기본값 | 하드 상한선 |
|---|---|---|
MaxValueLength | 4096 | 1048576 (1MB) |
MaxVariables int
파일당 최대 변수 수입니다. 기본값 500, 하드 상한선 10000.
cfg.MaxVariables = 1000| 설정 | 기본값 | 하드 상한선 |
|---|---|---|
MaxVariables | 500 | 10000 |
MaxExpansionDepth int
변수 확장의 최대 깊이입니다. 기본값 5, 하드 상한선 20.
cfg.MaxExpansionDepth = 10| 설정 | 기본값 | 하드 상한선 |
|---|---|---|
MaxExpansionDepth | 5 | 20 |
키 검증
KeyPattern *regexp.Regexp
사용자 정의 키 이름 일치 패턴입니다. 기본값 nil (빠른 바이트 수준 검증 사용).
성능 최적화
nil 값은 빠른 바이트 수준 검증을 활성화합니다 (약 10 배 성능 향상). 기본 검증 규칙: 문자로 시작, 문자, 숫자, 밑줄만 포함.
import "regexp"
// 사용자 정의 패턴
cfg.KeyPattern = regexp.MustCompile(`^[A-Z][A-Z0-9_]*$`)AllowedKeys []string
허용된 키 이름 허용 목록입니다. 비어 있으면 모든 키를 허용합니다 (금지된 키 제외).
cfg.AllowedKeys = []string{"APP_NAME", "APP_VERSION", "PORT"}ForbiddenKeys []string
추가 금지 키 목록입니다 (내장 금지 키에 추가됨).
cfg.ForbiddenKeys = []string{"CUSTOM_DANGEROUS_VAR"}내장 금지 키
라이브러리는 PATH, LD_PRELOAD, LD_LIBRARY_PATH, DYLD_INSERT_LIBRARIES 등의 시스템 핵심 변수를 기본적으로 금지합니다. 자세한 내용은 상수 및 오류를 참조하세요.
RequiredKeys []string
필수 키 이름 목록입니다. Validate() 호출 시 검사합니다.
cfg.RequiredKeys = []string{"DB_HOST", "API_KEY"}ValidateValues bool
값의 안전성을 검증합니다 (제어 문자, 널 바이트 등). 기본값 true.
보안 권장 사항
항상 활성화 상태를 유지하는 것을 권장하며, 제어 문자가 포함된 값을 저장해야 하는 등 특수한 상황에서만 비활성화하세요.
cfg.ValidateValues = true // 기본적으로 활성화됨ValidateUTF8 bool
값이 유효한 UTF-8 인코딩인지 검증합니다. 기본값 false.
cfg.ValidateUTF8 = true // UTF-8 검증 활성화파싱 옵션
AllowExportPrefix bool
export KEY=value 구문을 허용합니다. 기본값 true.
cfg.AllowExportPrefix = false // export 접두사 금지AllowYamlSyntax bool
YAML 스타일 구문 (KEY: value) 을 허용합니다. 기본값 false.
cfg.AllowYamlSyntax = trueJSON 옵션
JSONNullAsEmpty bool
JSON null 값을 빈 문자열로 변환합니다. 기본값 true.
cfg.JSONNullAsEmpty = trueJSONNumberAsString bool
JSON 숫자를 문자열로 변환합니다. 기본값 true.
cfg.JSONNumberAsString = trueJSONBoolAsString bool
JSON 부울값을 문자열로 변환합니다. 기본값 true.
cfg.JSONBoolAsString = trueJSONMaxDepth int
JSON 최대 중첩 깊이입니다. 기본값 10.
cfg.JSONMaxDepth = 20YAML 옵션
YAMLNullAsEmpty bool
YAML null/~ 값을 빈 문자열로 변환합니다. 기본값 true.
cfg.YAMLNullAsEmpty = trueYAMLNumberAsString bool
YAML 숫자를 문자열로 변환합니다. 기본값 true.
cfg.YAMLNumberAsString = trueYAMLBoolAsString bool
YAML 부울값을 문자열로 변환합니다. 기본값 true.
cfg.YAMLBoolAsString = trueYAMLMaxDepth int
YAML 최대 중첩 깊이입니다. 기본값 10.
cfg.YAMLMaxDepth = 15감사
AuditEnabled bool
감사 로그를 활성화합니다. 기본값 false.
cfg.AuditEnabled = trueAuditHandler AuditHandler
사용자 정의 감사 핸들러입니다.
cfg.AuditHandler = env.NewJSONAuditHandler(os.Stdout)자세히
감사 로깅에서 전체 감사 설정 설명을 확인하세요.
고급 옵션
Prefix string
이 접두사가 있는 변수만 처리합니다. 기본값 "" (모든 변수 처리).
cfg.Prefix = "MYAPP_" // MYAPP_로 시작하는 변수만 로드FileSystem FileSystem
사용자 정의 파일 시스템 인터페이스 (테스트용).
cfg.FileSystem = &MockFileSystem{}CustomValidator Validator
사용자 정의 키/값 검증기입니다. 내장 검증기를 덮어씁니다.
cfg.CustomValidator = &MyValidator{}CustomExpander VariableExpander
사용자 정의 변수 확장기입니다. 내장 확장기를 덮어씁니다.
cfg.CustomExpander = &MyExpander{}CustomAuditor AuditLogger
사용자 정의 감사 로거입니다. 내장 감사기를 덮어씁니다.
cfg.CustomAuditor = &MyAuditLogger{}팩토리 함수
DefaultConfig
func DefaultConfig() Config안전한 기본 설정을 반환합니다.
기본값:
| 필드 | 값 |
|---|---|
Filenames | [".env"] |
FailOnMissingFile | false |
OverwriteExisting | false |
AutoApply | false |
ExpandVariables | true |
MaxFileSize | 2MB |
MaxLineLength | 1024 |
MaxKeyLength | 64 |
MaxValueLength | 4096 |
MaxVariables | 500 |
MaxExpansionDepth | 5 |
ValidateValues | true |
KeyPattern | nil (빠른 검증) |
AllowExportPrefix | true |
AllowYamlSyntax | false |
JSONNullAsEmpty | true |
JSONNumberAsString | true |
JSONBoolAsString | true |
JSONMaxDepth | 10 |
YAMLNullAsEmpty | true |
YAMLNumberAsString | true |
YAMLBoolAsString | true |
YAMLMaxDepth | 10 |
ValidateUTF8 | false |
AuditEnabled | false |
Prefix | "" |
DevelopmentConfig
func DevelopmentConfig() Config개발 환경 설정을 반환합니다 (완화된 제한).
기본 설정과의 차이점:
OverwriteExisting:trueAllowYamlSyntax:trueMaxFileSize: 10MB
보안 보장
ValidateValues는 모든 프리셋 설정에서 항상 true로 유지되어 (기본값과 일치), 환경에 관계없이 보안이 보장됩니다.
cfg := env.DevelopmentConfig()
cfg.Filenames = []string{".env.development"}
loader, _ := env.New(cfg)TestingConfig
func TestingConfig() Config테스트 환경 설정을 반환합니다.
기본 설정과의 차이점:
OverwriteExisting:trueMaxFileSize: 64KBMaxVariables: 50
func TestSomething(t *testing.T) {
cfg := env.TestingConfig()
cfg.Filenames = []string{".env.test"}
loader, _ := env.New(cfg)
defer loader.Close()
}ProductionConfig
func ProductionConfig() Config프로덕션 환경 설정을 반환합니다 (엄격한 검증 + 감사).
기본 설정과의 차이점:
FailOnMissingFile:trueAuditEnabled:trueMaxFileSize: 64KBMaxVariables: 50
cfg := env.ProductionConfig()
cfg.RequiredKeys = []string{"DB_HOST", "API_KEY"}
cfg.AuditHandler = env.NewJSONAuditHandler(os.Stdout)
loader, _ := env.New(cfg)프리셋 상세 비교
| 기능 | Default | Development | Testing | Production |
|---|---|---|---|---|
| 기존 변수 덮어쓰기 | ✗ | ✓ | ✓ | ✗ |
| 파일 없음 시 오류 | ✗ | ✗ | ✗ | ✓ |
| 감사 로그 | ✗ | ✗ | ✗ | ✓ |
| YAML 구문 | ✗ | ✓ | ✗ | ✗ |
| 파일 크기 제한 | 2MB | 10MB | 64KB | 64KB |
| 최대 변수 수 | 500 | 500 | 50 | 50 |
| 금지 키 검사 | ✓ | ✓ | ✓ | ✓ |
| 값 검증 | ✓ | ✓ | ✓ | ✓ |
선택 가이드
- 개발 환경:
DevelopmentConfig()사용, 완화된 제한으로 빠른 반복 개발에 유리 - 테스트 환경:
TestingConfig()사용, 덮어쓰기 허용으로 테스트 격리에 유리 - 프로덕션 환경:
ProductionConfig()사용, 감사 및 엄격한 검증 활성화
메서드
Validate
func (c *Config) Validate() error설정의 유효성을 검증합니다. 모든 제한 값이 유효한 범위 내에 있는지 확인합니다.
cfg := env.DefaultConfig()
cfg.MaxFileSize = 1000
if err := cfg.Validate(); err != nil {
// 설정이 유효하지 않음
}검증 규칙:
- 모든 제한 값은 양수여야 함
- 모든 제한 값은 하드 상한선을 초과할 수 없음
KeyPattern이 nil 이 아닌 경우 유효한 키 이름 (예:TEST_KEY) 을 일치시킬 수 있어야 하고, 빈 문자열을 일치시키지 않아야 하며, 숫자로 시작하는 키 이름을 일치시키지 않아야 함JSONMaxDepth및YAMLMaxDepth는 1-100 사이여야 함
IsZero
func (c *Config) IsZero() boolConfig 가 초기화되지 않은 제로값인지 확인합니다. DefaultConfig()를 사용해야 하는지 판단하는 데 사용합니다.
반환값:
bool- 제로값 설정인지 여부
검사 범위:
- 숫자 제한 (MaxFileSize, MaxVariables 등)
- 부울 필드 (ValidateValues, AutoApply 등)
- 포인터/인터페이스 필드 (KeyPattern, FileSystem 등)
- 슬라이스 필드 (Filenames, RequiredKeys 등)
참고
부분적으로 초기화된 Config 는 제로값으로 감지되지 않을 수 있습니다. 항상 DefaultConfig()에서 시작하여 사용자 정의 설정을 구성하는 것을 권장합니다:
// 권장
cfg := env.DefaultConfig()
cfg.Filenames = []string{".env.production"}
// 비권장 (일부 필드가 제로값)
var cfg env.Config
cfg.Filenames = []string{".env.production"}사용 예제
기본 설정
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()프로덕션 환경 설정
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)
}접두사 필터링 사용
cfg := env.DefaultConfig()
cfg.Prefix = "MYAPP_" // MYAPP_KEY1, MYAPP_KEY2 등만 로드
cfg.Filenames = []string{".env"}
loader, _ := env.New(cfg)
// loader 에는 MYAPP_로 시작하는 변수만 있음사용자 정의 검증
import "regexp"
cfg := env.DefaultConfig()
// 대문자로 시작하는 키만 허용
cfg.KeyPattern = regexp.MustCompile(`^[A-Z][A-Z0-9_]*$`)
// 사용자 정의 금지 키 추가
cfg.ForbiddenKeys = []string{"DEBUG", "TRACE"}
loader, _ := env.New(cfg)관련 문서
- Loader API - 로더 메서드
- 상수 및 오류 - 제한 상수 및 오류 유형
- 감사 로깅 - 감사 설정 가이드