JetBrains Find Usages 与 Structural Search 适用范围

在 JetBrains IDE 里，Find Usages 和 Structural Search 解决的是两类不同的查找任务：前者追踪某个已经被 IDE 解析出来的类、方法或字段引用，后者按代码的语法形状匹配一批表达式。要查“这个方法被谁调用”，先用 Find Usages；要查“所有带两个参数的日志调用”，才建立 Structural Search 模板。

官方地址：https://www.jetbrains.com/idea/

步骤一：先按问题类型选择搜索入口

如果光标落在一个已解析的 Java 或 Kotlin 符号上，Find Usages 能按引用类型、作用域和文件分组展示结果；它关心的是“谁引用了这个实体”。普通文本搜索或正则表达式无法理解这些语义。

Structural Search 关心的是“代码长什么样”。例如模板 logger.$method$($argument$) 可以把方法名和参数表达式作为变量，再通过变量约束缩小范围。它适合寻找一类调用、声明或嵌套结构，但不能替代符号解析，也不负责自动更新所有外部引用。

步骤二：用 Find Usages 定位符号引用

把光标放到目标类、方法或字段上，右键选择 Find Usages，或按 Alt+F7。需要调整范围时，在结果窗口点击设置入口打开 Find Usages 对话框，把 Scope 改成 Project、Open Files 或自定义范围；若要把字符串中的同名文本也纳入，再单独打开文本匹配选项。

成功后，Find 工具窗口会显示按文件、包或目录分组的结果。先看调用类型，再点开 Preview 或 Jump to Source。只有一个命中时可能直接跳转，这不代表搜索失败；回到 Recent Find Usages 仍能查看最近的查询。

步骤三：用 Structural Search 匹配代码形状

进入 Edit | Find | Search Structurally，在 Structural Search 对话框中选择 Draft Template，输入带占位符的代码片段。例如只想找日志调用，可以从 logger.$method$($argument$) 开始，再为 $method$ 增加文本或正则约束。模板里的变量不是普通通配符，它代表一个语法节点，约束越具体，结果越容易复查。

点击 Find 后，在 Find 工具窗口查看命中片段。这里的确认点不是“关键字出现了几次”，而是每个结果是否具有预期的调用结构。若结果混入测试目录或生成代码，先收窄 Scope，再调整变量约束，不要直接把模板改得过于复杂。

步骤四：用 Structural Replace 做受控替换

确认 Structural Search 的命中集合后，点击对话框中的切换替换入口进入 Structural Replace。左侧保留原模板，右侧只放需要保留的变量和目标结构。先把 Scope 限定到一个模块或目录，再逐项预览；结构化替换适合统一调用形态，不适合没有清晰边界的语义迁移。

替换完成后重新运行原 Structural Search，确认旧形状的结果数量下降；如果替换涉及方法名、参数或类型，再对关键符号执行 Find Usages，检查调用方、重写方法和测试代码。JetBrains 文档也提醒，Structural Replace 不会自动更新所有引用，因此“替换成功”与“重构完成”是两个验收点。

常见问题

Find Usages 能不能搜索未解析的文本？

它的核心是符号引用。纯文本、注释或未被 IDE 解析的内容，应改用文本搜索，并在需要时单独开启文本匹配。

Structural Search 能否直接替代重构工具？

不能。它适合按结构找出候选并做受控替换；涉及重命名、继承关系和外部引用时，仍应使用 IDE 的重构动作并用 Find Usages 复查。

为什么模板命中很多无关代码？

通常是 Scope 太宽或变量没有约束。先缩小目录，再限制变量的文本、类型或正则条件，最后重新预览。

实际工作中可以把两者串成一个安全顺序：先用 Find Usages 认识符号影响面，再用 Structural Search 找到同形代码，最后用 Structural Replace 做小范围变更并回查引用。这样既不会把文本命中误当成语义引用，也能避免批量替换后遗漏调用方。