エラー処理

env ライブラリは構造化されたエラー処理メカニズムを提供し、errors.Is と errors.As パターンをサポートしています。

センチネルエラー

ファイルエラー

var (
    ErrFileNotFound  = errors.New("file not found")
    ErrFileTooLarge  = errors.New("file exceeds maximum size limit")
)

使用例：

err := loader.LoadFiles(".env")
if errors.Is(err, env.ErrFileNotFound) {
    log.Println("設定ファイルが存在しません")
}
if errors.Is(err, env.ErrFileTooLarge) {
    log.Println("設定ファイルが大きすぎます")
}

解析エラー

var (
    ErrLineTooLong  = errors.New("line exceeds maximum length limit")
    ErrInvalidKey   = errors.New("invalid key format")
    ErrDuplicateKey = errors.New("duplicate key encountered")
)

セキュリティエラー

var (
    ErrForbiddenKey      = errors.New("key is forbidden for security reasons")
    ErrSecurityViolation = errors.New("security policy violation")
    ErrInvalidValue      = errors.New("invalid value content")
)

禁止キーのチェック（実際は *SecurityError を返し、ErrSecurityViolation に一致）：

err := loader.Set("PATH", "/malicious")
if errors.Is(err, env.ErrSecurityViolation) {
    log.Println("禁止キーの設定を試みました")
}

展開エラー

var ErrExpansionDepth = errors.New("variable expansion depth exceeded")

制限エラー

var ErrMaxVariables = errors.New("maximum number of variables exceeded")

ステータスエラー

var (
    ErrClosed             = errors.New("loader has been closed")
    ErrInvalidConfig      = errors.New("invalid configuration")
    ErrAlreadyInitialized = errors.New("default loader already initialized")
    ErrNotInitialized     = errors.New("default loader not initialized; call Load() first")
    ErrMissingRequired    = errors.New("required key is missing")
)

確認方法：

// ローダーがクローズ済みか確認
if errors.Is(err, env.ErrClosed) {
    // ローダークローズ済み
}

// デフォルトローダーが初期化済みか確認
if errors.Is(err, env.ErrAlreadyInitialized) {
    // デフォルトローダーが既に存在し、Load を繰り返し呼び出せません
}

// デフォルトローダーが未初期化か確認
if errors.Is(err, env.ErrNotInitialized) {
    // 先に env.Load() または env.LoadWithConfig() を呼び出す必要がある
}

// 必須キーが不足していないか確認（実際は *ValidationError、Rule=="required"）
var valErr *env.ValidationError
if errors.As(err, &valErr) && valErr.Rule == "required" {
    // 必須キーが不足：valErr.Message に不足キーのリストを含む
}

アダプターエラー

var ErrValidateRequiredUnsupported = errors.New(
    "custom validator does not implement ValidateRequired; " +
    "implement Validator interface for required key validation",
)

カスタムバリデーターが KeyValidator インターフェースのみを実装し、完全な Validator インターフェースを実装していない場合、ValidateRequired を呼び出すとこのエラーが返されます。

確認方法：

if errors.Is(err, env.ErrValidateRequiredUnsupported) {
    // カスタムバリデーターは必須キー検証をサポートしていません
    // 完全な Validator インターフェースを実装する必要がある
}

解決方法

KeyValidator のみではなく、Validator インターフェース（ValidateKey、ValidateValue、ValidateRequired の 3 つのメソッドを含む）を実装してください。

構造化エラー型

ParseError

解析エラー、位置情報を含む：

type ParseError struct {
    File    string  // ファイル名
    Line    int     // 行番号
    Content string  // エラー内容
    Err     error   // 元のエラー
}

使用例：

err := loader.LoadFiles(".env")

var parseErr *env.ParseError
if errors.As(err, &parseErr) {
    log.Printf("解析エラー %s:%d - %s\n",
        parseErr.File, parseErr.Line, parseErr.Err)
    // 出力：解析エラー .env:15 - invalid key format
}

FileError

ファイル操作エラー：

type FileError struct {
    Path  string  // ファイルパス
    Op    string  // 操作
    Err   error   // 元のエラー
    Size  int64   // ファイルサイズ
    Limit int64   // 制限
}

使用例：

var fileErr *env.FileError
if errors.As(err, &fileErr) {
    if fileErr.Size > 0 {
        log.Printf("ファイル %s のサイズ %d が制限 %d を超過\n",
            fileErr.Path, fileErr.Size, fileErr.Limit)
    }
}

SecurityError

セキュリティエラー：

type SecurityError struct {
    Action  string  // 操作
    Reason  string  // 原因
    Key     string  // キー名
    Details string  // 詳細
}

使用例：

var secErr *env.SecurityError
if errors.As(err, &secErr) {
    log.Printf("セキュリティエラー: %s - %s (キー: %s)\n",
        secErr.Action, secErr.Reason, secErr.Key)
}

ValidationError

検証エラー：

type ValidationError struct {
    Field   string  // フィールド名
    Value   string  // 値
    Rule    string  // ルール
    Message string  // メッセージ
}

使用例：

var valErr *env.ValidationError
if errors.As(err, &valErr) {
    log.Printf("検証失敗: フィールド %s - %s\n", valErr.Field, valErr.Message)
}

ExpansionError

変数展開エラー：

type ExpansionError struct {
    Key   string             // キー名
    Depth int                // 現在の深度
    Limit int                // 制限
    Chain string             // 展開チェーン
    Kind  ExpansionErrorKind // エラー原因の分類（ゼロ値 = 深度/循環）
}

使用例：

var expErr *env.ExpansionError
if errors.As(err, &expErr) {
    log.Printf("展開深度超過: %s (チェーン: %s)\n", expErr.Key, expErr.Chain)
}

JSONError

JSON 解析エラー：

type JSONError struct {
    Path    string  // ファイルパス
    Message string  // エラーメッセージ
    Err     error   // 元のエラー
}

使用例：

var jsonErr *env.JSONError
if errors.As(err, &jsonErr) {
    log.Printf("JSON エラー %s: %s\n", jsonErr.Path, jsonErr.Message)
}

YAMLError

YAML 解析エラー：

type YAMLError struct {
    Path    string  // ファイルパス
    Line    int     // 行番号
    Column  int     // 列番号
    Message string  // エラーメッセージ
    Err     error   // 元のエラー
}

使用例：

var yamlErr *env.YAMLError
if errors.As(err, &yamlErr) {
    log.Printf("YAML エラー %s:%d:%d - %s\n",
        yamlErr.Path, yamlErr.Line, yamlErr.Column, yamlErr.Message)
}

MarshalError

シリアライズ/デシリアライズエラー：

type MarshalError struct {
    Field   string  // フィールド名
    Message string  // エラーメッセージ
}

使用例：

_, err := env.MarshalStruct(invalidData)
if err != nil && env.IsMarshalError(err) {
    var marshalErr *env.MarshalError
    if errors.As(err, &marshalErr) {
        log.Printf("シリアライズエラー: フィールド %s - %s\n", marshalErr.Field, marshalErr.Message)
    }
}