【IDEA插件开发】RefactoringEventListener与RefactoringElementListener的区别

IntelliJ IDEA中的重构监听器

在本文中，我们将介绍IntelliJ IDEA中的两种重构监听器：RefactoringEventListener和RefactoringElementListener，并比较它们的功能和用法。

什么是重构？

重构是一种改善源代码质量而不改变其功能的过程。重构可以帮助我们保持代码的整洁、简洁和易于维护。IntelliJ IDEA提供了许多内置的重构操作，例如重命名、移动、提取方法、提取常量等。

什么是重构监听器？

重构监听器是一种特殊的接口，它可以让我们在插件中捕获和处理重构事件。通过实现重构监听器，我们可以在重构发生前后执行一些自定义的逻辑，例如更新外部设置、检查冲突、显示提示等。

IntelliJ IDEA中有两种重构监听器：RefactoringEventListener和RefactoringElementListener。它们的区别在于：

• RefactoringEventListener是一个全局的监听器，它可以监听所有类型的重构事件（包括被重命名、被移动）。用于获取有关所选项目中已执行重构的高级通知。RefactoringEventData 取决于所执行的重构。它应该反映重构之前/之后的数据状态。它有两个方法：
  • refactoringStarted() 在重构开始时被调用。
  • refactoringDone() 在重构结束时被调用。
  • conflictsDetected() 检测到冲突时被激发。如果下一个事件来自相同的重构，则冲突将被忽略。
  • undoRefactoring() 当重构执行时创建的可撤消操作被撤消时触发。
  • redoRefactoring() 当重做重构执行时创建的可撤消操作时触发。
    注意：它还有一个ProjectLevel的TOPIC：Topic<RefactoringEventListener> REFACTORING_EVENT_TOPIC = new Topic<>("REFACTORING_EVENT_TOPIC", RefactoringEventListener.class, Topic.BroadcastDirection.NONE); 附加客户端侦听器的入口点。事件发布在项目总线及其子项上，因此应按以下方式完成连接project.getMessageBus().connect(Disposable).subscribe(RefactoringEventListener.REFACTORING_EVENT_TOPIC, new Listener())
• RefactoringElementListener是一个局部的监听器，它只能监听某个特定元素（例如类、方法、字段等）的重构事件。RefactoringElementListenerProvider收到一条通知，告知它在重构期间观察到的元素发生了什么。它有两个方法：
  • elementRenamed() 在元素被重命名时被调用。在写入操作和命令中调用。
  • elementMoved() 在元素被移动时被调用。在写入操作和命令中调用。

如何使用重构监听器？

要使用重构监听器，我们需要在插件中实现相应的接口，并通过扩展点注册到IntelliJ IDEA中 。

使用RefactoringEventListener

方式一：使用StartupActivity

要使用RefactoringEventListener，我们需要实现com.intellij.refactoring.listeners.RefactoringEventListener接口，并在插件的plugin.xml文件中添加如下扩展点：

<extensions defaultExtensionNs="com.intellij">
  <postStartupActivity implementation="com.example.listener.MyRefactoringEventListener$MyStartupActivity"/>
</extensions>

其中，MyRefactoringEventListenerProvider是一个实现了com.intellij.refactoring.listeners.RefactoringListenerProvider接口的类，它负责创建并返回我们自定义的RefactoringEventListener对象。例如：

public class MyRefactoringEventListener implements RefactoringEventListener {
    private final Project myProject;

    private MyRefactoringEventListener(@NotNull Project project) {
        myProject = project;
    }

    @Override
    public void refactoringStarted(@NotNull String refactoringId, @NotNull RefactoringEventData beforeData) {
        System.out.println("refactoringId = " + refactoringId);
        System.out.println("beforeData.getUserDataString() = " + beforeData.getUserDataString());
    }

    @Override
    public void refactoringDone(@NotNull String refactoringId, @NotNull RefactoringEventData afterData) {
        System.out.println("refactoringId = " + refactoringId);
        System.out.println("afterData.getUserDataString() = " + afterData.getUserDataString());
    }

    @Override
    public void conflictsDetected(@NotNull String refactoringId, @NotNull RefactoringEventData conflictsData) {
    }

    @Override
    public void undoRefactoring(@NotNull String refactoringId) {
    }

    /**
     * `StartupActivity`用于在项目打开后执行一些初始化操作。<br/>
     * 在IntelliJ IDEA启动时，会执行一系列的操作，包括加载插件、初始化项目、创建窗口等。这些操作都是由StartupActivity类来管理的。
     */
    public static class MyStartupActivity implements StartupActivity {

        /**
         * 在项目打开时运行活动
         *
         * @param project
         */
        @Override
        public void runActivity(@NotNull Project project) {
            MyRefactoringEventListener listener = new MyRefactoringEventListener(project);
            MessageBusConnection connection = project.getMessageBus().connect();
            connection.subscribe(RefactoringEventListener.REFACTORING_EVENT_TOPIC, listener);
        }
    }
}

方式二：使用projectListeners

从 idea 2019.3版本后支持在plugin.xml里注册监听器。

删除MyStartupActivity ，plugin.xml文件中改为添加：

<projectListeners>
   <listener class="com.pxl.mybatisognlupdater.listener.MyRefactoringEventListener"
              topic="com.intellij.refactoring.listeners.RefactoringEventListener"/>
</projectListeners>

使用RefactoringElementListener

要使用RefactoringElementListener，我们需要实现com.intellij.refactoring.listeners.RefactoringElementListener接口，并在插件的plugin.xml文件中添加如下扩展点：

<extensions defaultExtensionNs="com.intellij">
  <refactoringElementListenerProvider implementation="com.example.MyRefactoringElementListenerProvider"/>
</extensions>

其中，MyRefactoringElementListenerProvider是一个实现了com.intellij.refactoring.listeners.RefactoringElementListenerProvider接口的类，它负责为每个需要监听的元素创建并返回我们自定义的RefactoringElementListener对象。例如：

public class MyRefactoringElementListenerProvider implements RefactoringElementListenerProvider {
  @Override
  public RefactoringElementListener getListener(PsiElement element) {
    if (element instanceof PsiClass) {
      return new MyRefactoringElementListener((PsiClass) element);
    }
    return null;
  }
}

public class MyRefactoringElementListener implements RefactoringElementListener {
  private final PsiClass psiClass;

  public MyRefactoringElementListener(PsiClass psiClass) {
    this.psiClass = psiClass;
  }

  @Override
  public void elementRenamed(@NotNull PsiElement newElement) {
    // 在这里添加元素只被重命名时的逻辑
    System.out.println("Class renamed: " + psiClass.getName() + " -> " + ((PsiClass) newElement).getName());
  }

  @Override
  public void elementMoved(@NotNull PsiElement newElement) {
    // 在这里添加元素只被移动时的逻辑
    System.out.println("Class moved: " + psiClass.getQualifiedName() + " -> " + ((PsiClass) newElement).getQualifiedName());
  }
}

还可以参考com.intellij.refactoring.listeners.RefactoringElementAdapter创建RefactoringElementListener实例。

参考资料

: What is Refactoring?

Listening to Refactorings

com.intellij.refactoring.listeners (IntelliJ Platform Plugin API)

Plugin.xml (IntelliJ Platform Plugin API)