使用PF4J运行时注册端点引发RequestMappingHandlerMapping映射冲突

我之前也踩过这个坑！直接调用RequestMappingHandlerMapping.afterPropertiesSet()会触发Spring全量扫描所有控制器类，把已经注册过的核心Bean（比如你遇到的BasicErrorController）又重新注册一遍，自然就出现了路径映射歧义。下面是几个经过验证的解决思路：

1. 手动注册插件端点，避免全量扫描 #

放弃调用afterPropertiesSet()，转而针对性地注册插件中的控制器方法，只处理插件新增的端点：

• 插件加载完成后，先获取插件内的@RestController/@Controller实例
• 遍历这些类中带有@RequestMapping（包括@GetMapping/@PostMapping等派生注解）的方法
• 构建对应的RequestMappingInfo对象，调用RequestMappingHandlerMapping.registerMapping()手动注册

示例代码参考：

// 假设已获取到插件中的控制器实例
Object pluginController = pluginWrapper.getBean("pluginDemoController");
RequestMappingHandlerMapping coreHandlerMapping = applicationContext.getBean(RequestMappingHandlerMapping.class);

// 遍历插件控制器的方法
for (Method method : pluginController.getClass().getDeclaredMethods()) {
    // 处理@RequestMapping注解
    RequestMapping reqAnno = method.getAnnotation(RequestMapping.class);
    if (reqAnno != null) {
        RequestMappingInfo mappingInfo = RequestMappingInfo
                .paths(reqAnno.path())
                .methods(reqAnno.method())
                .produces(reqAnno.produces())
                .consumes(reqAnno.consumes())
                .build();
        coreHandlerMapping.registerMapping(mappingInfo, pluginController, method);
    }
    // 同理处理@GetMapping/@PostMapping等注解
    GetMapping getAnno = method.getAnnotation(GetMapping.class);
    if (getAnno != null) {
        RequestMappingInfo mappingInfo = RequestMappingInfo
                .paths(getAnno.path())
                .methods(RequestMethod.GET)
                .produces(getAnno.produces())
                .build();
        coreHandlerMapping.registerMapping(mappingInfo, pluginController, method);
    }
}

这种方式只会注册插件新增的端点，完全不会触动核心应用已有的映射，从根源上避免重复冲突。

2. 为插件配置独立的HandlerMapping #

创建一个专属的RequestMappingHandlerMapping来处理插件控制器，和核心应用的映射逻辑彻底隔离：

• 自定义RequestMappingHandlerMapping子类，通过类加载器判断是否为插件类
• 将这个自定义HandlerMapping注册到Spring容器，设置合适的order值确保优先级合理

示例配置：

@Bean
public RequestMappingHandlerMapping pluginHandlerMapping() {
    return new RequestMappingHandlerMapping() {
        @Override
        protected boolean isHandler(Class<?> beanType) {
            // 通过类加载器判断是否属于插件类
            return beanType.getClassLoader() instanceof PluginClassLoader && super.isHandler(beanType);
        }
    };
}

这样核心应用和插件的端点由不同的HandlerMapping处理，各自维护独立的映射表，再也不会出现重复注册的问题。

3. 应急方案：清理重复映射条目（不推荐） #

如果暂时没法重构注册逻辑，可以在调用afterPropertiesSet()后，手动清理重复的映射条目：

• 通过反射获取RequestMappingHandlerMapping中的私有属性handlerMethods
• 遍历所有映射，移除路径相同且HandlerMethod完全重复的条目

不过这种方式依赖Spring内部实现，版本升级可能会失效，建议优先使用前两种方案。

另外还要注意：PF4J加载插件时一定要保证类加载器隔离，避免插件类和核心类混淆，这是避免这类问题的基础。

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