IDEA Structural Search 使用详解

概述

IDEA Structural Search 是 IntelliJ IDEA 提供的一个强大的代码搜索功能，它基于代码的结构（AST抽象语法树）进行搜索，比传统的文本搜索更精确和灵活。特别适用于以下场景：

1. 需要查找同时满足多个条件的类或方法（如同时实现多个接口）
2. 需要基于代码结构而非简单文本进行搜索
3. 需要快速筛选大量候选类时

功能优势

1. 轻量级：相比 CodeQL、Tabby 等工具学习成本低，无需额外配置
2. 精确匹配：基于代码结构而非文本，避免误匹配
3. 实时反馈：编辑模板时即时显示匹配结果
4. 集成环境：直接在 IDE 中使用，无需切换工具

功能入口

在 IntelliJ IDEA 中：

1. 主菜单选择 Edit → Find → Search Structurally...
2. 或使用快捷键（Windows/Linux: Ctrl+Shift+S，Mac: Command+Shift+S）

核心概念

模板框架 (Template)

搜索的基本结构，使用 Java 代码片段表示要匹配的模式。例如：

class $Class$ implements $Interface1$, $Interface2$ {}

模板变量 (Template Variables)

用 $变量名$ 表示的可变部分，如 $Class$、$Interface1$ 等。

过滤器 (Filters)

对变量添加的约束条件，是 Structural Search 的核心功能。

过滤器类型详解

1. Text 过滤器

• 功能：基于文本内容匹配
• 用途：
  • 匹配特定类名（支持正则表达式）
  • 匹配特定字符串内容

示例：

$Interface1$:text = java\.util\.Comparator

2. Within type hierarchy

• 功能：包含继承层次中的匹配
• 用途：查找直接或间接实现接口/继承类的元素
• 建议：通常应开启以获得更全面的结果

3. Count 过滤器

• 功能：控制变量出现的次数
• 用途：限制方法参数数量、类实现接口数量等

4. Reference 过滤器

• 功能：基于引用的高级匹配
• 用途：如查找被特定注解标记的方法

示例：查找被注解的方法调用：

$MethodCall$();

然后为 $MethodCall$ 添加 Annotated methods 过滤条件

5. Invert modifier

• 功能：反转选择条件
• 用途：查找不符合某条件的元素

6. Script 过滤器

• 功能：使用 Groovy 脚本进行复杂条件判断
• 用途：实现无法通过简单条件表达的逻辑

示例：查找非接口、非枚举、非记录类的类：

!isInterface() && !isEnum() && !isRecord()

7. Type 过滤器

• 功能：指定变量类型
• 用途：精确匹配特定类型的元素

实用功能

1. 目标选择 (Target)

可指定搜索的目标类型：

• 类
• 方法
• 字段
• 语句等

2. 扫描范围 (Scan Scope)

可设置搜索范围：

• 整个项目 (In Project)
• 特定模块 (Module)
• 指定目录 (Directory)
• 自定义范围 (Scope)

3. 实时匹配

编辑模板时，IDE 会实时在当前文件中显示匹配结果，便于调试模板

4. 模板管理

• 保存模板：可将常用模板保存供后续使用
• 分类：
  • Draft Template：草稿
  • Recent：最近使用的模板
  • Saved Template：已保存的模板

实际案例

案例1：查找同时实现两个接口的类

需求：查找同时实现 java.util.Comparator 和 java.io.Serializable 的类

模板：

class $Class$ implements $Interface1$, $Interface2$ {}

过滤器设置：

• $Interface1$:
  • Text: java\.util\.Comparator
  • Within type hierarchy: 开启
• $Interface2$:
  • Text: java\.io\.Serializable
  • Within type hierarchy: 开启

案例2：查找被特定注解标记的方法调用

模板：

$MethodCall$();

过滤器设置：

• $MethodCall$:
  • Reference → Annotated methods

使用技巧

1. 依赖搜索：要搜索依赖中的代码，需确保已下载依赖的源码和文档
2. 变量命名：变量名无特殊要求，但建议使用有意义的名称
3. 组合过滤：可对同一变量应用多个过滤条件
4. 正则表达式：Text 过滤器支持正则表达式，提高匹配灵活性

适用场景

1. 接口实现的交叉查询
2. 需要从大量候选类中筛选特定条件的类
3. 查找具有固定模式的代码结构
4. 需要精确匹配代码语义而非简单文本

注意事项

1. 模板语法必须符合 Java 语法规则
2. 变量类型由其所在位置决定
3. 复杂的搜索可能需要组合多个过滤条件
4. 对于非常复杂的查询，可能需要使用 Script 过滤器

高级功能

Structural Search 还支持代码替换功能，可通过 Edit → Find → Replace Structurally... 访问，用法与搜索类似但增加了替换模板。

参考资源

• 官方文档: https://www.jetbrains.com/help/idea/structural-search-and-replace.html
• 官方示例模板: 在 Structural Search 对话框的 "Others" 菜单中查看