如何在Maven MOJO中支持含特殊字符的Map键且兼容旧客户端？

要解决这个问题，我们可以通过新增列表式参数配置的方式，同时保留原有Map的配置逻辑，完全实现向后兼容。核心思路是让用户既能用原有的简洁配置处理普通键，又能通过新的列表配置处理含特殊字符的键，最终在插件内部自动合并两种配置。

步骤1：定义自定义条目类 #

首先创建一个简单的POJO类，用来承载单个键值对——这样就能绕开XML元素名不能包含特殊字符的限制：

public class CustomTypeMappingEntry {
    @Parameter(required = true)
    private String name; // 对应Map的键，支持任意特殊字符
    @Parameter(required = true)
    private String value; // 对应Map的值

    // 必须提供getter和setter，Maven参数绑定依赖这些方法
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getValue() {
        return value;
    }

    public void setValue(String value) {
        this.value = value;
    }
}

步骤2：改造MOJO类 #

在原有的MOJO中新增一个List<CustomTypeMappingEntry>类型的参数，然后在execute方法里把新条目合并到原有的customTypesMapping中：

@Mojo(name = "generate", defaultPhase = LifecyclePhase.GENERATE_SOURCES, threadSafe = true)
public class GraphQLCodegenMojo extends AbstractMojo {
    // 保留原有参数，保证旧配置完全兼容
    @Parameter
    private Map<String, String> customTypesMapping = new HashMap<>();

    // 新增参数，专门处理含特殊字符的键
    @Parameter
    private List<CustomTypeMappingEntry> customTypeEntries;

    @Override
    public void execute() throws MojoExecutionException {
        // 合并新配置到原有Map中
        if (customTypeEntries != null) {
            for (CustomTypeMappingEntry entry : customTypeEntries) {
                customTypesMapping.put(entry.getName(), entry.getValue());
            }
        }

        // 后续业务逻辑依然使用customTypesMapping，无需修改
        getLog().info("最终类型映射集合：" + customTypesMapping);
    }
}

步骤3：用户配置方式 #

原有配置完全兼容 #

老用户不需要做任何修改，原来的配置依然正常生效：

<customTypesMapping>
    <DateTime>java.util.Date</DateTime>
</customTypesMapping>

新配置支持特殊字符键 #

需要配置含特殊字符的键时，使用新增的customTypeEntries节点：

<customTypeEntries>
    <customTypeEntry>
        <name>DateTime!</name>
        <value>java.util.Date</value>
    </customTypeEntry>
    <customTypeEntry>
        <name>User-ID</name>
        <value>java.lang.String</value>
    </customTypeEntry>
</customTypesMapping>

两种配置可以混合使用 #

如果同时配置了两种方式，新条目会自动合并到原有Map中（若出现重复键，新条目会覆盖旧的）：

<customTypesMapping>
    <DateTime>java.util.Date</DateTime>
</customTypesMapping>
<customTypeEntries>
    <customTypeEntry>
        <name>DateTime!</name>
        <value>java.time.LocalDateTime</value>
    </customTypeEntry>
</customTypesMapping>

为什么原来的方式行不通？ #

Maven默认的Map参数绑定逻辑是把XML子元素的名称作为Map的键，但XML元素名称有严格的语法限制，不能包含!、@、#这类特殊字符——即使转义（比如!）也会被Maven解析成元素名的一部分，导致最终的键变成DateTime!而非DateTime!，所以这种方式根本无法实现需求。

而通过自定义条目类的方式，我们把键放到了元素的内容中，完全避开了XML元素名的限制，同时完美保留了原有配置的兼容性。

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