@RegisterReflectionForBinding

## The core problem A GraalVM *native image* is an ahead-of-time (AOT) compiled binary. Unlike the JVM, which loads classes lazily and can reflect over anything on the classpath, native-image compilation does *closed-world static analysis*: at build time it computes the set of classes, methods, and fields that are provably reachable from the entry point, and everything else is discarded to shrink the binary and enable optimizations. Crucially, **reflection is opaque to this analysis** — a call like `clazz.getDeclaredConstructor().newInstance()` or Jackson walking a type's getters cannot be traced statically, so those members are dropped and *no reflection metadata* is retained for them. ## Where this bites Spring apps Serialization libraries bind data by reflection: - **Jackson** constructs your DTO via its constructor and reads/writes fields or getter/setter methods; - **Bean Validation** reflects over fields/getters to run constraints. If a DTO used as a `@RequestBody`/`@ResponseBody`, or in a `RestClient`/`WebClient` body, has no reflection hints, the native runtime can throw errors or silently produce empty objects. ## What `@RegisterReflectionForBinding` does It is a Spring Framework annotation (since 6.0) that you place on any Spring bean, `@Configuration` class, or even a method (`@Target({TYPE, METHOD})`). You list the DTO types to keep: - `@RegisterReflectionForBinding(MyDto.class)` or - `@RegisterReflectionForBinding(classes = {A.class, B.class})`. During **Spring AOT processing** (which runs at build time, e.g. via the `native` or `nativeCompile`/`processAot` steps), Spring generates GraalVM *reachability metadata* — historically `reflect-config.json` files under `META-INF/native-image/` — so the listed types (and, for binding, the types reachable through their properties) retain the reflective members needed for serialization/deserialization. ## On the JVM it does nothing These hints are only consulted by the native-image builder. Running on the normal JVM, the annotation is inert, so it is safe to leave in place. ## When you actually need it Spring's AOT engine already auto-detects many binding types — for example DTOs directly referenced by `@RequestMapping` controller method signatures. You reach for `@RegisterReflectionForBinding` for types Spring *can't* infer: - bodies passed to `RestClient`/`RestTemplate`/`WebClient` at runtime, - types resolved only through generics or `ParameterizedTypeReference`, - types deserialized manually with an `ObjectMapper`, - or polymorphic subtypes. It saves you from hand-writing `reflect-config.json` or a `RuntimeHintsRegistrar`. ## Key takeaways / gotchas - (1) It's a *build-time* mechanism — you must rebuild the native image for changes to take effect. - (2) It's for *reflection*, not for resources, proxies, or serialization-interface hints (those have their own hint types). - (3) Missing hints often fail loudly at native runtime, not at build time, so integration tests against the native binary matter.