Understanding SpringBoot’s Environment and PropertySource: Core Concepts and Practical Usage

Core Architecture of Spring Boot Configuration

Every configuration source—YAML files, environment variables, command‑line arguments, configuration‑center entries—gets wrapped as a PropertySource object. The Environment bean holds an ordered List<PropertySource<?>> and traverses it when a key is requested. The first PropertySource that contains the key supplies the value, so the list order defines priority (earlier entries win).

All sources become PropertySource instances. Environment maintains the ordered list.

When a key is looked up, the list is scanned from the beginning.

The position of a PropertySource determines its precedence.

Environment Interface Details

Environment

resides in org.springframework.core.env and abstracts configuration access across all sources. It extends ConfigurablePropertyResolver and adds profile management.

Inheritance Hierarchy

// Top‑level interface
PropertyResolver
    ↓ extends
ConfigurablePropertyResolver // adds type conversion, validation
    ↓ extends
Environment // adds profile support
    ↓ implemented by
AbstractEnvironment // maintains PropertySource list and profiles
    ↓ concrete classes
StandardEnvironment // non‑web
StandardServletEnvironment // web (default for Spring Boot)

In a typical Spring Boot web application, StandardServletEnvironment is used, automatically loading web‑related property sources.

Two Core Functions of Environment

Manage PropertySources : holds the list and provides methods to add, remove, or reorder sources.

Manage Profiles : tracks active and default profiles and offers checks such as acceptsProfiles.

PropertySource Management API

// Read‑only view of all sources
MutablePropertySources getPropertySources();
// Add source with highest priority
void addFirst(PropertySource<?> propertySource);
// Add source with lowest priority
void addLast(PropertySource<?> propertySource);
// Insert before/after a named source
void addBefore(String relativeName, PropertySource<?> propertySource);
void addAfter(String relativeName, PropertySource<?> propertySource);
// Remove a source by name
void remove(String propertySourceName);

Profile Management API

String[] getActiveProfiles();
String[] getDefaultProfiles();
void setActiveProfiles(String... profiles);
boolean acceptsProfiles(String... profiles);
boolean acceptsProfiles(Profiles profiles);

Common Usage

Inject Environment via @Autowired or constructor and call methods such as getProperty, getRequiredProperty, or resolvePlaceholders. Example controller:

@RestController
@RequiredArgsConstructor
public class EnvController {
    private final Environment environment;

    @GetMapping("/env/info")
    public Map<String, Object> getEnvInfo() {
        Map<String, Object> map = new HashMap<>();
        String appName = environment.getProperty("spring.application.name");
        Integer port = environment.getProperty("server.port", Integer.class);
        Boolean dev = environment.getProperty("spring.profiles.active", String.class).equals("dev");
        String timeout = environment.getProperty("myapp.timeout", String.class, "5000");
        String dbUrl = environment.getRequiredProperty("spring.datasource.url", String.class);
        String[] active = environment.getActiveProfiles();
        String[] defaults = environment.getDefaultProfiles();
        boolean acceptDev = environment.acceptsProfiles("dev");
        String appInfo = environment.resolvePlaceholders("${spring.application.name}:${server.port}");
        map.put("appName", appName);
        map.put("port", port);
        map.put("devEnv", dev);
        map.put("timeout", timeout);
        map.put("dbUrl", dbUrl);
        map.put("activeProfiles", active);
        map.put("appInfo", appInfo);
        return map;
    }
}

Accessing /env/info returns the collected configuration values, including profile data and placeholder resolution.

PropertySource Details

PropertySource

abstracts a single configuration origin. Subclasses implement getProperty(String key) to fetch values from their underlying store (Map, Properties, YAML, etc.).

public abstract class PropertySource<T> {
    protected final String name;
    protected final T source;
    public PropertySource(String name, T source) { this.name = name; this.source = source; }
    public abstract Object getProperty(String key);
    public String getName() { return this.name; }
    public T getSource() { return this.source; }
    public boolean containsProperty(String key) { return getProperty(key) != null; }
}

Each concrete PropertySource implements its own retrieval logic.

The name uniquely identifies the source (e.g., applicationConfig: [classpath:/application.yml]).

The source holds the raw data structure (Map for YAML, Properties for .properties files, etc.).

Common Implementations in Spring Boot

CommandLinePropertySource – command‑line arguments (e.g., --server.port=8081); highest priority.

SystemEnvironmentPropertySource – OS environment variables; second highest.

JvmSystemPropertiesPropertySource – JVM -D parameters; higher than config files.

ConfigFileApplicationListener$ConfigurationPropertySource – application-{profile}.yml; activated profile files.

ConfigFileApplicationListener$ConfigurationPropertySource – default application.yml; loaded for all profiles.

ClassPathResourcePropertySource – additional classpath files (e.g., custom.yml); requires @PropertySource to load.

DefaultPropertySource – Spring Boot built‑in defaults (e.g., port 8080); lowest priority.

Debugging: List All PropertySources

When configuration priority appears confused, expose the current list:

@RestController
@RequiredArgsConstructor
public class PropertySourceController {
    private final Environment environment;

    @GetMapping("/env/property-sources")
    public Map<String, Object> getPropertySources() {
        ConfigurableEnvironment env = (ConfigurableEnvironment) environment;
        MutablePropertySources sources = env.getPropertySources();
        Map<String, Object> result = new HashMap<>();
        sources.forEach(ps -> result.put(ps.getName(), ps.getSource().getClass().getSimpleName()));
        return result;
    }
}

The endpoint returns a JSON map of source names to their concrete class names, making it easy to verify order and presence.

Extending Environment & PropertySource

Adding a Custom PropertySource with Highest Priority

@Configuration
public class CustomPropertySourceConfig {
    @Bean
    public CommandLineRunner customPropertySource(ConfigurableEnvironment env) {
        return args -> {
            Map<String, Object> map = new HashMap<>();
            map.put("spring.application.name", "custom-app");
            map.put("server.port", 8088);
            PropertySource<?> ps = new MapPropertySource("customPropertySource", map);
            env.getPropertySources().addFirst(ps);
            System.out.println("Custom source applied, appName: " + env.getProperty("spring.application.name"));
        };
    }
}

After startup, server.port becomes 8088 and the application name changes to custom-app.

Database‑Backed PropertySource

Define a PropertySource that queries a sys_config table:

public class DbPropertySource extends PropertySource<JdbcTemplate> {
    public DbPropertySource(String name, JdbcTemplate source) { super(name, source); }
    @Override
    public Object getProperty(String key) {
        String sql = "SELECT config_value FROM sys_config WHERE config_key = ?";
        try { return getSource().queryForObject(sql, String.class, key); }
        catch (Exception e) { return null; }
    }
}

Register it before the default application.yml source:

@Configuration
public class DbConfigSourceConfig {
    @Autowired private JdbcTemplate jdbcTemplate;
    @Bean
    public CommandLineRunner dbPropertySource(ConfigurableEnvironment env) {
        return args -> {
            PropertySource<?> ps = new DbPropertySource("dbPropertySource", jdbcTemplate);
            env.getPropertySources().addBefore("applicationConfig: [classpath:/application.yml]", ps);
            System.out.println("DB config loaded: " + env.getProperty("db.custom.config"));
        };
    }
}

Dynamic Refresh with a Configuration Center (e.g., Nacos)

Listen for change events and replace the underlying map of the Nacos MapPropertySource:

@Component
public class NacosConfigRefreshListener {
    @Autowired private ConfigurableEnvironment environment;

    @EventListener(NacosConfigChangedEvent.class)
    public void onConfigChanged(NacosConfigChangedEvent event) {
        Map<String, Object> newConfig = event.getConfigInfo();
        MutablePropertySources sources = environment.getPropertySources();
        PropertySource<?> ps = sources.get("nacosConfigSource");
        if (ps instanceof MapPropertySource) {
            ((MapPropertySource) ps).getSource().putAll(newConfig);
        }
        System.out.println("Nacos config updated: " + event.getKeys());
    }
}

In real projects the Nacos or Apollo starter performs this automatically; the listener illustrates the underlying mechanism.

Complete Configuration Loading Chain

Spring Boot starts and creates a StandardServletEnvironment instance.

Default sources (OS env, JVM params, Spring defaults) are loaded. ConfigFileApplicationListener loads application.yml and any active‑profile files, wrapping them as PropertySource objects.

Custom @PropertySource files are added (normally at the end of the list).

Command‑line arguments and configuration‑center sources are inserted at the front, giving them highest priority.

When a component reads a property (via @Value, @ConfigurationProperties, or direct Environment calls), the environment scans the list in order and returns the first matching value.

Priority Summary (High → Low)

Command line args > OS env vars > JVM params > application-{profile}.yml > application.yml > @PropertySource files > Spring Boot defaults

Example: server.port=8080 in application.yml is overridden by --server.port=8081 on the command line.

Key Takeaways

Environment is the façade; PropertySource is the underlying container.

Configuration priority is dictated by the order of PropertySource instances in the environment.

Debugging can be done by listing all PropertySource entries; custom sources can be added for database, map‑based, or configuration‑center data; hot‑refresh works by updating the relevant PropertySource.