How Spring Boot Profiles Work Under the Hood: A Deep Dive

Preface

Building on the introductory article "Master Spring Boot Profiles in One Post," this piece investigates Spring Boot Profiles from a source‑code perspective, revealing how the framework isolates and activates environment configurations.

Body

We start with a simple Spring Boot example that prints a User bean containing a single name property. The name value is injected from the external configuration key user.username, which is defined in two property files: application.properties and application‑prod.properties.

When the application starts, the log shows User Bean: User(name=one), indicating that the value was read from application.properties. Adding a line to application.properties and restarting changes the logged name to the value from application‑prod.properties, and the log prints The following profiles are active: prod, confirming that the prod profile is active.

The log originates from SpringApplication#logStartupProfileInfo. Tracing upward reveals that the active profiles are stored in the environment object, which is created in SpringApplication#getOrCreateEnvironment as a StandardEnvironment (or StandardServletEnvironment in web contexts).

The environment is prepared in SpringApplication#prepareContext, where SpringApplicationRunListeners publish an ApplicationEnvironmentPreparedEvent. The ConfigFileApplicationListener handles this event, loading configuration files from four default locations:

file:./config/

file:./

classpath:config/

classpath:

During ConfigFileApplicationListener#onApplicationEvent, the listener invokes addPropertySources, which uses a private Loader class to coordinate property sources and profiles.

The loader performs three key steps: Loader#initializeProfiles adds null and the default profile. Loader#addProfileToEnvironment registers the profile in environment.activeProfiles. Loader#load reads configuration files. For .properties files, PropertiesPropertySourceLoader is used; for .yml/.yaml, YamlPropertySourceLoader is used.

The loader creates Document objects for each file, associates them with spring.profiles.active , and adds the resulting PropertySource to the environment. When the prod profile is active, application‑prod.properties is loaded after the default file, ensuring its values take precedence.

Conclusion

Although the focus is on how Spring Boot loads and applies profiles, the source‑code analysis reveals a sophisticated internal design: dedicated components handle resource loading, data parsing, and event notification, all orchestrated through well‑structured patterns. Effective debugging with IDE breakpoints is essential for navigating this complexity.