Quarkus扩展自定义前缀下从ConfigRoot迁移到ConfigMapping的问题

问题背景 #

我们基于Quarkus构建技术栈，原有多个扩展采用@ConfigRoot类实现配置，现正按照Quarkus扩展文档迁移至@ConfigMapping接口。所有配置使用自定义前缀（如mystack.），但迁移后发现无法为构建时和运行时配置共用该前缀，会触发配置验证异常：

ERROR [io.qua.dep.dev.IsolatedDevModeMain] (main) Failed to start quarkus: io.smallrye.config.ConfigValidationException: Configuration validation failed:
        mystack.configKey does not map to any root

该行为是预期的（对应Issue#32674），但观察到许多Quarkus扩展以quarkus.开头的前缀（如quarkus.mystack.）可共用构建与运行时配置前缀，因此咨询：

1. 能否让mystack.前缀的配置加载机制与quarkus.前缀表现一致？
2. 若不可行，拆分构建/运行时配置或改用quarkus.mystack.前缀是否是唯一方案？

另外注意到QuarkusConfigBuilderCustomizer中通过builder.withMappingIgnore("quarkus.**")忽略未映射的quarkus属性，是否有简便方法添加更多前缀到该忽略列表？

问题解答 #

1. 自定义前缀能否和quarkus.前缀表现一致？ #

不行。Quarkus对quarkus.前缀做了内置特殊处理：构建时和运行时配置系统会共享该前缀下的属性，且未映射的quarkus.属性会被自动忽略。而自定义前缀（如mystack.）没有这种预设逻辑，构建时和运行时的@ConfigMapping会被视为独立的配置根，共用前缀会导致未被当前阶段映射的属性触发验证异常。

2. 替代方案是否只有拆分配置或改用quarkus.前缀？ #

这两种是官方推荐的核心方案，同时还有一种变通手段（不推荐作为核心解决方案）：

• 拆分配置：将构建时和运行时配置分别使用不同子前缀，比如mystack.build.（构建时）和mystack.runtime.（运行时），各自对应独立的@ConfigMapping接口
• 改用quarkus.mystack.前缀：完全对齐官方扩展命名规范，自动享受Quarkus对quarkus.前缀的特殊处理，无需额外配置
• 自定义验证忽略规则：通过扩展配置忽略列表抑制异常，但无法解决构建/运行时属性归属的本质问题，仅能临时规避错误

如何添加自定义前缀到配置忽略列表？ #

可以实现自定义的QuarkusConfigBuilderCustomizer来扩展忽略规则：

import io.quarkus.runtime.configuration.QuarkusConfigBuilderCustomizer;
import io.smallrye.config.SmallRyeConfigBuilder;

public class CustomConfigIgnoreCustomizer implements QuarkusConfigBuilderCustomizer {
    @Override
    public void customize(SmallRyeConfigBuilder builder) {
        // 添加自定义前缀的忽略规则，格式与quarkus.**一致
        builder.withMappingIgnore("mystack.**");
    }
}

然后在扩展的META-INF/services/io.quarkus.runtime.configuration.QuarkusConfigBuilderCustomizer文件中注册该类：

com.yourpackage.CustomConfigIgnoreCustomizer

这样未被@ConfigMapping映射的mystack.前缀属性会跳过验证，不会触发异常，但仍建议优先选择拆分配置或改用官方前缀的方案。

内容的提问来源于stack exchange，提问作者shaped