IntelliJ Structural Search / Replace：用 PSI 约束结构改写
一个 Java 服务准备把 LOG.debug("order=" + orderId) 迁成参数化日志。普通正则很快命中字符串拼接，却也扫进注释、测试快照和另一套 AuditLog；有人在 IDEA 里用 Structural Replace 得到更干净的结果，于是直接 Replace All。编译通过后，评审发现嵌套拼接仍在参数求值阶段完成，改写没有获得预期的延迟格式化收益，受保护模块也被一起改动，而一处方法声明改名后调用方没有同步更新。
IntelliJ Structural Search / Replace，简称 SSR，按语言结构匹配代码片段。它把模板解析为 IDE 的 PSI 结构，再用变量、出现次数、文本、类型、引用和脚本等约束筛选候选。它比文本替换更懂语法，却不等于 Rename、Change Signature、Safe Delete 这类正式 refactoring：SSR 负责“哪些结构长成这样以及怎样重写片段”，正式重构负责“同一符号及其 usages 怎样保持一致”。
先确认内置能力和项目模型都可用
SSR 是 IntelliJ IDEA 内置能力，不需要另装独立 SSR 插件。以下界面名称以 IntelliJ IDEA 2026.1 版本帮助为基线：从 Edit → Find → Search Structurally 进入结构搜索，切换到 Replace 图标，或直接选择 Replace Structurally 进入替换界面。不同键位方案和发行线的快捷键可能不同，菜单入口更适合作为团队文档中的稳定入口。
IntelliJ IDEA 从 2025.3 版本起合并为统一产品，试用结束后仍可使用免费核心功能，Ultimate 功能需要有效订阅；企业不能再沿用“Community/Ultimate 两个安装包”的旧采购清单。SSR 和 IDE 内部使用的 PSI 没有单独的激活项，实际使用权跟随安装中的 IDE 功能集与产品协议；只有开发、分发插件或平台组件时，才需要继续核对 IntelliJ Platform SDK 与 redistributable 的条款。SSR 是否出现在当前安装、目标语言插件是否启用，仍要在实际 IDE 中核对。团队分发前同时确认 IntelliJ IDEA 安装与统一产品说明、注册与订阅说明 和 JetBrains User Agreement，不要把本机试用期内可见的功能直接写成全员许可结论。
第一次操作不要从全项目 Replace All 开始。先确认 Project SDK、Gradle/Maven 导入和语言级别正确，编辑器没有大面积红色 unresolved symbol，索引也不在更新。SSR 可以在部分索引状态下返回语法命中，但类型、Reference 等语义约束会依赖项目模型；项目不完整时，少命中不能证明代码不存在。
建立一个独立实验模块，放入下面样例并先运行项目原有测试：
package demo.logging;
final class CheckoutService {
private static final Logger LOG = LoggerFactory.getLogger(CheckoutService.class);
void checkout(String orderId) {
LOG.debug("order=" + orderId);
LOG.debug("order={}", orderId);
}
}把光标放进第一条调用再打开 SSR，IDEA 通常能从选中代码创建模板。模板中的 $Name$ 是变量，普通 Java 标识符和标点仍是结构的一部分。先用 Find 看结果树，逐条跳转到源码；只有 Language、Target、Recursive、Injected code、Match case 与搜索 scope 都符合预期，才进入替换。
PSI 模板匹配的是语法角色而非字节片段
PSI 是 IntelliJ 平台按语言构造的 Program Structure Interface；PsiFile 是文件结构树的根，同一文件在不同打开项目中可对应不同的 project-scoped PSI。Java 方法调用会被建模为 qualifier、method expression、argument list 等节点；空格、换行通常不改变这棵结构。因此下面两种格式可以由同一模板命中，而注释里的相同字符不会作为 Java 调用节点命中。PSI 的项目作用域和按需构造语义可对照 JetBrains 的 PSI Files：
LOG.debug("order=" + orderId);
LOG.debug(
"order=" + orderId
);搜索模板可以写成：
$Logger$.debug($Prefix$ + $Value$)$Logger$、$Prefix$、$Value$ 不是正则捕获组，而是 PSI 模板变量。模板只保证它们出现在相应语法位置；如果不加约束，audit.debug(message + context) 也可能命中。完整匹配本身也有一个隐含变量，可用来控制上下文、脚本或反向条件。
语言选择决定模板由哪种 PSI parser 解释。当前 IntelliJ IDEA 文档列出的 SSR 语言能力包括 Java、Kotlin、Scala 和 Groovy；具体 IDE 产品、插件与发行线可能改变可选语言，操作时以 Language 下拉框和 JetBrains 的 Structural search and replace 为准。不要把“编辑器能打开某文件”推断成“SSR 对该语言提供等价能力”。
变量约束把宽泛形状收紧成业务候选
在模板中把光标放到变量上，通过 filter 面板添加约束。Text 用正则限制节点文本；Count 控制变量出现次数；Type 约束表达式或声明类型；Reference 可按引用目标收紧；Script 允许用 Groovy 表达更复杂条件。不同语言和变量角色显示的选项会不同。
对日志样例，可以按以下意图设置：
Search template:
$Logger$.debug($Prefix$ + $Value$)
Logger.Text: LOG
Prefix.Text: "order="
Value.Text: orderId
Value.Count: min=1, max=1Text 约束面向变量绑定到的 PSI 文本，字符串字面量是否包含引号要以预览结果确认。这里把 Value.Text 故意收紧到实验变量 orderId，使多段拼接和方法调用稳定留在反向样本；生产迁移若要覆盖更多简单表达式，应逐类增加 fixture 和约束，不能直接删掉这一过滤器后沿用“只命中单值”的结论。LOG 这个名字仍不能证明它就是 SLF4J logger；若项目存在同名字段或静态代理，再增加 Type/Reference 条件，或先把搜索限制到已知 logger 声明的模块。脚本约束能访问 PSI 对象，表达力很高，也意味着它可能依赖 IDE API 细节；团队共享规则时优先使用声明式约束，把脚本留给无法用标准 filter 表达且有 fixture 的条件。
Recursive 会决定嵌套结构是否全部返回。例如搜索方法调用时，foo(foo(foo())) 在递归模式下可能返回多层调用，关闭后通常只返回外层目标。这个开关会直接改变替换次数；嵌套改写前要在小样本中确认从内到外还是从外到内更安全。
Injected code 会把 Java 字符串里的 SQL、HTML 中的 JavaScript 等注入语言纳入搜索。它可能跨越原本以为的文件边界，并使用另一种 PSI。迁移普通 Java 调用时通常关闭；确需改注入代码，应把宿主文件、注入语言和转义后的输出作为独立实验验证。
scope 是第一道变更防火墙
SSR 可以选择 Project、Module、Directory 或 Custom Scope。一个准确模板配上过宽 scope，仍会改到 generated、vendor、fixture、兼容层和不属于当前团队的模块。第一次 Find 使用最小目录；确认约束后扩大到单 module；最后才考虑 Custom Scope 或整个项目。
团队可在 Settings → Appearance & Behavior → Scopes 创建名为 checkout-production 的 Custom Scope：在项目树中递归 Include checkout-service/src/main/java，再递归 Exclude src/generated 与 src/testFixtures。Scope 编辑器会生成并校验以 file: 为核心、可组合 &&、||、! 的 pattern；先在树形视图检查绿色纳入项与黑色排除项，不要复制一个未经当前 module/content root 验证的字符串。完整语法和 UI 行为以 Scopes 为准。scope 不是权限系统：IDE 进程仍可能读取账号有权访问的其他源码，它只过滤当前搜索动作。受法律、租户或仓库 ACL 约束的代码，应在文件系统和仓库权限层隔离，不能依赖 SSR 下拉框防止访问。
每次执行记录 scope 名、模块、语言、模板和候选数。若模板从 XML 导入，scope 可能随模板一起带入，也可能在另一位开发者机器上无法解析同名 module；导入后必须重新展开 scope 并抽查候选路径，不能看到模板名相同就直接替换。
正向实验：先预览再逐项替换参数化日志
搜索模板沿用 $Logger$.debug($Prefix$ + $Value$)，正向 fixture 放三种格式，反向 fixture 放已经参数化的日志、嵌套拼接和另一 logger：
LOG.debug("order=" + orderId); // 应命中
LOG.debug(
"order=" + orderId
); // 应命中
LOG.debug("order={}", orderId); // 不应命中
LOG.debug("order=" + orderId + ", user=" + userId); // 暂不命中
AUDIT.debug("order=" + orderId); // 不应命中替换模板写成：
$Logger$.debug("order={}", $Value$)点击 Find 后，在 Find 工具窗口打开 Preview Replacement。预期只出现前两条，预览保持 receiver 和 value 表达式不变。误命中的结果先用 Exclude 移出本次动作；排除项在执行 Replace All 时不会被修改，但它只是这一次结果集的人工筛选，不会反向修复模板。先用 Replace Selected 替换一条，运行格式化与模块测试，再处理余下候选。Reformat 可让新代码遵循 IDE formatter，Shorten fully-qualified names 可能改 imports，Use static import 可能改变调用形态；不需要的选项保持关闭，减少与业务变更无关的 diff。Find 工具窗口的替换、预览与排除语义可对照 Find tool window。
这个变换只对单个值的字符串拼接成立。"order=" + orderId + ", user=" + userId 的 PSI 是嵌套二元表达式，若被宽泛 $Value$ 吞入，替换后可能仍先完成字符串拼接，失去参数化日志的延迟格式化收益。为双参数形状写另一条模板和 fixture，不要让一个变量代表任意复杂表达式后直接 Replace All。
替换完成后运行：
./gradlew :checkout-service:compileJava
./gradlew :checkout-service:test
git diff --check
git diff -- src/main/java再运行同一 Structural Search。旧形状应为零命中，新形状的文本或结构搜索数量应与已替换集合一致。零命中只对当前 scope、当前项目模型和当前模板成立；最后再用文本搜索检查旧日志前缀，发现注释、生成代码或动态字符串中的残留。
反向实验：故意拆掉约束观察误命中
第一轮移除 Logger.Text: LOG，保留宽泛模板。预期 AUDIT.debug 进入结果树，证明语法形状相同不代表业务身份相同。恢复 Text 约束后，如果项目中另有名为 LOG 的非 SLF4J 字段，再用 Type 或 Reference 约束分离；若类型约束结果异常，先修复项目导入和 unresolved symbol。
第二轮把 scope 从 checkout-production 改成 Whole project。预期测试 fixture、迁移兼容层或生成目录的候选数上升。不要通过继续叠加复杂脚本来掩盖 scope 错误；路径所有权和语法条件是两条独立过滤轴。
第三轮开启 Recursive，并加入：
LOG.debug("order=" + normalize(prefix + orderId));观察结果是否包含内层表达式或额外调用，再比较关闭 Recursive 的结果。预览必须确认 $Value$ 绑定到整个 normalize(...)，替换没有重复包裹或拆散表达式。不同模板的递归行为需要以实际结果树为证据。
第四轮故意把方法声明 void checkout(String orderId) 用 SSR 替换成 void placeOrder(String orderId)。声明可能成功改名，但调用方不会因为这是“结构替换”就自动按符号同步。编译错误或 Find Usages 中的旧调用就是反例证据。撤销这次实验，改用 Rename refactoring，预览 usages 后再应用。
SSR 与正式 refactor 的分界看 usages 一致性
只要动作要求维护符号身份或调用契约，就优先使用正式 refactoring。Rename 应同步代码引用并可选择文本出现；Change Signature 要处理调用参数、重载、继承和实现；Move 要更新包、imports 和资源路径；Safe Delete 要判断 usages；Extract Method/Variable 还要分析控制流与数据流。SSR 不应手工模拟这些语义操作。
SSR 更适合没有现成 refactoring 的局部结构迁移，例如把一个弃用调用形状改成新调用、识别缺少保护条件的代码片段、统一注解参数或把已确认的样板展开。即便如此，框架通过反射、配置、序列化名、模板和依赖注入连接的关系也可能不在 PSI usages 中，仍要补文本搜索和运行测试。
JetBrains 文档也明确提醒：用结构替换把 class 改成 interface 不会自动更新 usages；此类任务应优先使用能同步 usages 的 inspection 或重构动作。判断口诀不是“SSR 是否能写出目标文本”，而是“修改后有哪些其他节点必须随同保持一致”。只要答案超出当前匹配片段，就要寻找正式重构、inspection quick-fix 或专用 codemod。
把模板升级为 inspection 和 quick-fix 要更谨慎
Find 结果可以将模板创建为 Structural Search Inspection，也可以把替换模板作为 quick-fix。这样规则能进入 IDE inspection 和团队配置，适合长期禁止旧 API。但一次性迁移模板不应默认变成长期开启的检查：错误约束会持续制造告警，quick-fix 还会把误改入口交给更多开发者。
共享前先导出模板 XML，纳入代码评审并在样例模块导入验证。XML 会携带模板、变量约束以及可能的 scope 信息；它是可执行的团队规则配置，尤其脚本约束应按代码对待。一个最小治理记录应包含稳定字段：
id: logging-parameterized-order
owner: platform-observability
language: JAVA
expectedPositiveFixtures: 2
expectedNegativeFixtures: 3
allowedScope: checkout-production
quickFixEnabled: false
rollback: revert-dedicated-change先让 inspection 仅告警，统计真实命中和误报；完成 fixture 与样本模块验证后，再决定是否提供 quick-fix。CI 是否能执行同等检查取决于团队的 IntelliJ/Qodana 工具链与许可配置，不能因为本地 inspection 变绿就声称构建门禁已经存在。
回滚要区分 IDE 缓冲区、工作树和已合并变更
单次替换后可立即使用 Edit → Undo，但连续替换、格式化和其他编辑会让撤销栈难以审计。IntelliJ IDEA 会在编译、运行、切换应用或空闲等事件中自动保存，不能把“我没按 Ctrl+S”当作尚未落盘；大批替换前可在 File → Local History → Put Label 留恢复点，但 Local History 有本机保留期限，不能替代 Git。更稳的做法是在干净的专用分支或隔离工作树操作，每完成一个模板批次就检查 Local Changes 与 Git diff。已有用户未提交改动时，不执行大范围 Replace All，也不通过回滚整文件覆盖他人工作。
刚执行且没有夹杂其他编辑时优先 Undo；撤销栈不再清晰时，从 Local History 标签或 Git diff 逐块恢复。已落入工作树但未提交的改动按本批 hunk、文件或 changelist 恢复，不能用整文件 Rollback 吞掉并行修改；已提交未合并的改动回退专用 commit；已经合并则使用正常 revert，并重新运行编译、测试和部署验证。SSR 修改若伴随配置、生成代码、数据库字段或对外协议，源码回退必须与相应兼容动作协调。JetBrains 的 Save and revert changes 与 Local History 分别说明了自动保存、Undo 和本地历史的边界。
模板本身也有生命周期。错误 inspection 要先禁用 quick-fix，再撤回共享配置；导入到个人 IDE 的副本可能不会自动消失，需要通知 owner 删除或升级。回滚演练应证明旧模板不再产生替换入口、新模板仍能识别残留旧形状，且已回退代码重新通过项目门禁。
权限、容量与团队治理决定能否扩大使用
IDEA 以当前用户身份读取项目、索引依赖和缓存。SSR 不需要生产数据库、云账号或部署 token；项目导入若依赖私有制品，只授予只读包权限，并避免把凭据写进模板、脚本约束、导出 XML 或截图。脚本约束执行 Groovy 代码，来源不可信的模板应先检查 XML 和脚本，再在无生产网络的样例项目导入。
大项目的成本主要来自索引、PSI 遍历、类型/引用约束和结果展示。Whole project、Recursive、Injected code 与复杂 Script 同时开启时，搜索可能占用大量 CPU 和内存。先用 module scope 测量候选数与响应时间，再逐步扩大；结果过多时先收紧路径和声明式约束，而不是让 Find 工具窗口承载几十万条候选。
团队对每条共享模板指定 owner、语言与 IDE 兼容基线、样例模块、正反 fixture、允许 scope、最大候选批次、替换选项、验证命令和退出策略。升级 IDE 或语言插件后，重新跑变量约束、嵌套递归、导入 XML、替换预览和正式 refactoring 反例。项目索引异常、候选数突然归零或暴增时暂停替换，先恢复项目模型并比较历史基线。
成熟的 SSR 使用记录不会只写“替换成功 318 处”。它会留下模板和约束、实际 scope、候选与拒绝样本、预览 diff、编译测试、再次搜索结果和回退 commit。这样下一位维护者才能判断这 318 处是受 PSI 与项目模型约束的可解释变更，而不是一次更高级的全局替换。