IntelliJ 平台 PolySymbols 迁移实战：把 PSI 驱动的集成迁移到 Symbol API（测试先行、逐类落地）

IntelliJ 平台 PolySymbols 迁移实战：把 PSI 驱动的集成迁移到 Symbol API（测试先行、逐类落地）

【免费下载链接】intellij-communityIntelliJ IDEA & IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community

导读

本文以 IntelliJ 社区版仓库中的 PolySymbols 迁移指南为主体，系统讲解如何把一个已经基于经典 PSI（PsiReference/PsiReferenceContributor）工作的语言集成渐进式迁移到 PolySymbols（构建于平台 Symbol API 之上的符号共享框架），而不是从零新建集成。整个迁移分两个阶段：Phase A 先迁移测试基础设施（让测试经由 Symbol API 解析、对未迁移的符号类型透明回退到经典 PSI），Phase B 再逐类型迁移生产代码（每种 PSI 元素类型一次性完整迁移）。读完本文，你将掌握：为什么"双轨运行"只是过渡态而非终点、哪些CodeInsightTestFixture方法被禁用及如何替换、PolySymbolOwnReferenceHost+polySymbolOwnReferencesDSL 的正确用法、移除PsiLinkedPolySymbol桥接前必须检查的风险，以及如何用真实案例（GDScript 迁移）印证每个决策点。

本文主体来自 .claude/skills/poly-symbols/references/migration.md，并以 .claude/skills/poly-symbols/SKILL.md、testing.md、query-model.md、case-studies.md 及 symbols-api/SKILL.md 做纵深补充。

前置知识：PolySymbols、Symbol API 与"增量而非权威"原则

迁移文档是 poly-symbols 技能族的一部分，默认读者已经读过主技能文档。理解迁移，需要先掌握三个背景事实：

1. Symbol API 是底层基础。com.intellij.model.Symbol（定义于community/platform/core-api/src/com/intellij/model/Symbol.java，从仓库技能文档描述可确认）是平台对"把PsiReference解析成一个PsiElement"这一模式的通用替代：一个Symbol代表某个模型中的语义元素（语言、框架、数据库 schema），导航、查找用法、重命名、文档都与 PSI 解耦。Symbol不要求有PsiElement支撑，也不应试图从一个Symbol反推 PSI。经典的 JDK 存根编译类、Spring Bean、数据库列都是无 PSI 支撑符号的典型例子。详见 symbols-api/SKILL.md。
2. PolySymbols 是构建在 Symbol 之上的框架。PolySymbol : Symbol，提供查询执行器（PolySymbolQueryExecutor）、完成提供器基类、默认的searchTarget/renameTarget/getDocumentationTarget/getNavigationTargets实现，让你用远少于手写 Symbol API 的代码拿到声明、引用、完成、搜索、重命名、导航全套能力。2022.3–2025.1 时代它叫 "Web Symbols"，目前仍标记为 experimental。
3. "增量（additive），而非自动权威"：本仓库研究的每一个真实 PolySymbols 集成（GDScript、JS/TS/HTML/CSS、Vue、Angular）都在一段时期内与遗留 PSI 代码双轨运行，没有一个完全只走 PolySymbols。这是设计事实，不是可以忽略的迁移残留物。PsiLinkedPolySymbol的文档注释原文就是 "serves as a bridge between Symbol-based functionality and the old PSI-based functionality"（连接基于 Symbol 的功能与旧 PSI 功能的桥）。

核心原则：双轨运行是过渡态，不是落脚点

迁移指南开门见山地给出全篇最重要的判断：

additive 是过渡态（transient state），不是落脚点（resting one）。

按主技能的 "additive, not authoritative" 规则，仓库里每个真实的 PolySymbols 集成都会与遗留 PSI 双轨运行一段时间——这在迁移过程中是预期内的。但这不是可以停下来的地方。

判断一个符号类型双轨运行太久的信号：重复的 Find Usages 结果。一次来自遗留PsiReferenceContributor支撑的搜索，一次来自 Symbol API 路径。如果你看到这种重复，正确的做法是完成该类型的迁移（Phase B），而不是去抑制那条重复结果。

这个信号在仓库里是真实发生过的：GDScript 模块自己的polySymbols/README.md曾明确记录 PSI 与 PolySymbols 两条路径同时运行、产生重复的 Find Usages 结果，直到遗留路径被删除。GDScript 通过 own-references 迁移彻底删除了遗留psi.referenceContributor后，重复问题随之消失（换来了一个更窄的问题——需要手写ReferencesSearch执行器恢复用法搜索对等性，见下文 Phase B 第 4 步）。

Phase A：先迁移测试（不要先碰生产解析代码）

在触碰任何生产引用解析代码之前，先做 Phase A。目标是让测试套件经由 Symbol API 解析（对尚未迁移的类型透明回退到经典 PSI——这正是 testing.md 里所谓"Symbol-API-first, classic-PSI-fallback"的承重设计点），这样后续逐类型的生产迁移（Phase B）就有了预先验证的回归基线，测试本身再也不用改动。

Phase A 共 5 步：

步骤 1：盘点（Inventory）

在测试树中用正则搜索被禁用的CodeInsightTestFixture方法（完整清单见下表）。排除那些已经完整迁移到PolySymbolsTestCase、或命名为*PolySymbol*的测试套件——它们已被跟踪为"已迁移"，不在本轮范围内。

步骤 2：先重写共享的 PSI 遍历测试基础设施

如果存在一个共享基类在直接遍历 PSI 树并调用经典PsiReference.resolve()（例如一个"dump 出每个引用及其解析状态"的测试基类），先把它的遍历逻辑切换到：

• element.psiSymbolReferences()—— 元素级等价物，对应经典的element.references（own/EP 注册的PsiSymbolReference优先，其余经典PsiReference经PsiSymbolService.asSymbolReference包装）。
• PsiSymbolReference.resolveReference()。

两者都来自 testing.md 中PolySymbolsTestUtil.kt扩展函数速查表。关键约束：保持 gold 文件输出形状完全不变。

这一处改动之所以威力巨大，是因为它让所有构建在该基类之上的测试，在生产代码后续把各个引用类型从PsiReferenceContributor→ EPpsiReferenceProvider→ own-references 逐步迁移时，都能原样继续通过——dumper 不关心是哪种机制应答的，只关心有没有东西应答。

步骤 3：按映射表逐个替换被禁用的调用点

见下文的"被禁用的方法及替换映射"。

步骤 4：顺序重跑每个迁移后的测试——绝不要并发

同时运行多个tests.cmd调用会破坏共享的 Bazel 增量构建依赖图/字符串表。实际见过的症状：

• java.io.IOException: Mapping for number N does not exist. Current string table size: M entries.
• java.lang.IllegalStateException: Unable to find dependency '//.../..._test_lib.jar'

如果撞上上述任何一个，几乎可以肯定是并发问题——按顺序重跑同样的命令即可，而不是去调试代码。

步骤 5：显式分诊任何行为偏差——绝不静默更新 gold 文件

Symbol API 在回退到经典 PSI之前会先咨询任何已注册的polySymbols.psiReferenceProviderEP 提供器。因此，一个以前只走经典机制的测试，可能新近通过一个 EP 提供器解析成功，而该提供器还没有强制执行经典机制当时强制的正确性规则。常见肇事者：

• 只在 completion 中应用、而未在引用解析中应用的 static-vs-instance 访问过滤；
• 通过构造函数调用的限定符链解析没有完整建模。

这是测试基础设施变更暴露出的真实、预先存在的生产缺口，不是迁移的 bug。必须逐案例显式决策，三选一：

1. 更新 gold 文件，并把缺口记录在某个持久化位置；
2. 用@Ignore跳过该测试/断言，注释指向缺口；
3. 如果缺口在范围内，立即修复。

绝不能让"测试基础设施迁移完成了"悄悄变成"我们改变了这些测试验证的内容"。

被禁用的CodeInsightTestFixture方法及替换映射

以下每个方法都通过经典 PSI/caret 查找直接解析目标，完全绕过 Symbol API——调用其中任何一个，测试练习的正是本次迁移要摆脱的 pre-Symbol-API 路径（即使生产代码已经把该类型迁移到 own-references 也一样）：

findSingleReferenceAtCaret、getReferenceAtCaretPosition、getReferenceAtCaretPositionWithAssertion、testRename、testRenameUsingHandler、testFindUsages、testFindUsagesUsingAction、findUsages(PsiElement)、getElementAtCaret/elementAtCaret、renameElementAtCaret、renameElementAtCaretUsingHandler。

替换映射表（来自 migration.md 原文）：

两个被认可的例外

这两者都是执行（execution）原语而非解析（resolution）机制，因此被豁免：

• renameElement(element, newName)：给定已知元素、执行机械重命名的裸调用，没问题。这正是renameSymbolAtCaret内部在通过 Symbol API 解析到正确目标后（或有意回退到经典解析时）调用的那个函数。上述规则针对的是目标如何被发现，不是这最后一步。
• findUsages(target: SearchTarget)：这是PolySymbolsTestUtil.kt的重载，与被禁用的findUsages(PsiElement)不同，是 Symbol-API 的官方替代品。

设计内核：Symbol-API-first，经典 PSI 回退

psiSymbolReferences()/symbolAtCaret()/usagesAtCaret()/usagesAtOffsetBySignature()都先尝试 own/EP 注册的 PolySymbol 解析，然后——无条件、无需任何标志——在没有别的应答时透明回退到把经典 PSI 命名元素/引用包装成Psi2Symbol。实际效果：同一个测试辅助调用，无论底层引用类型是已完整迁移到 PolySymbols、迁移中、还是 100% 经典 PSI，都能原样工作。这正是测试套件可以先于任何生产迁移迁移到这套 API 的原因。

renameSymbolAtCaret是这个模式最尖锐的实例（源码见 testing.md）：

fun CodeInsightTestFixture.renameSymbolAtCaret(newName: String) { val symbol = symbolAtCaret() ?.takeIf { PsiSymbolService.getInstance().extractElementFromSymbol(it) == null } if (symbol == null) { if (runCatching { getElementAtCaret() }.isSuccess) { renameElementAtCaret(newName) // 有意为之：回退到经典机制 return } else throw AssertionError("No Symbol at caret") } // ... 真正的 PolySymbol/RenameTarget/PsiLinkedPolySymbol 路径 ... }

一个仅被解析为Psi2Symbol包装（extractElementFromSymbol返回非空——没有真正的PolySymbol/RenameTarget/PsiLinkedPolySymbol参与）的符号被当作"没有真正的符号"，函数落到 fixture 自带的经典renameElementAtCaret。这是有意为之、被认可的对禁用方法的使用——它把"引用 vs 声明"的歧义消解委托给平台自身久经测试的TargetElementUtil机制。这个例外属于共享测试基础设施，不属于单个测试代码——测试应调用renameSymbolAtCaret/usagesAtCaret，绝不直接调用renameElementAtCaret/elementAtCaret。

Phase A 端到端实例：GDScript 迁移

从 GDScript 迁移提炼的真实过程：

• ResolveTestBase的 dumper 从element.references+ref.resolve()切换到psiSymbolReferences()+resolveReference()；
• ResolveNestedClassMethodsTest和RenameTest.renameElementAtCaret()中的直接遗留引用类构造按同样方式替换；
• 字典键测试（GdDictionaryLuaStyleKeyTest/GdDictionaryStringKeyTest）——一种完全没有任何 PolySymbols 覆盖计划的引用类型——零行为变化地干净迁移，证明了经典回退设计即使对永远不会有 PolySymbols 实现的类型也有效；
• 单独地，重写ResolveTestBase仅靠切换解析机制就在已部分迁移的类型（GdRefIdRef/GdSetGetMethodIdRef）上暴露了 4 个真正的新失败——静态访问过滤和构造函数限定符链解析的缺口，经典 dumper 从未练习过。这些被留作开放、显式跟踪的决策，而不是被粉饰——正是步骤 5 的纪律。（TSCN↔GDScript 跨语言重命名测试当时也在"尚无 PolySymbols 覆盖、仅经典回退"桶里，后来 TSCN 的TscnNamedElement获得了自己的 own-references 实现，这两个测试如今练习真正的 PolySymbols 解析/重命名，不再走回退。）

Phase B：逐类型的生产迁移单元

只有当 Phase A 的测试全部变绿、或其偏差已显式分诊后，才能开始 Phase B。一次只迁移一个 PSI 元素类型（或符号类型），且对每个类型，在同一处变更中全部完成以下事项：

1. 实现PolySymbolOwnReferenceHost并覆写getOwnReferences()

让宿主 PSI 类的 own 接口实现PolySymbolOwnReferenceHost，然后在 impl 类上覆写getOwnReferences()，用polySymbolOwnReferences { ... }DSL 构建结果。精确形状见 query-model.md 的 "References — own references" 一节：

interface MyRefElement : PolySymbolOwnReferenceHost // 原来是 `: PsiElement` abstract class MyRefElementImpl(node: ASTNode) : ASTWrapperPsiElement(node), MyRefElement { override fun getOwnReferences(): Collection<PsiSymbolReference> = polySymbolOwnReferences(this) { resolveFromNameMatchQuery(MY_KIND, text) // 或原始 reference(range, kind) { ... } 形式 } }

几个关键点：

• 该 DSL 的element参数要求宿主类型实现PolySymbolOwnReferenceHost（一个扩展PsiElement的标记接口，位于community/platform/polySymbols/src/com/intellij/polySymbols/references/PolySymbolOwnReferenceHost.kt，从技能文档描述可确认）——对普通PsiElement类型的宿主编译不过。
• 标记接口不是编译期形式主义：PolySymbolHighlightingAnnotator.annotate()用element is PsiExternalReferenceHost || element is PolySymbolOwnReferenceHost这一个is检查门控整个方法体（引用问题标注、own/external 引用解析、甚至经PolySymbolDeclarationProvider的声明高亮）。跳过标记接口意味着标注器永远不会到达你的覆写——静默地没有任何高亮和引用问题诊断。
• resolveFromNameMatchQuery是PolySymbolQueryExecutorFactory.create(element, true).nameMatchQuery(kind, name).run()的便捷包装，可带可选 filter；解析逻辑超过单个 name-match 查询时（多个候选 kind、特殊 token 等），用底层reference(range, kind, resolver)形式。
• 同一元素绝不要同时实现两种机制：按PsiSymbolReferenceServiceImpl.getReferences()，own references 一旦非空，就会取代external ones 用于解析/搜索/重命名——所以对一个同时覆写了getOwnReferences()的宿主注册PsiPolySymbolReferenceProvider是死代码，不是补充。
• 旧迭代的 API 是已删除的PolySymbolOwnReferencesHost.buildOwnReferences()（复数 "References"）；如果你在旧代码/笔记里看到这个名字，它已过时——当前的直接覆写形式才是标准，别跟拼写相近但当前的PolySymbolOwnReferenceHost（单数 "Reference"）混淆。
• GdRefElement（GDScript）和TscnNamedElement（TSCN）是把标记接口加到既有元素接口上的真实示例；GdRefIdRefImpl是 query-model 文档里底层reference(range, kind, resolver)形式的示范（先对new/self/super/数学常量 token 分支，再回退到 name-match 查询+filter）。

2. 删除匹配的遗留PsiReferenceContributor及其PsiReference类

own references 一旦非空就抢占 EP 注册的外部引用（见 query-model 的 own-references 一节），因此一旦某类型有了 own-references，它的 EP 注册就是死代码。

3. 删除对应的polySymbols.psiReferenceProviderEP 注册和提供器类

同上——own references 会抢占 EP 注册的外部引用（PsiSymbolReferenceServiceImpl.getReferences()的语义），所以 EP 注册不是补充，而是死代码。

4. 如果该类型的声明还依赖PsiLinkedPolySymbol作为通往遗留 PSI 引用机制的桥，切换到PolySymbolDeclaredInPsi+ 手写PolySymbolDeclarationProvider

桥的存在理由（把旧解析目标识别为用法的双向搜索）一旦没有东西需要它，就不复存在。但预期会失去"用法搜索找到原始 PSI 声明"的行为——PolySymbolDeclaredInPsi自己的文档注释明确说了这一点（"any usage or rename searches for thePsiElementreturned bysourceElementwill not result in the symbol being recognized as a usage or rename target"）。它不把符号链回PsiElement做反向查找（见 query-model.md 的 Declarations 一节）。如果这对你迁移的类型很重要，预算一个手写ReferencesSearch执行器来恢复它。

GDScript 的真实迁移恰好撞上这个点，写了GdOwnReferencesSearcher——一个通用的"词搜索→解析每个出现的 own-references→与目标匹配"执行器——来补齐缺口，其前身是更窄的GdConstructorReferencesSearcher（让对构造函数_init的 Find Usages 也浮现ClassName.new(...)调用点——这些调用点在文本上根本不包含_init）。这印证了 query-model 的结论：PolySymbolDeclaredInPsi的"无用法搜索桥"权衡是每个采用者无论如何都要付的真实成本，不是没人撞过的角落。

5. 更新该类型的 Phase-A 移植测试，全程通过 Symbol API 断言

丢弃该类型剩余的纯 PSI 回退断言。

时间纪律与验证循环

• 绝不让一个类型在"已迁移但仍双轨"状态下停留超过一个变更——这正是核心原则警告的"落脚式双轨运行"状态。
• 每做一次原子的逐类型变更，就跑对应的测试模块。不要把多个类型批进一个未提交的变更——如果回归了，你要能一眼看出是哪个类型导致的。

删除PsiLinkedPolySymbol前的风险检查

目前PsiLinkedPolySymbol让"裸 PSI 触发的 Find Usages / Rename"（直接在声明上发起、而非通过已解析的引用）免费工作——它把 linked element 直接当作搜索目标。PolySymbolDeclaredInPsi不会自动做这件事。因此移除桥之前，检查是否有任何旧 API 的ReferencesSearch.search(PsiElement)调用者（未使用代码检查、构造函数用法搜索器、自定义 Find Usages 处理器）依赖它；如果有，要么为该元素→符号的反向查找加一个PsiLinkedPolySymbolProvider（EPcom.intellij.polySymbols.psiLinkedSymbolProvider，getSymbols(element: PsiElement): List<PsiLinkedPolySymbol>），要么在同一变更落地前把那个调用者也迁移掉。

Angular2PsiLinkedPolySymbolProvider是后者的典型示例：它从裸TypeScriptField（如.ts文件里的@Input() foo）恢复出Angular2DirectiveProperty，让PsiLinkedPolySymbolReferenceSearcher能通过PolySymbolNamesProvider.getNames(...)展开每一个名字变体（@Input('alias')、kebab-case 属性形式、banana-in-a-box 绑定形式）分别搜索。没有它，从类字段发起的 Find Usages 会静默退化成按字面名的文本搜索，漏掉所有别名/转换名写法下的用法。

生产侧迁移的一个常见陷阱：PolySymbolsHighlightingCustomizer收到的是原始查询结果

Phase B 中，当 own-references 成为主路径后，高亮定制器收到的symbol是查询/引用机制产生的原始nameMatchQuery结果，不一定是真正底层的符号。PolySymbolHighlightingAnnotator.highlightSymbols()直接把nameSegment.symbols条目传下去。对于经过fromNameMatchQuery式过滤的 own-references，那是同一个PolySymbolMatchBase包装，它自己的.kind报告的是查询的复合 kind，不是真实符号的 kind——先symbol.unwrapMatchedSymbols().firstOrNull()再读.kind/.modifiers，否则定制器对几乎每个符号都会静默返回null/错误答案。GDScript 的GdPolySymbolHighlightingCustomizer在迁离遗留标注器时正好踩过：把旧的（因为运行在经典 PSI 解析成功之后所以是对的）when (symbol.kind)着色逻辑机械移植过来，一旦成为主路径就静默地把几乎一切都渲染成通用回退色。

另外两点易误读之处（来自 query-model）：

1. PolySymbolHighlightingAnnotator既从 own-references 也从 EP 提供的（PsiExternalReferenceHost）引用取高亮——own-references 不是唯一来源，只是两条同等受支持的路径之一；同时它也是标注器在运行前检查的唯一条件（不实现PolySymbolOwnReferenceHost/PsiExternalReferenceHost，元素被整体跳过，不只是高亮）。
2. 两条路径本身都不产生任何颜色。属性查找链是getSymbolTextAttributes(host, symbol, level)→symbol[TextAttributesKeyProperty]→getTextAttributesFor(kind)，三者都默认返回null。覆写getOwnReferences()只拿到机制，真正的颜色由PolySymbolHighlightingCustomizer（EPcom.intellij.polySymbols.highlightingCustomizer，多个定制器按 EP 注册序 first-non-null-wins 组合）提供。

迁移相关文档导航

• poly-symbols/SKILL.md—— 框架本身，以及本次迁移最终要消解的 "additive, not authoritative" 规则；还有一条硬性纪律：未经用户明确的一次性许可，绝不修改community/platform/polySymbols/**平台源码，遇到平台缺口默认"报告并询问"，正确的修复几乎总是自己插件里的东西（插件注册的 EP 实现，如自己的UsageSearcher/RenameUsageSearcher/CustomUsageSearcher），而不是改平台文件。
• testing.md—— Phase A 把测试套件迁过去的那套测试编写 API：PolySymbolsTestCase类层次、PolySymbolsTestUtil.kt速查表、按功能分类的菜谱（解析/导航/完成/用法/重命名/高亮/文档）。
• query-model.md—— "实际如何解析"的参考：查询执行器、scope、contributor/configurator、声明三路径（PolySymbolDeclaredInPsi/PsiLinkedPolySymbol/ 手写PolySymbolDeclarationProvider）、own references、完成、以及解析出的PolySymbol如何点亮搜索/重命名/导航/文档。
• case-studies.md—— 四个真实集成（GDScript、JS/TS/HTML/CSS、Vue、Angular）的逐项 PolySymbols-vs-legacy 裁决与文件:行号证据，设计新集成前必读。
• symbols-api/SKILL.md—— 两个阶段共同构建于其上的Symbol/PsiSymbolReference/PsiSymbolDeclaration平台层，包含符号生命周期契约（单次读动作内有效、equals/hashCode须反映语义同一性、跨读动作必须createPointer()）。

迁移清单速查

Phase A（先做，不碰生产代码） □ 搜索测试树中被禁用的 CodeInsightTestFixture 方法（排除已迁移套件） □ 若有共享 PSI 遍历基类：切换到 psiSymbolReferences() + resolveReference()，保持 gold 输出不变 □ 按映射表替换每个禁用调用点 □ 顺序（绝不并发）重跑 tests.cmd；撞上 string-table/依赖错误先怀疑并发 □ 显式分诊行为偏差：更新 gold+记录 / @Ignore+注释 / 立即修复，三选一 Phase B（逐个类型，一次一个变更） □ 宿主接口实现 PolySymbolOwnReferenceHost，impl 覆写 getOwnReferences() 用 polySymbolOwnReferences { ... } □ 删除遗留 PsiReferenceContributor + PsiReference 类 □ 删除对应 polySymbols.psiReferenceProvider EP 注册 + 提供器类 □ 若依赖 PsiLinkedPolySymbol 桥：换 PolySymbolDeclaredInPsi + 手写 DeclarationProvider； 预期失去"用法搜索找到裸 PSI 声明"，必要时预算手写 ReferencesSearch 执行器； 删除桥前检查 ReferencesSearch.search(PsiElement) 调用者 □ 更新该类型的测试：全程 Symbol API 断言 □ 每原子变更后跑对应测试模块，绝不批量

【免费下载链接】intellij-communityIntelliJ IDEA & IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community