Introduction

Custom variables in application.properties are the standard Spring Boot way to externalize application-specific behavior. Instead of hardcoding URLs, feature flags, retry limits, or timeouts in Java classes, define them under a clear prefix and let Spring bind them into your application.

Define Application-Specific Keys

The simplest pattern is to choose a prefix such as app. and keep related settings under it:

1app.name=Order Service
2app.timeout-ms=1500
3app.retry.max-attempts=3
4app.feature.new-checkout=true

This avoids collisions with built-in Spring properties and makes it obvious which settings belong to your code rather than to the framework.

Inject Small Numbers of Properties with @Value

For a few isolated values, @Value works fine:

1import org.springframework.beans.factory.annotation.Value;
2import org.springframework.stereotype.Component;
3
4@Component
5public class AppConfigView {
6
7    @Value("${app.name}")
8    private String appName;
9
10    @Value("${app.timeout-ms:1000}")
11    private int timeoutMs;
12
13    public String getAppName() {
14        return appName;
15    }
16
17    public int getTimeoutMs() {
18        return timeoutMs;
19    }
20}

The :1000 part is a default value. It is useful for optional settings, but once you have many related values, @Value becomes harder to maintain.

Prefer @ConfigurationProperties for Groups

For structured configuration, bind a whole prefix into a dedicated class:

1import org.springframework.boot.context.properties.ConfigurationProperties;
2import org.springframework.stereotype.Component;
3
4@Component
5@ConfigurationProperties(prefix = "app")
6public class AppProperties {
7    private String name;
8    private int timeoutMs;
9    private Retry retry = new Retry();
10
11    public static class Retry {
12        private int maxAttempts;
13
14        public int getMaxAttempts() { return maxAttempts; }
15        public void setMaxAttempts(int maxAttempts) { this.maxAttempts = maxAttempts; }
16    }
17
18    public String getName() { return name; }
19    public void setName(String name) { this.name = name; }
20
21    public int getTimeoutMs() { return timeoutMs; }
22    public void setTimeoutMs(int timeoutMs) { this.timeoutMs = timeoutMs; }
23
24    public Retry getRetry() { return retry; }
25    public void setRetry(Retry retry) { this.retry = retry; }
26}

This approach scales better because:

• the config is type-safe
• the prefix is defined once
• related settings stay grouped

It also makes testing much cleaner because a whole configuration block can be reasoned about as one object.

Override with Environment Variables

Spring Boot lets environment variables override file-based properties. For example:

• 'APP_NAME maps to app.name'
• 'APP_TIMEOUT_MS maps to app.timeout-ms'

Example:

export APP_TIMEOUT_MS=2500

That will override the value from application.properties at runtime. This is especially useful in containers and deployment systems where the artifact stays the same but environment-specific values differ.

Use Profiles for Environment Differences

Spring Boot also supports profile-specific files such as:

• 'application.properties'
• 'application-dev.properties'
• 'application-prod.properties'

Activate a profile from configuration or the environment:

spring.profiles.active=dev

or:

export SPRING_PROFILES_ACTIVE=prod

This keeps development, staging, and production differences out of your Java code.

Keep Secrets Out of the File When Possible

Custom variables are great for flags and non-sensitive settings, but secrets need extra care. Avoid checking passwords or tokens into source control. Instead, reference environment variables or a secret manager:

app.api-key=${APP_API_KEY}

That keeps the property binding model consistent while moving the sensitive value out of the repository.

Common Pitfalls

• Mixing application-specific keys with Spring framework keys under no clear naming convention.
• Using @Value for large configuration groups and ending up with scattered property strings everywhere.
• Forgetting that environment variables can override file values at runtime.
• Storing secrets directly in application.properties and committing them to version control.
• Treating configuration as untyped strings when @ConfigurationProperties would give stronger structure.

Summary

• Define custom application properties under a clear prefix such as app..
• Use @Value for a small number of isolated values.
• Prefer @ConfigurationProperties for grouped, structured configuration.
• Override values cleanly with environment variables and profile-specific files.
• Keep sensitive values external even when the property key itself lives in Spring Boot configuration.