IntelliJ 插件开发实战：索引与 PSI 存根机制

IntelliJ 平台内置了几个标准文件索引，对插件开发者最有用的包括：

• 词索引：通过 PsiSearchHelper 类的辅助方法间接访问。
• 文件名索引：FilenameIndex 用于快速查找与特定文件名匹配的文件。
• 文件类型索引：FileTypeIndex 用于按文件类型快速筛选。

添加索引根目录

若要添加额外的文件或目录进行索引，可实现 IndexableSetContributor 扩展点 com.intellij.indexedRootsProvider。

存根索引详解

存根树是文件 PSI 树的精简子集，以紧凑的二进制格式存储。文件的 PSI 树可由 AST（解析构建）或从磁盘反序列化的存根树支持，两者切换是透明的。存根树通常只包含从外部文件解析此文件中声明所需的节点。若尝试访问不属于存根树的节点（如访问 PSI 元素的文本），系统会触发文件解析从 PSI 切换到 AST。

存根树中的每个存根本质上是一个无行为的 Bean 类，存储相应 PSI 元素状态的子集，如名称、修饰符标志（public、final 等）。它还包含指向父项的指针及子项存根的列表。

要为自定义语言支持存根，首先需决定哪些 PSI 元素应存储为存根。通常，其他文件可见的方法或字段需要存根，而外部不可见的语句或局部变量则无需。

概述

构建存根树时，可将部分数据放入多个索引中，以便通过相应的键查找 PSI 元素。与文件索引不同，存根索引不支持将自定义数据作为值存储，其值始终是 PSI 元素。键通常为字符串（如类名），但也支持其他数据类型。

存根索引继承自 AbstractStubIndex。当键类型为 String 时，建议使用更具体的基类 StringStubIndexExtension。存根索引需实现 com.intellij.stubIndex 扩展点。

要将数据放入索引，需实现 IStubElementType.indexStub() 方法（例如 JavaClassElementType.indexStub()）。该方法接受 IndexSink 参数，并为每个应存储的元素输入索引 ID 和键。

从索引访问数据时，可在管理的单例实例上使用以下方法：

• getAllKeys() / processAllKeys()：返回指定项目索引中所有键的列表（如项目中找到的所有类名）。
• get()：返回指定范围内与某个键对应的 PSI 元素集合。

public class JavaAnnotationIndex extends StringStubIndexExtension<PsiAnnotation> {
    private static final JavaAnnotationIndex ourInstance = new JavaAnnotationIndex();

    public static JavaAnnotationIndex getInstance() {
        return ourInstance;
    }

    @NotNull
    @Override
    public StubIndexKey<String, PsiAnnotation> getKey() {
        return JavaStubIndexKeys.ANNOTATIONS;
    }

    @Override
    public Collection<PsiAnnotation> get(@NotNull final String s,
                                         @NotNull final Project project,
                                         @NotNull final GlobalSearchScope scope) {
        return StubIndex.getElements(getKey(), s, project,
                new JavaSourceFilterScope(scope), PsiAnnotation.class);
    }
}

实现步骤

对于支持存根的每种语言，只需执行以下步骤一次：

1. 将语言的文件元素类型（ParserDefinition.getFileNodeType() 返回的类型）更改为扩展 IStubFileElementType 的类。
2. 在 plugin.xml 中定义扩展，指定包含语言解析器常量的 com.intellij.stubElementTypeHolder 接口。IElementType 定义了所有存根元素类型的 externalIdPrefix。

对于要存储在存根树中的每种元素类型，需执行以下操作：

• 定义一个派生自 StubElement 接口的存根接口。
• 提供该接口的实现。
• 确保 PSI 元素接口扩展了存根接口类型的参数化。
• 确保 PSI 元素实现类扩展了存根接口类型的参数化，并提供接受 ASTNode 和存根的构造函数。
• 创建一个实现存根接口和实际 PSI 元素接口的 IStubElementType 类。实现 createPsi() 和 createStub() 方法，以及用于二进制流序列化的 serialize() 和 deserialize() 方法。
• 解析时使用该类作为元素类型常量。
• 确保 PSI 元素接口中的所有方法在适当时访问存根数据而非 PSI 树。

默认情况下，若 PSI 元素扩展了 StubBasedPsiElement，则该类型的所有元素都将存储在存根树中。如需更精确控制，可覆盖 IStubElementType.shouldCreateStub() 并返回 false 以排除特定元素。注意排除不是递归的：若返回 false 的元素中包含其他基于存根的 PSI 元素，它们仍会被包含。

序列化数据

为了在存根中序列化字符串数据（如元素名称），建议使用 StubOutputStream.writeName() 和 StubInputStream.readName() 方法。这些方法确保每个唯一标识符仅在数据流中存储一次，从而减少序列化大小。

若需更改存根的存储二进制格式（例如存储额外数据或新元素），请务必提前更新 IStubFileElementType.getStubVersion() 返回的版本号，这将触发存根重建。

最后，必须确保存储在存根树中的所有信息仅取决于为其构建存根的文件内容，而不依赖任何外部文件。否则，当外部依赖项变化时，存根树不会重建，导致数据陈旧或不正确。