JetBrains Structural Search 批量定位 API 调用模式

当一个项目里出现几十处相似的 API 调用时，普通文本搜索通常只能回答“这段字符在哪里”，却不能稳定区分方法调用、参数数量和嵌套结构。JetBrains Structural Search 的解决方式是先写一个代码形状，再把可变化的部分交给变量过滤器，最后在项目、模块或目录范围内集中查看结果。

官方地址：https://www.jetbrains.com/help/idea/structural-search-and-replace.html

要批量定位 API 调用，先用 $变量$ 写出调用骨架，再用 Text、Count 或 Type 条件缩小命中范围；先 Find 和预览，确认结果后再考虑保存模板或做结构化替换。

先准备一个能复用的定位场景

假设项目中有多个服务类调用同一个客户端 API，但调用方法名、参数名和业务对象不同。我们希望找出“某个服务对象调用任意方法，并且只带一个参数”的代码形状，而不是把注释、字符串和普通文本一并搜出来。Structural Search 目前支持 Java、Kotlin、Scala 和 Groovy，本文用 Java 风格调用说明界面操作。

进入 IntelliJ IDEA 后，打开 Edit | Find | Search Structurally。软件教程中的界面名称可能随版本语言设置略有差异，但入口仍然围绕 Structural Search 对话框。

把 API 调用写成结构化模板

1. 在 Search Template 区域输入调用骨架：service.$Method$($Argument$)。
2. 把 $Method$ 和 $Argument$ 当作可筛选的结构变量，而不是普通正则表达式分组。
3. 在 Language 或 File type 中选择 Java，再把 Scope 设为当前 Project、Module、Directory 或自定义范围。
4. 先不要勾选过多选项，点击 Find，让第一轮结果帮助你判断模板是否写得过宽。

模板的重点是代码结构。比如 service.$Method$($Argument$) 只表达一个调用节点和一个参数位置；它不会因为注释里出现同样的字符就自动把注释当作方法调用。若目标 API 有固定接收者，也可以把 service 换成具体类型或对象表达式，再通过过滤器限制方法名。

用过滤器把宽结果收窄

第一次搜索命中太多并不代表工具失效，通常说明变量边界还没有写清。把光标放在变量上，使用过滤器区域逐个增加条件：

• Text：限制变量的文本形式。例如把 $Method$ 设为 find.*，可以集中查看以 find 开头的调用。
• Count：限制参数或语句数量。若只想找单参数调用，可把对应变量的最小值和最大值都设为 1。
• Type：限制参数类型。当同名 API 同时接受多个类型时，Type 比单纯看变量名更稳定。
• 正则条件：适合方法名有明确命名规律的场景，但它只应约束变量，不要把整段 Java 代码退化成脆弱的长正则。

例如，下面的调用形状表示“只观察一个字符串参数的打印类 API”，示例里的注释说明模板用途，实际模板仍应在对话框内按当前项目语言解析：

logger.$Method$($Message$)
// $Method$ 用 Text 条件限制为 debug|info|warn
// $Message$ 用 Type 条件限制为 String，避免混入对象参数

如果使用的是现有模板，先从模板列表选一个接近目标的原型，再改变量和过滤条件，通常比从空白模板开始更快。

处理递归、大小写和搜索范围

Structural Search 对话框里的几个开关决定“匹配到多深”。Recursive 开启后，方法调用模板可以继续观察嵌套调用；例如外层调用里再套一层同类型调用时，结果会更完整。若只关心最外层节点，则关闭 Recursive。

Match case 用来控制大小写敏感，Injected code 用来决定 HTML 中注入的 JavaScript 或 Java 中注入的 SQL 是否进入搜索。Scope 则控制搜索边界：项目级适合盘点全局调用，模块级适合局部迁移，目录级适合先做小范围试跑。

建议按“目录或模块 → 项目”的顺序扩大范围。这样可以先验证模板表达的结构，再把确认过的模板用于批量盘点，减少一开始面对大量误命中的干扰。

在结果窗口确认命中，再决定是否保存

点击 Find 后，结果会进入 Find tool window。先随机打开几处命中，确认高亮区域真的是目标 API 调用，而不是同名字段、字符串或嵌套节点。结果预览是操作流程中最关键的人工判断点：结构化搜索负责找候选，是否适合后续修改仍要由开发者决定。

确认结果后，可以把模板保存到 Recent 或 User Defined，之后从模板列表直接复用。若希望把它变成长期检查规则，可在结果窗口选择 Create Inspection from Template，再到代码检查范围中按名称运行。

定位和替换要分成两个动作

Structural Replace 可以为搜索模板配置替换模板，但不要因为“命中很多”就直接全量替换。先用 Find 查看候选，再逐个或按选中项替换，并优先使用预览。替换模板可以继续复用变量，例如：

java.util.logging.Logger.getLogger(this.getClass().getName()).fine($Message$)
// 只把已确认的消息变量带入日志调用，避免替换整个方法体
// 先预览结果，再选择逐项替换或批量替换

替换对话框还可能提供格式化、缩短全限定名和静态导入等选项。这些选项会改变生成代码的外观，应该结合项目现有风格逐项确认；Structural Search 本身不会替你判断业务语义是否等价。

常见问题和最终确认

为什么结果比普通搜索少？

因为结构化搜索依赖语言解析和节点形状。检查 Language、File type、Scope，以及模板是否写成了当前语言的合法调用结构；再决定是否开启 Recursive 或 Injected code。

为什么同名方法没有全部命中？

先检查 Text、Type、Count 过滤器是否过窄，再检查 Match case。不要先放宽所有条件，保留一个最能描述目标的约束，逐项调整更容易找到原因。

什么时候应该保存为 Inspection？

当这个调用模式会反复出现，或需要在后续提交中持续提醒时再保存。一次性的迁移盘点保留搜索模板即可，避免检查规则过多造成噪声。

最后可以用这张清单收尾：模板是否表达了调用结构；变量是否有 Text、Count 或 Type 边界；Scope 是否从小到大验证；结果窗口是否抽查了真实命中；结构化替换是否先预览并保留回退路径。满足这些条件，Structural Search 才真正从“搜索框”变成了可复用的 API 调用定位工具。