如何在自定义Maven插件中扩展ClassRealm？——内部API受限情况下的可行方案咨询

问题描述 #

我正在编写自定义Maven Deploy插件，遇到了特定类加载失败的问题。有文章提出可通过扩展ClassRealm来扩大类加载范围，于是我编写了如下代码：

@Mojo( name = "deploy", defaultPhase = LifecyclePhase.DEPLOY, requiresDependencyCollection = ResolutionScope.RUNTIME, requiresDirectInvocation = true, requiresOnline = true )
public class DeployMojo extends AbstractMojo {
    @Parameter
    private String server;
    
    @Parameter(defaultValue = "${project}", readonly = true, required = true)
    private MavenProject project;
    
    @Component
    private PluginDescriptor descriptor;
    
    public void execute() throws MojoExecutionException, MojoFailureException {
        // Added runtime resources for the project and create the classloader
        final var realm = descriptor.getClassRealm();
        final ArrayList<String> classpathElements;
        try {
            classpathElements = new ArrayList<>(project.getRuntimeClasspathElements());
        } catch (DependencyResolutionRequiredException e) {
            throw new MojoExecutionException("Unable to resolve project dependencies", e);
        }
        classpathElements.add(project.getBuild().getOutputDirectory());
        final var urls = new URL[classpathElements.size()];
        for (int i = 0; i < classpathElements.size(); ++i) {
            try {
                urls[i] = new File(classpathElements.get(i)).toURI().toURL();
                realm.addURL(urls[i]);
            } catch (MalformedURLException e) {
                throw new MojoExecutionException(String.format("Unable to parse classpath: %s as URL", classpathElements.get(i)), e);
            }
        }
        //Some other operations
    }
}

但当我尝试通过descriptor.getClassRealm()获取ClassRealm时，出现了“Cannot access org.codehaus.plexus.classworlds.realm.ClassRealm”的错误。此外，官方文档中明确警告：这是一个仅因技术原因公开的内部工具方法，不属于公共API范畴，该方法可能会在未提前通知的情况下被修改或删除，插件禁止使用。我想咨询是否存在合法的ClassRealm扩展方式，或者此类操作本就不应进行？

回答 #

首先明确一点：直接操作ClassRealm不仅不推荐，而且应该严格避免。Maven官方把它标记为内部API是有原因的——它属于Maven核心的类加载实现细节，违反插件开发的隔离原则，版本兼容性极差，后续Maven版本升级很可能直接导致你的插件失效。

那针对你的类加载需求，有哪些合法且规范的替代方案呢？

1. 依赖配置优先：让Maven自动管理插件类路径 #

如果你的插件需要访问某些类，首先应该通过插件自身的pom.xml正确声明依赖：

• 若插件运行时需要的类属于Maven核心已提供的组件，使用<scope>provided</scope>，避免重复打包；
• 若插件需要项目运行时的依赖类，你已经在@Mojo注解中设置了requiresDependencyCollection = ResolutionScope.RUNTIME，这会让Maven自动收集项目的运行时依赖到插件的上下文，但注意：插件本身的类加载器和项目的类加载器是隔离的，不要试图让插件直接加载项目类，而是通过下面的方式处理。

2. 创建独立的URLClassLoader加载项目类 #

如果必须加载项目运行时的类，正确的做法是创建独立的类加载器，而不是修改插件的ClassRealm。这样既不会污染插件自身的类空间，也符合Maven的隔离规范：

@Component
private ArtifactResolver artifactResolver;
@Parameter(defaultValue = "${repositorySystemSession}", readonly = true)
private RepositorySystemSession session;

private Class<?> loadProjectClass(String targetClassName) throws MojoExecutionException {
    try {
        // 收集项目运行时依赖和输出目录的URL
        List<URL> classpathUrls = new ArrayList<>();
        
        // 添加项目编译输出目录
        classpathUrls.add(new File(project.getBuild().getOutputDirectory()).toURI().toURL());
        
        // 收集并解析项目运行时依赖的JAR
        List<Artifact> runtimeArtifacts = project.getRuntimeArtifacts();
        for (Artifact artifact : runtimeArtifacts) {
            artifactResolver.resolveArtifact(session, artifact);
            classpathUrls.add(artifact.getFile().toURI().toURL());
        }
        
        // 创建独立类加载器，父类加载器使用插件类加载器，保证插件自身类可访问
        URLClassLoader projectClassLoader = new URLClassLoader(
                classpathUrls.toArray(new URL[0]),
                getClass().getClassLoader()
        );
        
        return projectClassLoader.loadClass(targetClassName);
    } catch (Exception e) {
        throw new MojoExecutionException("Failed to load project class", e);
    }
}

3. 间接调用：让项目自身处理类加载 #

如果你的需求是执行项目中的自定义逻辑（比如自定义部署逻辑），更优雅的方式是让项目负责类加载，插件只做触发和参数传递：

• 让用户在项目中编写一个包含主方法的类，实现部署逻辑；
• 你的插件通过调用Maven的exec:java目标来执行这个主类，把server等参数传递过去。
  这种方式完全避开了插件类加载的问题，所有类加载都由项目自身的类路径处理，兼容性和可维护性更好。

为什么不能碰ClassRealm？ #

再强调下官方警告的合理性：

• 类隔离破坏：Maven插件的类加载器本应和项目类加载器隔离，修改ClassRealm会导致类冲突（比如插件和项目依赖不同版本的同一个类）；
• API不稳定：ClassRealm属于Plexus Classworlds的内部实现，Maven随时可能修改甚至移除相关方法，插件会直接失效；
• 调试难度升级：类加载问题本身就难排查，修改内部Realm会让问题更复杂。

总结：你的类加载需求完全可以通过上述合法方案解决，没必要冒着兼容性风险使用内部API。

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