Config API

Config 構造体の完全な設定オプションリファレンス。

構造体の定義

Config はネストした構造体で設定を編成し、同時に Go のフィールド昇格で後方互換性を維持します：

type Config struct {
    FileConfig       // ファイル読み込み動作
    ValidationConfig // キーと値の検証
    LimitsConfig     // サイズと数量の制限
    JSONConfig       // JSON 解析オプション
    YAMLConfig       // YAML 解析オプション
    ParsingConfig    // 汎用解析動作
    ComponentConfig  // カスタムコンポーネントと高度なオプション
}

2 つのアクセス方式：

// 旧方式（フィールド昇格経由、引き続き有効）
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 // 1 ファイルの最大バイト数
    MaxVariables      int   // ファイルごとの最大変数数
    MaxLineLength     int   // 1 行の最大長
    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:-default} と同じ（変数が存在しない場合にデフォルト値を使用、ストレージに書き戻さない）
${VAR:?error}	変数が存在しないか空の場合にエラーを返す

空文字列の扱い

${VAR:-default} と ${VAR:=default} は変数が未設定の場合のみデフォルト値を使用します。変数が明示的に空文字列（VAR=）に設定されている場合、空文字列の元の値を使用します。${VAR:?error} のみが空文字列をエラーとして扱います。詳しくは変数展開を参照。

セキュリティ制限

MaxFileSize int64

1 ファイルの最大バイト数。デフォルト 2MB、ハード上限 100MB。

cfg.MaxFileSize = 10 * 1024 * 1024 // 10 MB

設定	デフォルト値	ハード上限
MaxFileSize	2MB (2097152)	100MB

---

MaxLineLength int

1 行の最大長。デフォルト 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 = true

JSON オプション

JSONNullAsEmpty bool

JSON null 値を空文字列に変換。デフォルト true。

cfg.JSONNullAsEmpty = true

---

JSONNumberAsString bool

JSON 数値を文字列に変換。デフォルト true。

cfg.JSONNumberAsString = true

---

JSONBoolAsString bool

JSON ブール値を文字列に変換。デフォルト true。

cfg.JSONBoolAsString = true

---

JSONMaxDepth int

JSON の最大ネスト深度。デフォルト 10。

cfg.JSONMaxDepth = 20

YAML オプション

YAMLNullAsEmpty bool

YAML null/~ 値を空文字列に変換。デフォルト true。

cfg.YAMLNullAsEmpty = true

---

YAMLNumberAsString bool

YAML 数値を文字列に変換。デフォルト true。

cfg.YAMLNumberAsString = true

---

YAMLBoolAsString bool

YAML ブール値を文字列に変換。デフォルト true。

cfg.YAMLBoolAsString = true

---

YAMLMaxDepth int

YAML の最大ネスト深度。デフォルト 10。

cfg.YAMLMaxDepth = 15

監査

AuditEnabled bool

監査ログを有効化。デフォルト false。

cfg.AuditEnabled = true

---

AuditHandler 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: true
• AllowYamlSyntax: true
• MaxFileSize: 10MB

セキュリティ保証

ValidateValues はすべてのプリセット設定で常に true（デフォルト値と同じ）を維持し、環境によるセキュリティの低下を防ぎます。

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

---

TestingConfig

func TestingConfig() Config

テスト環境設定を返します。

デフォルト設定との差異：

• OverwriteExisting: true
• MaxFileSize: 64KB
• MaxVariables: 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: true
• AuditEnabled: true
• MaxFileSize: 64KB
• MaxVariables: 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() bool

Config が未初期化のゼロ値かをチェックします。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 - ローダーメソッド
• 定数とエラー - 制限定数とエラー型
• 監査ログ - 監査設定ガイド