Type-Safe Configuration in Go Without Viper

Introduction

Managing application configuration is a fundamental aspect of software development. As applications grow in complexity, so does the need for a robust, maintainable, and type-safe configuration mechanism. Many Go developers turn to powerful external libraries like Viper to handle this, and for good reason – Viper offers extensive features for reading configuration from various sources, watching for changes, and unmarshaling into Go structs.

However, relying on external dependencies always comes with a trade-off: increased binary size, potential breaking changes in upstream libraries, and a slightly steeper learning curve for new team members. What if we could achieve a significant portion of Viper's benefits, specifically type-safe configuration from environment variables, using only Go's built-in features and standard libraries? This article explores how to craft a simple yet powerful configuration solution using Go struct tags and environment variables, providing a lightweight, type-safe, and dependency-free alternative that's often sufficient for many Go applications.

Core Concepts Explained

Before diving into the implementation, let's briefly define the core concepts that underpin our approach:

• Struct Tags: These are short, optional string literals that can be attached to fields in a Go struct. They are commonly used by standard library packages (like json for marshaling/unmarshaling) and third-party libraries to provide metadata about how a field should be processed. In our case, we'll use them to specify the environment variable name associated with each struct field.
• Environment Variables: These are dynamic named values that can affect the way a running process behaves. They provide a common and easily modifiable way to pass configuration to applications without modifying the codebase. Go's os package provides convenient functions for interacting with environment variables.
• Reflection: A powerful feature in Go that allows a program to inspect and modify its own structure at runtime. We'll use reflection to iterate over the fields of a configuration struct, read their struct tags, and then retrieve corresponding environment variable values.
• Type Safety: Ensuring that variables and expressions are used in a way that is consistent with their defined types. By unmarshaling environment variables into a Go struct with specific types (e.g., int, bool, string), we leverage Go's type system to validate configuration values at runtime and prevent common errors.

Building a Type-Safe Configuration Loader

Our goal is to create a function that takes a pointer to a Go struct, populates its fields from environment variables based on struct tags, and handles type conversion.

The Configuration Struct

First, let's define a sample configuration struct. We'll use a env struct tag to specify the corresponding environment variable name.

package main

import (
    "fmt"
    "os"
    "reflect"
    "strconv"
)

// AppConfig holds our application's configuration.
// 'env' struct tags specify the environment variable name.
type AppConfig struct {
    LogLevel        string `env:"LOG_LEVEL"`
    Port            int    `env:"APP_PORT"`
    DatabaseURL     string `env:"DATABASE_URL"`
    EnableFeatureX  bool   `env:"ENABLE_FEATURE_X"`
    MaxConnections  int    `env:"DB_MAX_CONNECTIONS,default=10"` // Example with a default value
}

// simulateEnvironment sets mock environment variables for testing.
func simulateEnvironment() {
    os.Setenv("LOG_LEVEL", "DEBUG")
    os.Setenv("APP_PORT", "8080")
    os.Setenv("DATABASE_URL", "postgres://user:pass@host:5432/db")
    os.Setenv("ENABLE_FEATURE_X", "true")
    // DB_MAX_CONNECTIONS is not set to test the default
}

The LoadConfig Function

Now, let's implement the LoadConfig function. This function will take a pointer to our AppConfig struct, use reflection to iterate through its fields, read the env tag, fetch the environment variable, and perform type conversion.

// LoadConfig populates the given struct from environment variables.
// The struct fields should have `env:"ENV_VAR_NAME"` tags.
func LoadConfig(config interface{}) error {
    configValue := reflect.ValueOf(config)
    if configValue.Kind() != reflect.Ptr || configValue.IsNil() {
        return fmt.Errorf("config must be a non-nil pointer")
    }

    elem := configValue.Elem()
    elemType := elem.Type()

    for i := 0; i < elem.NumField(); i++ {
        field := elem.Field(i)
        fieldType := elemType.Field(i)

        envTag := fieldType.Tag.Get("env")
        if envTag == "" {
            continue // Skip fields without an 'env' tag
        }

        envVarName := envTag
        defaultValue := ""

        // Check for default value in tag (e.g., "ENV_VAR,default=VALUE")
        if idx := strings.Index(envTag, ",default="); idx != -1 {
            envVarName = envTag[:idx]
            defaultValue = envTag[idx+len(",default="):]
        }


        envValue := os.Getenv(envVarName)

        // Use default value if env var is not set and a default is provided
        if envValue == "" && defaultValue != "" {
            envValue = defaultValue
        } else if envValue == "" && defaultValue == "" {
        	// Optionally, you might want to return an error here for mandatory fields
            // For now, we'll just leave the field at its zero value.
        	continue
        }

        if !field.CanSet() {
            return fmt.Errorf("cannot set field %s", fieldType.Name)
        }

        // Perform type conversion
        switch field.Kind() {
        case reflect.String:
            field.SetString(envValue)
        case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
            intValue, err := strconv.ParseInt(envValue, 10, 64)
            if err != nil {
                return fmt.Errorf("failed to parse int for %s: %w", fieldType.Name, err)
            }
            if field.OverflowInt(intValue) {
                 return fmt.Errorf("value for %s (%d) overflows field type", fieldType.Name, intValue)
            }
            field.SetInt(intValue)
        case reflect.Bool:
            boolValue, err := strconv.ParseBool(envValue)
            if err != nil {
                return fmt.Errorf("failed to parse bool for %s: %w", fieldType.Name, err)
            }
            field.SetBool(boolValue)
        // Add more types as needed (float, duration, etc.)
        default:
            return fmt.Errorf("unsupported field type: %s for field %s", field.Kind().String(), fieldType.Name)
        }
    }
    return nil
}

Usage Example

Finally, let's put it all together and see how to use our LoadConfig function.

import "strings" // Add this import for strings package

func main() {
    simulateEnvironment() // Setup mock env vars

    var config AppConfig
    err := LoadConfig(&config)
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error loading configuration: %v\n", err)
        os.Exit(1)
    }

    fmt.Printf("Application Configuration:\n")
    fmt.Printf("  Log Level: %s\n", config.LogLevel)
    fmt.Printf("  App Port: %d\n", config.Port)
    fmt.Printf("  Database URL: %s\n", config.DatabaseURL)
    fmt.Printf("  Enable Feature X: %t\n", config.EnableFeatureX)
    fmt.Printf("  Max DB Connections: %d\n", config.MaxConnections) // Should show 10 as default
}

When you run this main function, it will:

1. Set simulated environment variables.
2. Call LoadConfig with a pointer to AppConfig.
3. LoadConfig will iterate through AppConfig's fields.
4. For each field with an env tag, it will retrieve the corresponding environment variable.
5. It will then attempt to convert the string value from the environment variable into the correct Go type (string, int, bool).
6. If conversion fails, an error is returned, ensuring type safety.
7. The default value for DB_MAX_CONNECTIONS will be used since os.Setenv("DB_MAX_CONNECTIONS") was not called.

The output will be:

Application Configuration:
  Log Level: DEBUG
  App Port: 8080
  Database URL: postgres://user:pass@host:5432/db
  Enable Feature X: true
  Max DB Connections: 10

This demonstrates a robust and type-safe configuration loading mechanism. You can easily extend LoadConfig to support more types (e.g., float64, time.Duration), add validation logic, or even implement support for multiple environment variable sources by prioritizing them.

Conclusion

By leveraging Go's built-in reflection capabilities and struct tags, alongside standard library packages like os and strconv, we can create a powerful, type-safe, and dependency-free configuration loading mechanism. This approach, while requiring a bit more boilerplate than a full-featured library like Viper, offers excellent control, reduces external dependencies, and is perfectly suitable for many applications, promoting a lightweight and idiomatic Go development style. Embracing Go's standard features for configuration management fosters a deeper understanding of the language and leads to more self-contained, robust applications.