backend-spring-config

Spring Config Review

Overview

Review Spring Boot configuration for correct property binding, profile management, conditional bean wiring, lifecycle hygiene, and secrets externalization. Catches issues that are valid Java/Kotlin but invalid Spring patterns.

Triggers only when Spring Boot is detected (a spring-boot-starter* dependency in pom.xml/build.gradle*). Use backend-deployment-safety-review for the multi-instance / rollout angle on the same files.

Version Compatibility

Supported: Spring Boot 3.x (declared via spring_boot_versions: ["3.x"] in frontmatter).

Spring Boot 2.x — degraded coverage:

• G1 (@ConfigurationProperties prefix): applies identically
• G3 (immutable config): SB2.2+ supports constructor binding via @ConfigurationPropertiesScan; SB2.0/2.1 require explicit @ConstructorBinding. SB3 makes constructor binding the default
• All other checks: framework-stable across SB2/SB3

To add full SB2 coverage, follow Pattern A (broaden the rubric) per shield/skills/backend/EXTENDING-VERSIONS.md.

When to Use

• Reviewing application.yml, application-{profile}.yml, or application.properties
• Reviewing @Configuration/@Bean/@ConfigurationProperties classes
• Reviewing @ConditionalOn* usage
• Pre-implementation: shaping the config surface during planning

When NOT to Use

• Pure runtime config (env vars, K8s ConfigMaps) — operational concern
• Build-time config (Maven/Gradle property substitution) — different phase
• Non-Spring frameworks (Quarkus application.properties, Micronaut config) — same concepts but different annotations

Review Process

1. Inventory: application*.yml/.properties files, @Configuration classes, @ConfigurationProperties POJOs/records, @Bean methods
2. For each artifact, apply Evaluation Points G1–G10
3. Cross-cut: trace a property from application.yml to its consumer; flag any binding gap

Evaluation Points

#	Check	What to Look For	Severity
G1	@ConfigurationProperties prefix	Always set prefix = "...". Without it, properties won't bind to nested keys correctly	High
G2	Validation on config types	@Validated + JSR-303 annotations on @ConfigurationProperties so invalid config fails at startup, not runtime	Medium
G3	Immutable config types	Prefer records or constructor binding (@ConfigurationPropertiesScan + immutable POJO) over getter/setter mutability	Medium
G4	@Value vs @ConfigurationProperties	For typed groups of config, prefer @ConfigurationProperties. @Value is OK for one-off literals or SpEL	Medium
G5	Profile correctness	application-{profile}.yml files exist for each declared profile. No profile-specific behavior baked into base config	Medium
G6	Secrets in committed source	No passwords, API keys, or tokens in application*.yml / application*.properties. Use env vars, config server, or secret manager	High
G7	@ConditionalOn* correctness	@ConditionalOnProperty etc. apply to the right bean and have correct havingValue/matchIfMissing semantics	High
G8	@Bean lifecycle	No state in the @Bean method body that mutates a singleton context; no manual new SomeBean() outside @Bean for managed components	Medium
G9	@ComponentScan boundaries	Default scan covers the right packages; no overly broad scans that pick up test classes in production	Medium
G10	Default profile fallback	Sensible defaults in application.yml; profile files override only what changes	Low