Loader API

Loader 型の完全なメソッドリファレンス。Loader は env ライブラリのコア型で、環境変数の読み込み、格納、アクセス機能を提供します。

スレッドセーフ

Loader のすべてのメソッドはスレッドセーフで、複数の goroutine から並行して呼び出し可能です。

型定義

type Loader struct {
    // プライベートフィールドを含む
}

// コンパイル時のインターフェース実装チェック
var _ EnvLoader = (*Loader)(nil)
var _ io.Closer = (*Loader)(nil)

作成

New

func New(cfg ...Config) (*Loader, error)

新しいローダーインスタンスを作成します。

パラメータ：

cfg - オプションの設定オプション。未指定またはゼロ値 Config を渡した場合、自動的に DefaultConfig() を使用

戻り値：

*Loader - ローダーインスタンス
error - 設定検証エラー

動作：

設定の有効性を検証
内部コンポーネントを作成（バリデーター、監査機能、エキスパンダー）
cfg.Filenames が空でない場合、自動的にファイルを読み込み
cfg.AutoApply が true の場合、自動的にシステム環境に適用

// デフォルト設定を使用
loader, err := env.New()

// カスタム設定を使用
cfg := env.DefaultConfig()
cfg.Filenames = []string{".env"}
cfg.AutoApply = true
loader, err := env.New(cfg)

if err != nil {
    panic(err)
}
defer loader.Close()

ファイル読み込み

LoadFiles

func (l *Loader) LoadFiles(filenames ...string) error

1 つ以上の設定ファイルを読み込みます。

パラメータ：

filenames - ファイルパスのリスト、空の場合はデフォルトで .env を読み込み

戻り値：

error - 読み込みエラー

動作：

順番に読み込み、後に読み込んだものが前に読み込んだものを上書き（OverwriteExisting 設定で制御）
ファイルフォーマットを自動検出（.env、JSON、YAML）
FailOnMissingFile 設定に基づきファイル不存在時の動作を決定
AutoApply が true の場合、読み込み後に自動適用

// デフォルト .env ファイルを読み込み
err := loader.LoadFiles()

// 指定ファイルを読み込み
err := loader.LoadFiles(".env", ".env.local")

// フォーマット混在
err := loader.LoadFiles("config.env", "settings.json", "secrets.yaml")

エラー型：

ErrFileNotFound - ファイルが存在しない（FailOnMissingFile=true 時）
ErrFileTooLarge - ファイルがサイズ制限を超過
ErrClosed - ローダーがクローズ済み
*ParseError - 解析エラー
*JSONError - JSON 解析エラー
*YAMLError - YAML 解析エラー
*SecurityError - ファイルパスのセキュリティ検証失敗（パストラバーサル攻撃など）

フォーマット検出ルール：

拡張子	フォーマット
`.env`	FormatEnv
`.json`	FormatJSON
`.yaml`, `.yml`	FormatYAML
その他	FormatAuto（.env パーサーを使用）

値の取得

キー名の解決

すべての取得メソッドはインテリジェントなキー名解決をサポートします：

入力キー名	解決結果
`"DATABASE_HOST"`	`"DATABASE_HOST"`（完全一致）
`"database.host"`	`"DATABASE_HOST"`（ドットをアンダースコアに変換）
`"app.name"`	`"APP_NAME"`（大文字 + アンダースコア）
`"servers.0.host"`	`"SERVERS_0_HOST"`（配列インデックス）

解決順序：

完全一致 - キー名を直接検索
大文字変換 - シンプルキーは大文字版を試行
パス解決 - ドットパスをアンダースコアフォーマットに変換
インデックスフォールバック - インデックスアクセス時にカンマ区切り値にフォールバック

GetString

func (l *Loader) GetString(key string, defaultValue ...string) string

文字列値を取得します。ドットパス解決をサポートします。

パラメータ：

key - キー名（完全一致、大文字変換、ドットパスをサポート）
defaultValue - オプションのデフォルト値

戻り値：

string - 値またはデフォルト値（見つからずデフォルト値なしの場合は空文字列）

// 基本的な使い方
host := loader.GetString("HOST", "localhost")

// ドットパスアクセス（JSON/YAML ネスト構造）
dbHost := loader.GetString("database.host", "localhost")
appName := loader.GetString("app.name")

// デフォルト値なしの場合は空文字列を返す
value := loader.GetString("NON_EXISTENT")  // ""

GetInt

func (l *Loader) GetInt(key string, defaultValue ...int64) int64

整数値を取得します。ドットパス解決をサポートします。

パラメータ：

key - キー名（ドットパスをサポート）
defaultValue - オプションのデフォルト値、型は int64

戻り値：

int64 - 値またはデフォルト値（見つからずデフォルト値なしの場合は 0）

port := loader.GetInt("PORT", 8080)
maxConn := loader.GetInt("database.max_connections", 10)

// デフォルト値なしの場合は 0 を返す
value := loader.GetInt("NON_EXISTENT")  // 0

GetBool

func (l *Loader) GetBool(key string, defaultValue ...bool) bool

ブール値を取得します。ドットパス解決をサポートします。

パラメータ：

key - キー名（ドットパスをサポート）
defaultValue - オプションのデフォルト値

戻り値：

bool - 値またはデフォルト値（見つからずデフォルト値なしの場合は false）

サポートする値：

真値：true, 1, yes, on, enabled
偽値：false, 0, no, off, disabled

debug := loader.GetBool("DEBUG", false)
cacheEnabled := loader.GetBool("cache.enabled", true)

// デフォルト値なしの場合は false を返す
value := loader.GetBool("NON_EXISTENT")  // false

GetUint64

func (l *Loader) GetUint64(key string, defaultValue ...uint64) uint64

符号なし整数値を取得します。ドットパス解決をサポートします。

パラメータ：

key - キー名（ドットパスをサポート）
defaultValue - オプションのデフォルト値、型は uint64

戻り値：

uint64 - 値またはデフォルト値（見つからずデフォルト値なしの場合は 0）

port := loader.GetUint64("PORT", 8080)
maxSize := loader.GetUint64("MAX_SIZE", 1024)

// デフォルト値なしの場合は 0 を返す
value := loader.GetUint64("NON_EXISTENT")  // 0

GetFloat64

func (l *Loader) GetFloat64(key string, defaultValue ...float64) float64

浮動小数点数値を取得します。ドットパス解決をサポートします。

パラメータ：

key - キー名（ドットパスをサポート）
defaultValue - オプションのデフォルト値、型は float64

戻り値：

float64 - 値またはデフォルト値（見つからずデフォルト値なしの場合は 0）

rate := loader.GetFloat64("RATE", 0.5)
threshold := loader.GetFloat64("THRESHOLD")

// デフォルト値なしの場合は 0 を返す
value := loader.GetFloat64("NON_EXISTENT")  // 0

GetDuration

func (l *Loader) GetDuration(key string, defaultValue ...time.Duration) time.Duration

時間間隔値を取得します。ドットパス解決をサポートします。

パラメータ：

key - キー名（ドットパスをサポート）
defaultValue - オプションのデフォルト値

戻り値：

time.Duration - 値またはデフォルト値（見つからずデフォルト値なしの場合は 0）

サポートフォーマット： ns, us, ms, s, m, h（例：30s, 5m, 1h30m）

timeout := loader.GetDuration("TIMEOUT", 30*time.Second)
ttl := loader.GetDuration("cache.ttl", 5*time.Minute)

// デフォルト値なしの場合は 0 を返す
value := loader.GetDuration("NON_EXISTENT")  // 0

GetSecure

func (l *Loader) GetSecure(key string) *SecureValue

セキュア値を取得します（機密データ保護）。

パラメータ：

key - キー名

戻り値：

*SecureValue - セキュア値の防御的コピー、呼び出し側が解放を担当；キーが存在しないまたはローダーがクローズされた場合は nil

secret := loader.GetSecure("API_SECRET")
if secret != nil {
    defer secret.Release()

    value := secret.Reveal()   // 平文値
    masked := secret.Masked()  // [SECURE:32 bytes]
}

重要

使用後に Release() または Close() を呼び出してリソースを解放する必要があります。

防御的コピー

GetSecure は元の値のコピーを返し、親 Loader から独立しています。呼び出し側が Release() または Close() の呼び出しを担当します。

詳細

SecureValue API で完全なドキュメントを参照してください。

スライス値の取得

Loader はスライス取得メソッドを提供しません（Go はジェネリックメソッドをサポートしないため）。独立したジェネリック関数 GetSliceFrom[T] で Loader インスタンスからスライスを取得します：

// 独立ジェネリック関数を使用
hosts := env.GetSliceFrom[string](loader, "HOSTS")
ports := env.GetSliceFrom[int64](loader, "PORTS", []int64{80})
portsInt := env.GetSliceFrom[int](loader, "PORTS")  // int もサポート

サポートする型： string, int, int64, uint, uint64, bool, float64, time.Duration

詳細

パッケージ関数 - GetSliceFrom で完全なドキュメントを参照してください。

Lookup

func (l *Loader) Lookup(key string) (string, bool)

キーが存在するかチェックし値を取得します。ドットパス解決をサポートします。

パラメータ：

key - キー名（ドットパスをサポート）

戻り値：

string - 値（前後の空白は削除済み）
bool - 存在するか

value, exists := loader.Lookup("API_KEY")
if !exists {
    // キーが存在しない
}

// ドットパス
if value, exists := loader.Lookup("database.host"); exists {
    fmt.Println(value)
}

// インデックスアクセス（カンマ区切り値にフォールバック）
// HOSTS=localhost,example.com
if value, exists := loader.Lookup("hosts.0"); exists {
    fmt.Println(value)  // "localhost"
}

設定と削除

Set

func (l *Loader) Set(key, value string) error

環境変数を設定します。

パラメータ：

key - キー名
value - 値

戻り値：

error - 設定エラー

動作：

キー名の有効性を検証
ValidateValues が true の場合、値の安全性を検証
OverwriteExisting が false でキーが既存の場合、スキップ（nil を返す）
AutoApply が true の場合、システム環境にも同時に設定

err := loader.Set("CUSTOM_KEY", "value")
if err != nil {
    // エラーを処理
}

エラー型：

*ValidationError - キー名形式が無効（Field="key"）
*SecurityError - キーが禁止されている（errors.Is(err, env.ErrSecurityViolation) でマッチ可能）
ErrInvalidValue - 値が無効（ValidateValues が true の場合、値にヌルバイト、制御文字などの安全でない内容が含まれる）
ErrClosed - ローダーがクローズ済み

Delete

func (l *Loader) Delete(key string) error

環境変数を削除します。

パラメータ：

key - キー名

戻り値：

error - 削除エラー

動作：

変数がシステム環境に適用済みの場合、システム環境からも同時に削除

err := loader.Delete("TEMP_KEY")
if err != nil {
    panic(err)
}

コレクション操作

Keys

func (l *Loader) Keys() []string

すべてのキー名を取得します。

戻り値：

[]string - キー名リスト、ローダーがクローズ済みの場合は nil

keys := loader.Keys()
for _, key := range keys {
    fmt.Println(key)
}

All

func (l *Loader) All() map[string]string

すべてのキーと値のペアを取得します。

戻り値：

map[string]string - キーと値のマッピング、ローダーがクローズ済みの場合は nil

all := loader.All()
for key, value := range all {
    fmt.Printf("%s=%s\n", key, value)
}

Len

func (l *Loader) Len() int

変数の数を取得します。

戻り値：

int - 変数の数、ローダーがクローズ済みの場合は 0

count := loader.Len()
fmt.Printf("%d 個の変数を読み込みました\n", count)

システムへの適用

Apply

func (l *Loader) Apply() error

変数をシステム環境（os.Environ）に適用します。

戻り値：

error - 適用エラー

動作：

読み込んだすべての変数をトラバース
OverwriteExisting 設定に基づき既存のシステム環境変数を上書きするか決定
適用後 os.Getenv() でアクセス可能

エラー型：

ErrClosed - ローダーがクローズ済み
ラップされた os エラー - 環境変数の設定失敗（キー名はマスク済み、エラーメッセージに機密キー名を露出しない）

err := loader.Apply()
if err != nil {
    panic(err)
}

// その後 os.Getenv() でもアクセス可能
host := os.Getenv("HOST")

IsApplied

func (l *Loader) IsApplied() bool

変数がシステム環境に適用済みかチェックします。

戻り値：

bool - 適用済みか

if loader.IsApplied() {
    // 変数が os.Environ に適用済み
}

状態クエリ

LoadTime

func (l *Loader) LoadTime() time.Time

最後にファイルを読み込んだ時刻を返します。

戻り値：

time.Time - 読み込み時刻、未読み込みの場合はゼロ値

loadTime := loader.LoadTime()
if !loadTime.IsZero() {
    fmt.Printf("最終読み込み時刻: %v\n", loadTime)
}

Config

func (l *Loader) Config() Config

ローダーの設定を返します。

戻り値：

Config - 設定（読み取り専用として扱うべき）

注意

返された Config は読み取り専用として扱うべきです。KeyPattern、AllowedKeys、ForbiddenKeys、RequiredKeys などのフィールドを変更するとローダーの動作に影響する可能性があります。安全な変更可能なコピーが必要な場合は、必要なフィールドを手動でコピーしてください。

cfg := loader.Config()
fmt.Printf("最大ファイルサイズ：%d\n", cfg.MaxFileSize)

検証とマッピング

Validate

func (l *Loader) Validate() error

必須キーが存在するか検証します。

戻り値：

error - 検証エラー

動作：

ValidationConfig.RequiredKeys で指定されたすべてのキーが存在するかチェック

cfg := env.DefaultConfig()
cfg.RequiredKeys = []string{"DB_HOST", "API_KEY"}

loader, _ := env.New(cfg)
loader.LoadFiles(".env")

if err := loader.Validate(); err != nil {
    // 必須キーが不足
    var missingErr *env.ValidationError
    if errors.As(err, &missingErr) {
        fmt.Printf("不足: %s\n", missingErr.Field)
    }
}

ParseInto

func (l *Loader) ParseInto(v any) error

環境変数を構造体にマッピングします。

パラメータ：

v - 構造体ポインタ

戻り値：

error - マッピングエラー

サポートするタグ：

env:"KEY" - 環境変数名を指定
env:"-" - このフィールドを無視
envDefault:"value" - デフォルト値を指定

スライスフィールドはデフォルトでカンマ , で区切られ（セパレータ前後の空白は自動削除）、カスタムセパレータタグはありません。

type Config struct {
    Host    string   `env:"HOST" envDefault:"localhost"`
    Port    int64    `env:"PORT" envDefault:"8080"`
    Debug   bool     `env:"DEBUG" envDefault:"false"`
    Hosts   []string `env:"HOSTS"`
    Ignored string   `env:"-"`
}

var cfg Config
err := loader.ParseInto(&cfg)
if err != nil {
    panic(err)
}

リソース解放

Close

func (l *Loader) Close() error

リソースを解放しストレージをクリアします。

戻り値：

error - クローズエラー

動作：

すべての格納された機密データを安全にゼロクリア
ローダーが ComponentFactory を所有する場合、ファクトリーも同時にクローズ
安全なクローズ、複数回呼び出しで nil を返す

loader, _ := env.New(cfg)
defer loader.Close()

// loader を使用...

クローズ後の動作

クローズ後のすべての操作はエラーまたはゼロ値を返します：

LoadFiles → ErrClosed
GetString → 空値を返す
Set → ErrClosed
Keys → nil を返す
Len → 0 を返す

IsClosed

func (l *Loader) IsClosed() bool

ローダーがクローズ済みかチェックします。

戻り値：

bool - クローズ済みか

if loader.IsClosed() {
    // ローダーはクローズ済み
}

完全な例

package main

import (
    "errors"
    "fmt"
    "log"
    "os"
    "time"

    "github.com/cybergodev/env"
)

func main() {
    // 本番環境設定を作成
    cfg := env.ProductionConfig()
    cfg.RequiredKeys = []string{"DB_HOST", "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", ".env.production"); err != nil {
        if errors.Is(err, env.ErrFileNotFound) {
            log.Fatal("設定ファイルが存在しません")
        }
        log.Fatal(err)
    }

    // 必須キーを検証
    if err := loader.Validate(); err != nil {
        log.Fatal("必須設定が不足しています：", err)
    }

    // 設定を読み取り
    host := loader.GetString("DB_HOST")
    port := loader.GetInt("DB_PORT", 5432)
    debug := loader.GetBool("DEBUG", false)
    timeout := loader.GetDuration("TIMEOUT", 30*time.Second)

    fmt.Printf("Server: %s:%d\n", host, port)
    fmt.Printf("Debug: %v, Timeout: %v\n", debug, timeout)

    // 機密データ
    secret := loader.GetSecure("API_KEY")
    if secret != nil {
        defer secret.Release()
        fmt.Printf("API Key length: %d\n", secret.Length())
    }

    // システム環境に適用
    if err := loader.Apply(); err != nil {
        log.Fatal(err)
    }

    // すべての変数
    fmt.Printf("Loaded %d variables\n", loader.Len())
    fmt.Printf("Load time: %v\n", loader.LoadTime())
}

Loader API ​

型定義 ​

作成 ​

New ​

ファイル読み込み ​

LoadFiles ​

値の取得 ​

キー名の解決 ​

GetString ​

GetInt ​

GetBool ​

GetUint64 ​

GetFloat64 ​

GetDuration ​

GetSecure ​

スライス値の取得 ​

Lookup ​

設定と削除 ​

Set ​

Delete ​

コレクション操作 ​

Keys ​

All ​

Len ​

システムへの適用 ​

Apply ​

IsApplied ​

状態クエリ ​

LoadTime ​

Config ​

検証とマッピング ​

Validate ​

ParseInto ​

リソース解放 ​

Close ​

IsClosed ​

完全な例 ​

関連ドキュメント ​

Loader API

型定義

作成

New

ファイル読み込み

LoadFiles

値の取得

キー名の解決

GetString

GetInt

GetBool

GetUint64

GetFloat64

GetDuration

GetSecure

スライス値の取得

Lookup

設定と削除

Set

Delete

コレクション操作

Keys

All

Len

システムへの適用

Apply

IsApplied

状態クエリ

LoadTime

Config

検証とマッピング

Validate

ParseInto

リソース解放

Close

IsClosed

完全な例

関連ドキュメント