README
¶
Config Package
The config package provides a reusable and extensible configuration loader built on top of Viper. It is designed to simplify configuration management in Go applications by supporting multiple config sources, context propagation, and functional loading options.
Features
- Environment-First Configuration: Automatically reads from environment variables.
- YAML File Support: Load config from
.yamlfiles (required or optional). - Injectable Defaults: Provide fallback values when env or file values are not present.
- Context Integration: Easily inject and retrieve config via
context.Contextor*http.Request.
Installation
go get github.com/kittipat1413/go-common/framework/config
Documentation
For detailed API documentation, examples, and usage patterns, visit the Go Package Documentation.
Usage
This is the simplest way to get started using MustConfig with some defaults:
package main
import (
"fmt"
"github.com/kittipat1413/go-common/framework/config"
)
func main() {
cfg := config.MustConfig(
config.WithRequiredConfigPath("env.yaml"),
config.WithDefaults(map[string]any{
"SERVICE_NAME": "my-service",
"SERVICE_PORT": ":8080",
"ENV": "development",
}),
)
// Read config values
serviceName := cfg.GetString("SERVICE_NAME")
port := cfg.GetString("SERVICE_PORT")
env := cfg.GetString("ENV")
fmt.Println("=== Service Config ===")
fmt.Printf("Service Name: %s\n", serviceName)
fmt.Printf("Port: %s\n", port)
fmt.Printf("Environment: %s\n", env)
}
With an optional env.yaml override:
SERVICE_NAME: "user-api"
SERVICE_PORT: ":9090"
ENV: "staging"
Examples
- You can find a complete working example in the repository under framework/config/example.
Functional Options
WithRequiredConfigPath(path string): Fails if the file does not exist or is unreadable.
config.WithRequiredConfigPath("env.yaml")
WithOptionalConfigPaths(path string): Tries each path in order and uses the first found file. Skips missing files.
config.WithOptionalConfigPaths("env.yaml")
WithDefaults(defaults map[string]any): Injects fallback values if the config key is not set in env or file.
config.WithDefaults(map[string]any{
"SERVICE_NAME": "my-service",
"SERVICE_PORT": ":8080",
"ENV": "development",
})
Accessing Values
cfg.Get("SERVICE_NAME") // any type
cfg.GetString("SERVICE_NAME") // string
cfg.GetInt("MAX_WORKERS") // int
cfg.GetDuration("TIMEOUT") // string, use time.ParseDuration
cfg.All() // map[string]interface{}
Documentation
¶
Index ¶
- func NewContext(ctx context.Context, cfg *Config) context.Context
- func NewRequest(r *http.Request, cfg *Config) *http.Request
- type Config
- func (c *Config) All() map[string]interface{}
- func (c *Config) Get(key string) any
- func (c *Config) GetBool(key string) bool
- func (c *Config) GetDuration(key string) time.Duration
- func (c *Config) GetFloat64(key string) float64
- func (c *Config) GetInt(key string) int
- func (c *Config) GetIntSlice(key string) []int
- func (c *Config) GetString(key string) string
- func (c *Config) GetStringMap(key string) map[string]any
- func (c *Config) GetStringMapString(key string) map[string]string
- func (c *Config) GetStringMapStringSlice(key string) map[string][]string
- func (c *Config) GetStringSlice(key string) []string
- func (c *Config) GetTime(key string) time.Time
- type Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewContext ¶
NewContext creates a new context.Context with the provided Config instance attached.
Example:
// Inject into root context ctx := config.NewContext(context.Background(), appConfig) // Use ctx in your application ...
Types ¶
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config wraps a Viper instance to provide a simplified interface for configuration management. It offers type-safe methods for retrieving configuration values and handles the underlying Viper complexity.
func FromContext ¶
FromContext retrieves a Config instance from the provided context.Context.
Example:
cfg := config.FromContext(ctx)
func FromRequest ¶
FromRequest retrieves a Config instance from an http.Request's context.
Example:
cfg := config.FromRequest(r)
func MustConfig ¶
MustConfig creates and returns a new Config instance using the provided options. It behaves like NewConfig but will terminate the program with log.Fatalln if any error occurs.
This function is typically used at application startup when configuration loading is critical and the application cannot continue without proper configuration.
Warning: This function calls log.Fatalln on error, which will terminate the program. Use NewConfig if you need error handling instead of program termination.
Example:
// Global config that must load or app fails to start
var AppConfig = config.MustConfig(
config.WithRequiredConfigPath("env.yaml"),
config.WithDefaults(map[string]any{
"SERVICE_PORT": ":8080",
"DEBUG_MODE": false,
}),
)
func main() {
port := AppConfig.GetString("SERVICE_PORT")
// ... rest of application
}
func NewConfig ¶
NewConfig creates and returns a new Config instance using the provided options. It initializes Viper with automatic environment variable reading and applies all options in order.
Environment variable reading is automatically enabled, meaning any environment variable can be accessed using its name as a key.
Example:
config, err := NewConfig(
WithOptionalConfigPaths("config.yaml"),
WithDefaults(map[string]any{
"SERVICE_PORT": ":8080",
}),
)
if err != nil {
log.Fatalf("Failed to load config: %v", err)
}
func (*Config) All ¶
All returns a map containing all configuration key-value pairs. This includes values from all sources (defaults, config files, environment variables).
Keys are normalized to lowercase. This is useful for debugging configuration or when you need to iterate over all available configuration values.
func (*Config) GetDuration ¶
GetDuration retrieves the value associated with the key as a time.Duration.
func (*Config) GetFloat64 ¶
GetFloat64 retrieves the value associated with the key as a float64.
func (*Config) GetIntSlice ¶
GetIntSlice retrieves the value associated with the key as a slice of integers.
func (*Config) GetStringMap ¶
GetStringMap retrieves the value associated with the key as a map[string]any.
func (*Config) GetStringMapString ¶
GetStringMapString retrieves the value associated with the key as a map[string]string.
func (*Config) GetStringMapStringSlice ¶
GetStringMapStringSlice retrieves the value associated with the key as a map[string][]string.
func (*Config) GetStringSlice ¶
GetStringSlice retrieves the value associated with the key as a slice of strings.
type Option ¶
Option is a function that configures the Viper instance during initialization. Options are applied in the order they are provided to NewConfig or MustConfig.
func WithDefaults ¶
WithDefaults injects fallback configuration values into the Viper instance. These values are used when no value is found in config files or environment variables.
Default values should use the same key names as expected in config files and environment variables.
Example:
config := MustConfig(
WithDefaults(map[string]any{
"SERVICE_PORT": ":8080",
"DEBUG_MODE": false,
"DATABASE.TIMEOUT": "30s",
"REDIS.POOL_SIZE": 10,
}),
)
func WithOptionalConfigPaths ¶
WithOptionalConfigPaths attempts to load the first configuration file found from the given list of paths. It will silently skip missing files but return an error if a file exists but cannot be read or parsed.
Example:
// Try local config first, then fallback to default location config := MustConfig( WithOptionalConfigPaths( "./local.env.yaml", "./config/env.yaml", "/etc/myapp/config.yaml", ), )
func WithRequiredConfigPath ¶
WithRequiredConfigPath forces the specified configuration file to exist and be readable. If the file doesn't exist or cannot be read, an error is returned.
Example:
config := MustConfig(
WithRequiredConfigPath("./config/production.yaml"),
)
Source Files
Directories