GH-3880: Doc for default @KafkaHandler limitations

Fixes: #3880

Add an documentation on how to correctly inject headers in default `@KafkaHandler`.

Because of arguments resolution limitations in Spring Messaging, the `@Header` cannot be used on the default `@KafkaHandler`.
Instead the more general `@Headers Map<String, Object>` has to be used.
To satisfy default `@KafkaHandler` method expectations (usually `Object payload`), the `HandlerAdapter` injects a payload into `providedArgs`.
The type of that payload may clash with expected type of the `@Header` argument.
See `InvocableHandlerMethod.getMethodArgumentValues()` for details how params are resolved.

Signed-off-by: Sanghyeok An <[email protected]>
Co-authored-by: Artem Bilan <[email protected]>

Author: chickenchickenlove

spring-kafka-docs/src/main/antora/modules/ROOT/pages/kafka/receiving-messages/class-level-kafkalistener.adoc

@@ -62,3 +62,25 @@ void listen(Object in, @Header(KafkaHeaders.RECORD_METADATA) ConsumerRecordMetad
     ...
 }
 ----
+
+Also, this won't work as well.
+The `topic` is resolved to the `payload`.
+
+[source, java]
+----
+@KafkaHandler(isDefault = true)
+public void listenDefault(String payload, @Header(KafkaHeaders.RECEIVED_TOPIC) String topic) {
+    // payload.equals(topic) is True.
+    ...
+}
+----
+
+If there are use cases in which discrete custom headers are required in a default method, use this:
+[source, java]
+----
+@KafkaHandler(isDefault = true)
+void listenDefault(String payload, @Headers Map<String, Object> headers) {
+    Object myValue = headers.get("MyCustomHeader");
+    ...
+}
+----