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 // 単一ファイルの最大バイト数
    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 = 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 - ローダーメソッド
• 定数とエラー - 制限定数とエラー型
• 監査ログ - 監査設定ガイド