Spring Boot ConditionalOnProperty: make optional infrastructure opt in

Last updated: 5 Oct 20264 min read

tutorial

A property condition can register a feature only for an explicit value, with absence and false kept distinct from enabled.

The absent value has meaning

A receipt replay worker should not start merely because its class is on the classpath. @ConditionalOnProperty with havingValue true and matchIfMissing false requires an explicit opt-in setting. That prevents an unreviewed deployment from running a second replay loop. Multi-instance scheduling still needs a claim or leader protocol; a property flag only controls whether a bean is registered on each instance.

Keep deployment and runtime decisions separate

The condition is evaluated while building the context. Changing a property in an external store does not automatically add or remove the worker from an already running context. Use a controlled restart or a separately designed runtime switch with defined drain behavior. Include the flag in the same deployment review as its queue, permissions and monitoring settings. Config precedence matters because command-line, environment and files may disagree about the final value.

Test the matrix

Start a minimal context with the property absent, false and true. Assert that exactly the true case registers ReceiptReplayWorker. Then test a malformed value and verify the intended behavior instead of assuming arbitrary text means enabled. A context test establishes registration; a worker integration test must separately prove idempotent claims, shutdown and retry. Configuration validation should reject a missing queue name when the feature is enabled.

Implementation contract

@AutoConfiguration
@ConditionalOnProperty(
    prefix = "receipt.replay",
    name = "enabled",
    havingValue = "true",
    matchIfMissing = false)
class ReceiptReplayAutoConfiguration {
    @Bean
    ReceiptReplayWorker receiptReplayWorker(ReceiptClaimStore claims) {
        return new ReceiptReplayWorker(claims);
    }
}

Cost and verification

A disabled feature creates no worker or polling load. When enabled, each application instance evaluates the same setting and may start a worker, so database claim contention and polling volume still need explicit bounds.

Common Mistakes

Do not assume a conditional property is a live runtime toggle.
Do not interpret bean registration as proof that only one cluster member will run the worker.
Do not leave required enabled-mode settings unvalidated.