Spring Boot Auto-configuration & Config

@SpringBootApplication includes @EnableAutoConfiguration, which imports every class listed in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports from jars on the classpath. Each is guarded by conditions such as @ConditionalOnClass(DataSource.class) and @ConditionalOnMissingBean.

• DataSourceAutoConfiguration creates a Hikari pool when spring.datasource.url is present (or an embedded DB if one is on the classpath).
• User-defined beans always back off auto-configured ones via @ConditionalOnMissingBean.
• spring.factories was replaced for auto-config by the .imports file in Boot 2.7/3.0.

Run with --debug (or debug=true) to print the Conditions Evaluation Report: "Positive matches", "Negative matches" with the failing condition, and "Unconditional classes". The actuator /actuator/conditions endpoint shows the same at runtime.

• Typical negatives: @ConditionalOnClass (starter missing), @ConditionalOnMissingBean (you defined your own), @ConditionalOnProperty (flag off), @ConditionalOnWebApplication (wrong type).
• /actuator/beans lists what actually exists.

JacksonAutoConfiguration registers its ObjectMapper with @ConditionalOnMissingBean. Your bean replaces it, so all spring.jackson.* properties, registered modules (JavaTimeModule), and Boot defaults such as FAIL_ON_UNKNOWN_PROPERTIES=false and WRITE_DATES_AS_TIMESTAMPS=false no longer apply.

Customize instead of replacing:

@Bean
Jackson2ObjectMapperBuilderCustomizer customizer() {
    return b -> b.simpleDateFormat("yyyy-MM-dd").serializationInclusion(JsonInclude.Include.NON_NULL);
}

If you must build your own, start from the injected Jackson2ObjectMapperBuilder.

Implement Condition (or extend SpringBootCondition) and annotate with @Conditional(MyCondition.class). Use it when built-in conditions cannot express the rule, for example "a cloud metadata variable exists and a class is present".

class OnKubernetesCondition implements Condition {
    public boolean matches(ConditionContext ctx, AnnotatedTypeMetadata md) {
        return ctx.getEnvironment().getProperty("KUBERNETES_SERVICE_HOST") != null;
    }
}

• Conditions run during configuration parsing, before beans exist; do not look up beans in them (except via ConditionalOnBean semantics in auto-config).
• Wrap as a meta-annotation for readability.

Two modules by convention: acme-spring-boot-autoconfigure (auto-configuration, @ConfigurationProperties, .imports file) and acme-spring-boot-starter (empty jar with dependencies). A single module is acceptable for internal use.

@AutoConfiguration
@ConditionalOnClass(AcmeClient.class)
@EnableConfigurationProperties(AcmeProperties.class)
public class AcmeAutoConfiguration {
    @Bean @ConditionalOnMissingBean
    AcmeClient acmeClient(AcmeProperties p) { return new AcmeClient(p.getUrl()); }
}

Register in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. Add spring-boot-configuration-processor for property metadata. Third-party starters should not use the spring-boot-starter-* prefix; use acme-spring-boot-starter.

Yes. For environment variables Boot converts dots and dashes to underscores and uppercases, so app.max-connections is matched by APP_MAX_CONNECTIONS (the form APP_MAXCONNECTIONS with dashes removed also binds for @ConfigurationProperties).

• In .properties/.yml, prefer kebab-case (app.max-connections); camelCase and underscore forms also bind.
• List items use indexes: APP_HOSTS_0, APP_HOSTS_1.
• @Value supports only limited relaxation, so use @ConfigurationProperties when you rely on env var naming.

Highest to lowest (abridged): command-line args, SPRING_APPLICATION_JSON, system properties, OS environment variables, profile-specific config files (outside the jar, then inside), application config files (outside, then inside), @PropertySource, and finally default properties.

• Test properties (@TestPropertySource, properties=) beat all of those in tests.
• @PropertySource is processed early and low in precedence, and it cannot load YAML without a custom factory.
• A profile-specific file overrides the base file; later spring.config.import entries override earlier ones.

Use spring.config.import (Boot 2.4+) with optional:file:/etc/config/ for config files, or configtree:/etc/secrets/ for one-file-per-property secret mounts.

spring:
  config:
    import:
      - optional:file:/etc/config/application.yml
      - optional:configtree:/etc/secrets/

• Without optional: a missing path fails startup, which is useful in production.
• Keys map from file names; db.password file yields db.password.
• Changes need a restart (or Spring Cloud Kubernetes reload).

The app should fail fast at startup with a binding error. Annotate the class with @Validated and use Jakarta Bean Validation constraints; requires spring-boot-starter-validation.

@ConfigurationProperties("payments")
@Validated
public record PaymentsProperties(@NotBlank String url, @DefaultValue("5s") Duration timeout) {}

• Records or final fields use constructor binding automatically (Boot 3 implicit when single constructor).
• Nested objects need @Valid to cascade validation.
• Without the validation starter on the classpath, constraints are silently ignored.

Measure first: enable ApplicationStartup (BufferingApplicationStartup) and expose /actuator/startup, or use -Ddebug and logging timestamps, plus a profiler/async-profiler on boot.

Common culprits and fixes:

• Eager remote calls in @PostConstruct or runners (DB migrations, cache warmup, config servers): move to async or after readiness.
• Large component scan or classpath scan: narrow scanBasePackages.
• Hibernate schema validation/ddl-auto, Flyway on big histories.
• Connection pool initialization with initialization-fail-timeout retries on an unreachable DB.
• Many auto-configurations: exclude unused ones; consider spring.main.lazy-initialization, CDS/AppCDS, or native.

Liveness answers "should this process be restarted?"; readiness answers "should it receive traffic?". Boot exposes /actuator/health/liveness and /readiness when running on Kubernetes (or with management.endpoint.health.probes.enabled=true).

• Mistake: including a downstream dependency (DB, third-party) in the liveness group. When the DB blips, all pods fail liveness and restart together, turning a partial outage into a total one.
• Keep dependencies in readiness at most; liveness should reflect only internal unrecoverable state (LivenessState.BROKEN).
• Customize groups: management.endpoint.health.group.readiness.include=readinessState,db.

Endpoints such as env, heapdump, threaddump, configprops, beans, loggers, and mappings leak configuration, credentials (partially sanitized), and internals; loggers and shutdown (if enabled) allow state changes.

• Expose the minimum (health, info, prometheus), secure the rest with Spring Security roles, and consider a separate management port (management.server.port) not routed externally.
• Since Boot 3, show-values for env/configprops defaults to never, but treat the endpoints as sensitive anyway.
• Keys matching password, secret, key, token are sanitized by default; custom names may not be.

Implement HealthIndicator (or extend AbstractHealthIndicator); the bean name minus HealthIndicator becomes the component key.

@Component
class PaymentsHealthIndicator implements HealthIndicator {
    public Health health() {
        return pingOk() ? Health.up().build() : Health.down().withDetail("reason", "timeout").build();
    }
}

Keep the check cheap and time-bounded, because health is polled every few seconds by orchestrators. Do not run expensive queries or call slow third parties synchronously; cache the last result.

Set server.shutdown=graceful and spring.lifecycle.timeout-per-shutdown-phase=30s. On SIGTERM the server stops accepting new requests but lets in-flight requests finish before the context closes (supported for Tomcat, Jetty, Reactor Netty, Undertow).

• On Kubernetes, also add a short preStop sleep because the endpoints controller and the SIGTERM race; otherwise traffic still arrives after shutdown begins.
• terminationGracePeriodSeconds must exceed the Spring timeout.
• Background work (@Async, schedulers) needs its own setWaitForTasksToCompleteOnShutdown and await settings.

Environment.getProperty reads a raw string by exact key with conversion; @ConfigurationProperties uses the Binder with relaxed names, nested objects, lists, maps, and validation.

Multi-document YAML activates sections per profile:

server.port: 8080
---
spring:
  config:
    activate:
      on-profile: prod
server.port: 8443

You cannot place spring.profiles.active inside an on-profile document (it throws InactiveConfigDataAccessException). Replace the old spring.profiles key (removed in 2.4+).

starter-parent (or the spring-boot-dependencies BOM / Gradle plugin) manages compatible dependency versions, so starters need no version. DevTools provides auto-restart and LiveReload using two classloaders.

• DevTools is excluded from the repackaged fat jar by default (optional/developmentOnly), and disabled when run via java -jar; do not include it in production.
• Overriding a managed version (<jackson-bom.version>) can break compatibility with other managed libraries.
• Starters are only dependency descriptors; they contain no code.

Boot repackages into an executable "fat" jar with nested jars. A layered jar (layers.enabled, default since 2.4) splits into dependencies, spring-boot-loader, snapshot-dependencies, application, so Docker caches the rarely-changing dependency layer.

FROM eclipse-temurin:21-jre AS build
COPY app.jar app.jar
RUN java -Djarmode=tools -jar app.jar extract --layers --destination out

• java -Djarmode=layertools was replaced by -Djarmode=tools in 3.3.
• mvn spring-boot:build-image / bootBuildImage uses Cloud Native Buildpacks, with no Dockerfile.
• Extracted layout starts faster than the nested fat jar.

Spring AOT runs at build time, evaluating conditions and generating bean-definition code plus reflection/proxy hints, so the app has a fixed closed-world context. GraalVM then compiles it to a native executable with millisecond startup and lower memory, at the cost of a longer, heavier build and no runtime dynamic class loading.

• Things that break: reflection, resources, proxies, JNI not covered by hints; conditions based on runtime properties (@Profile, @ConditionalOnProperty) are fixed at build time.
• Provide hints with RuntimeHintsRegistrar / @RegisterReflectionForBinding.
• Peak throughput can be lower than JIT-compiled JVM; JIT warmup versus AOT trade-off.
• Alternatives: CDS/AppCDS, CRaC (Boot 3.2+), virtual threads, lazy init.

List and array properties are replaced, not merged, across property sources when a higher-precedence source provides any index of that list. Mixing app.hosts[0] from YAML with APP_HOSTS_1 from env produces surprising partial replacement, while a comma-separated value in one source replaces the entire list.

• Provide the full list in one source.
• Maps, in contrast, are merged across sources by key.
• For profile-specific files, a profile list replaces the base list entirely.

Never commit secrets; inject via environment variables, mounted files (configtree:), or a secrets manager (Vault, AWS Secrets Manager via Spring Cloud). Use management.endpoint.env.show-values=never (or when-authorized) and custom SanitizingFunction beans for non-standard key names.

• Do not log Environment or properties objects; toString() of properties classes can print secrets (exclude them or use records carefully).
• Jasypt-style encrypted values add key-management problems and are not a substitute for a secret store.
• Command-line args show up in ps output, so env or files are safer.

Boot auto-configures applicationTaskExecutor (ThreadPoolTaskExecutor, or a virtual-thread executor when spring.threads.virtual.enabled=true in 3.2+) when no Executor bean exists. Defining your own Executor makes it back off.

• For @Async, a single TaskExecutor/Executor bean named taskExecutor is used, or implement AsyncConfigurer; with multiple executors, name the one in @Async("ioPool").
• Auto-config ordering is declared with @AutoConfiguration(before/after), not @Order.
• Tune spring.task.execution.pool.* properties for the default.

Only the first application.yml found on the classpath root is used (typically your own app's, since it comes first); a library's file of the same name is shadowed, not merged. Libraries should not ship application.yml; use spring.config.import, defaults via @ConfigurationProperties defaults, or META-INF/ properties.

• Use distinctly named files in libraries and have users import them.
• Check effective values at /actuator/configprops and /actuator/env, which show which property source supplies each value.

Spring Boot properties are read at startup, so changing a file does nothing for an already-built DataSource. Options: restart via rolling deploy (simplest and safest), Spring Cloud @RefreshScope plus a rebuilt datasource, or an IAM/Vault dynamic credential mechanism that supplies credentials per connection.

• HikariCP can update username/password via HikariConfigMXBean for new connections, but existing connections stay authenticated until recycled; set maxLifetime below the rotation window.
• Overlap old and new credentials during rotation to avoid failed in-flight connections.

TLS terminates at the proxy, so the app sees plain HTTP and the proxy's IP. Enable forwarded header handling with server.forward-headers-strategy=native (container support, recommended) or framework (ForwardedHeaderFilter).

• Trust only headers from your proxy; otherwise clients can spoof X-Forwarded-For.
• On Kubernetes/Cloud Foundry platforms Boot enables it automatically.
• Tomcat RemoteIpValve settings (server.tomcat.remoteip.*) fine-tune trusted proxies.

@SpringBootApplication = @SpringBootConfiguration + @EnableAutoConfiguration + @ComponentScan with TypeExcludeFilter and AutoConfigurationExcludeFilter filters. Adding your own @ComponentScan on the same class overrides the default scan, so the default filters and the "main package" base are lost unless you restate them.

• Overriding scanBasePackages without listing the main package drops your own classes.
• Test slices (@WebMvcTest) rely on TypeExcludeFilter; a custom scan without it pulls in every @Service and @Repository.

Hikari's initializationFailTimeout defaults to 1 ms, which fails fast: the exception aborts the context. If the app continues, either the datasource is lazy, spring.datasource.hikari.initialization-fail-timeout is set negative (skip), or the failing pool is not the one that matters.

• Fail-fast is usually right behaviour: the orchestrator restarts the pod when the DB is unreachable.
• A background retry is acceptable for non-critical datasources; protect with readiness health indicators.
• JPA's hibernate.temp.use_jdbc_metadata_defaults=false avoids DB contact at boot but defers failures.