Ankur Mhatre
86246dc860
configuration-properties/ @ConfigurationProperties vs @Value on Spring Boot 4.1.1. The relaxed-binding matrix is generated by binding each spelling rather than transcribed, and re-checked against real processes -- the in-process probe was wrong twice before it was right. Records the three findings that came out of it: @Value does get relaxed resolution inside Spring Boot (Boot attaches ConfigurationPropertySources), the configuration processor silently stops generating metadata on JDK 23+ when declared as a plain dependency, and @Valid is not what makes nested constraints run. profiles-and-config/ Precedence, profiles, spring.config.import and config trees. /precedence reports every source holding a property in rank order with file and line, which turns "my profile file had no effect" into a two-line answer. Also pins the counterintuitive one: an imported file outranks the file that imported it. spring-aop/ Designators, proxy types, and aspects that do not fire. One advice per supported designator so the reference table is generated from real matches; all fourteen unsupported designators fed to the parser. Two corrections to the reference documentation: unsupported designators throw UnsupportedPointcutPrimitiveException (extends RuntimeException, not IllegalArgumentException), and spring-boot-starter-aop was renamed to spring-boot-starter-aspectj in Boot 4. 19 contract tests across the three modules, 15 captured transcripts, all regenerated by scripts/run-all.sh. Verified on Spring Boot 4.1.1, Spring Framework 7.0.9, JDK 25.0.4.1. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Gip4srpzMwjgoba6uEfbr5
63 lines
3.3 KiB
Markdown
63 lines
3.3 KiB
Markdown
[← Two mechanisms](01-two-mechanisms.md) · [Index](../README.md) · [Registration →](03-registration.md)
|
|
|
|
# 2. Relaxed binding, measured
|
|
|
|
Everything here is generated by [`RelaxedBindingProbe`](../src/main/java/com/ankurm/configprops/web/RelaxedBindingProbe.java)
|
|
and re-checked against real processes by [`demo-env-binding.sh`](../scripts/demo-env-binding.sh).
|
|
Transcripts: [`01-relaxed-matrix.txt`](output/01-relaxed-matrix.txt),
|
|
[`02-env-var-binding.txt`](output/02-env-var-binding.txt).
|
|
|
|
## The canonical form
|
|
|
|
Every property has one canonical name: lower case, words separated by `-`, levels separated by
|
|
`.`. For `RelaxedProperties.apiKey` under prefix `demo.relaxed`, that is
|
|
`demo.relaxed.api-key`.
|
|
|
|
## What matches it
|
|
|
|
| Spelling | Source | Binder | `${}` plain Spring | `${}` in Spring Boot |
|
|
|---|---|---|---|---|
|
|
| `demo.relaxed.api-key` | file / `-D` | bound | bound | bound |
|
|
| `demo.relaxed.apiKey` | file / `-D` | bound | MISS | bound |
|
|
| `demo.relaxed.api_key` | file / `-D` | bound | MISS | bound |
|
|
| `demo.relaxed.APIKEY` | file / `-D` | bound | MISS | bound |
|
|
| `DEMO.RELAXED.API-KEY` | file / `-D` | bound | MISS | bound |
|
|
| `demo.relaxed.apikey` | file / `-D` | bound | MISS | bound |
|
|
| `demo.relaxed.api.key` | file / `-D` | **MISS** | MISS | **MISS** |
|
|
| `DEMO_RELAXED_API_KEY` | env var | bound | bound | bound |
|
|
| `DEMO_RELAXED_APIKEY` | env var | bound | MISS | bound |
|
|
| `demo_relaxed_api_key` | env var | bound | bound | bound |
|
|
|
|
## Reading it
|
|
|
|
**Dashes, underscores and case are noise.** `ConfigurationPropertyName` compares elements in a
|
|
"uniform" form with separators removed and case folded, so `api-key`, `apiKey`, `api_key` and
|
|
`apikey` are the same name.
|
|
|
|
**A dot is not noise.** `demo.relaxed.api.key` is four name elements; `demo.relaxed.api-key` is
|
|
three. Nothing relaxed will ever join them. This is the one spelling that genuinely fails, and
|
|
it is the one people write when they are guessing.
|
|
|
|
**`@Value` gets relaxed resolution too — but only inside Spring Boot.** The widely repeated
|
|
claim that `@Value` does not support relaxed binding is a statement about the Spring Framework.
|
|
Spring Boot calls `ConfigurationPropertySources.attach(environment)` while preparing every
|
|
environment, which inserts a property source that resolves placeholders through the binder's
|
|
name matching. Remove that call and the middle column is what you get.
|
|
|
|
That is worth knowing in both directions: you can rely on it in a Boot application, and you
|
|
cannot rely on it in a plain `ApplicationContext`, a standalone `Environment` or a test that
|
|
builds one by hand.
|
|
|
|
## Environment variables
|
|
|
|
Both `DEMO_RELAXED_API_KEY` and `DEMO_RELAXED_APIKEY` work. Prefer the first: `_` for every
|
|
separator, upper case throughout. It is the form the binder generates when it goes looking, so
|
|
it is the one that cannot depend on the reverse mapping.
|
|
|
|
A harness note that cost a wrong finding here: Spring Boot decides to apply environment-variable
|
|
name mapping by comparing the property source's *name* against
|
|
`StandardEnvironment.SYSTEM_ENVIRONMENT_PROPERTY_SOURCE_NAME`, not by checking its type. A
|
|
`SystemEnvironmentPropertySource` registered under any other name is mapped with the ordinary
|
|
rules. A test that builds one by hand and names it something descriptive will report that
|
|
underscore spellings do not bind, and will be wrong.
|