README
¶
Environment
Overview
The Environment component provides utilities for working with environment variables in Go applications. It simplifies the process of retrieving environment variables with fallback values, making configuration via environment variables more robust and convenient.
Features
- Simple API: Easy-to-use functions for retrieving environment variables
- Fallback Values: Automatic fallback to default values when environment variables are not set
- Zero Dependencies: No external dependencies beyond the Go standard library
- Type Safety: Clear function signatures for type-safe environment variable handling
- Testability: Easy to mock for testing purposes
Installation
go get github.com/abitofhelp/servicelib/env
Quick Start
See the Basic Usage example for a complete, runnable example of how to use the environment component.
API Documentation
Key Methods
GetEnv
Retrieves the value of the environment variable named by the key. If the variable is not present, the fallback value is returned.
func GetEnv(key, fallback string) string
Examples
For complete, runnable examples, see the following directories in the EXAMPLES directory:
- Basic Usage - Shows basic usage of environment variables with fallbacks
- Config Integration - Shows how to integrate environment variables with a configuration structure
Best Practices
- Use Descriptive Keys: Choose clear, descriptive names for environment variables
- Provide Sensible Defaults: Always provide reasonable fallback values for non-critical settings
- Validate Values: Validate environment variable values before using them in your application
- Document Required Variables: Clearly document which environment variables are required and which are optional
- Use Prefixes: Use prefixes for environment variables to avoid naming conflicts (e.g., APP_PORT instead of PORT)
Troubleshooting
Common Issues
Environment Variables Not Being Read
If your environment variables are not being read:
- Verify that the variables are actually set in the environment
- Check for typos in the variable names
- Ensure the variables are exported properly in your shell
- Remember that environment variables are case-sensitive
Unexpected Values
If you're getting unexpected values:
- Check if the variable is being overridden elsewhere
- Verify that the variable is set at the correct scope (system vs. user vs. process)
- Ensure there are no leading or trailing whitespaces in the variable value
Related Components
- Config - Configuration management that can use environment variables
- Logging - Logging component that can be configured via environment variables
Contributing
Contributions to this component are welcome! Please see the Contributing Guide for more information.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Documentation
¶
Overview ¶
Package env provides utilities for working with environment variables.
This package offers a simple and consistent way to access environment variables with fallback values, making it easier to configure applications through the environment. Using environment variables for configuration is a best practice for cloud-native applications, following the principles of the Twelve-Factor App methodology.
The package is designed to be lightweight and focused on a single responsibility: retrieving environment variables with sensible defaults. This helps prevent application crashes due to missing environment variables and reduces the need for conditional checks throughout the codebase.
Key features:
- Retrieval of environment variables with fallback values
- Simple, consistent API for environment access
- Zero external dependencies
Example usage:
// Get database connection string with a default value
dbConnString := env.GetEnv("DATABASE_URL", "postgres://localhost:5432/mydb")
// Get application port with a default value
port := env.GetEnv("PORT", "8080")
// Get log level with a default value
logLevel := env.GetEnv("LOG_LEVEL", "info")
The package is typically used during application startup to load configuration values from the environment. It can be used directly or as part of a more comprehensive configuration system.
Package env provides utilities for working with environment variables.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetEnv ¶
GetEnv retrieves the value of the environment variable named by the key. If the variable is not present, the fallback value is returned. Parameters:
- key: The name of the environment variable
- fallback: The value to return if the environment variable is not set
Returns:
- string: The value of the environment variable or the fallback value
Types ¶
This section is empty.
Source Files