在 Quarkus 中使用 Multi 入参的 Kafka 消费方法无法自动传播 Kafka 消息头（如 HEADER1、HEADER2），仅 OpenTelemetry 相关头被保留；改用单条 Bytes 入参 + 返回 Multi 可完整支持配置的 header 透传。
在 quarkus 中使用 `multi
Quarkus 的 SmallRye Reactive Messaging 对 Kafka 消息头（headers）的自动传播机制，依赖于方法签名与消息元数据绑定的粒度。当你声明如下消费方法：
@Incoming("generic-in")
@Outgoing("generic-out")
public Multi<String> consume(@NotNull Multi<Bytes> messages) {
return messages.flatMap(message ->
Multi.createFrom().items(parseMessageIntoStrings(message))
);
}尽管逻辑上清晰（批量拉取、扁平化为多条输出），但该签名将整个 Multi<bytes></bytes> 视为一个“流式输入单元”，框架无法为每个原始 Kafka 记录关联其 headers 并逐条透传——因此 propagate-headers: "HEADER1,HEADER2" 配置对 Multi<bytes></bytes> 入参无效，仅 OpenTelemetry 上下文因全局钩子被保留。
✅ 正确做法：改用单消息入参 + 多消息出参签名：
基于夸克网盘自动转存项目 QAS 的懒人追剧、追番 SKILL，内置 CLI 工具。即使 QAS 订阅失效，仍可重新搜索资源、遍历多级目录，在多个最新候选中按用户偏好（如更高清晰度）转存新集和缺失集。可交由本地 OpenClaw、Hermes Agent 或其他 Claude 客户端使用。
@Incoming("generic-in")
@Outgoing("generic-out")
public Multi<String> consume(Bytes message) {
// 此时 message 来源于单条 Kafka Record，headers 已绑定到当前上下文
return Multi.createFrom().items(parseMessageIntoStrings(message));
}在此模式下：
- 框架为每条入站 Kafka 记录独立调用该方法；
-
Bytes实例隐式携带原始 record 的所有 headers（包括HEADER1,HEADER2）； -
propagate-headers配置生效，这些 headers 将自动附加到本方法产出的每一条String输出消息上（即generic-outtopic 中的每条 record）。
⚠️ 注意事项：
- 确保
parseMessageIntoStrings()不抛出未捕获异常，否则会导致流中断；建议包裹try-catch并记录错误或返回空Multi； - 若需在
flatMap中访问 headers（如做路由判断），可通过message.getHeaders()显式读取（Bytes提供该 API）； -
propagate-headers值为逗号分隔的 header key 列表，大小写敏感，且 key 必须存在于原始 record 中； - 不要混用
Multi<bytes></bytes>与@Blocking或复杂状态管理——单消息签名天然更易测试、可观测、符合 Kafka 分区语义。
总结：Kafka header 传播能力与方法参数类型强相关。追求 header 透传时，请优先选用 Bytes（或 byte[]、Record, ?>）单消息入参，而非 Multi<bytes></bytes>。这是 Quarkus Reactive Messaging 的设计约束，也是保障元数据端到端一致性的最佳实践。
