Java Matcher.replaceAll 怎样按捕获组动态生成替换文本

如果每次正则匹配都要根据捕获组生成不同的替换文本，Java 9 及以上可以直接使用 Matcher.replaceAll(Function)。替换函数会收到当前匹配的 MatchResult，你可以读取完整匹配、命名捕获组和位置，再返回本次替换字符串。

官方文档：https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/util/regex/Matcher.html#replaceAll(java.util.function.Function)

迁移时记住三个边界：函数返回的是每次匹配的替换文本；未参与匹配的捕获组可能是 null；返回文本里的美元符号和反斜杠仍可能按替换语法解释，需要字面量输出时先调用 Matcher.quoteReplacement。

固定字符串替换为什么不够用

传统的 replaceAll(String) 适合“所有命中项都替换成同一个文本”。例如把多个版本号统一改成 latest：

import java.util.regex.Pattern;

public class FixedReplacement {
    public static void main(String[] args) {
        String input = "api-1.2 api-2.0";
        // 固定替换只关心命中位置，不会读取每次匹配里的版本号。
        String result = Pattern.compile("api-(\\d+\\.\\d+)")
                .matcher(input)
                .replaceAll("api-latest");
        System.out.println(result);
    }
}

但如果需求变成“保留主版本号，只把次版本号改成 0”，固定字符串就不够了。手写 find、appendReplacement 和 appendTail 可以完成任务，却需要自己维护匹配游标和替换缓冲区。函数式重载把“当前匹配如何变成替换文本”单独交给一个函数，迁移面更小。

用 MatchResult 按捕获组生成替换文本

函数式重载的参数类型是 Function。下面把 user 和 domain 两个命名捕获组重新组合成脱敏后的邮箱：

import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class DynamicReplacement {
    private static final Pattern EMAIL = Pattern.compile(
            "(?[A-Za-z0-9._%+-]+)@(?[A-Za-z0-9.-]+)");

    public static String maskDomain(String input) {
        // 每个命中项都通过 MatchResult 读取自己的捕获组。
        Matcher matcher = EMAIL.matcher(input);
        return matcher.replaceAll(match -> {
            String user = match.group("user");
            String domain = match.group("domain");
            // 只保留域名首字符，返回值就是当前命中项的替换文本。
            String visibleDomain = domain.substring(0, 1);
            return user + "@" + visibleDomain + "***";
        });
    }
}

这里不需要手动调用 find()。replaceAll(Function) 会扫描所有命中项，并把每个匹配结果交给替换函数。返回值最终被拼回完整字符串，未命中的片段会原样保留。

如果只想替换第一个命中项，可以使用同样接受函数的 replaceFirst(Function)。两者都会重置并改变当前 Matcher 的匹配状态；后续如果还要用同一个对象继续匹配，应先明确调用 reset() 或重新创建 Matcher。

捕获组的 null 和空字符串要分开处理

命名捕获组没有参与当前匹配时，group("name") 返回 null；如果捕获组参与了匹配但匹配到的是空内容，返回的是空字符串。两者都不能直接拿来做无条件的 substring。

import java.util.regex.Pattern;

public class OptionalGroupReplacement {
    private static final Pattern ITEM = Pattern.compile(
            "(?[A-Z]+)?-(?\\d+)");

    public static String normalize(String input) {
        // 可选 prefix 没命中时是 null，先转换成业务默认值。
        return ITEM.matcher(input).replaceAll(match -> {
            String prefix = match.group("prefix");
            String id = match.group("id");
            String safePrefix = prefix == null ? "ITEM" : prefix;
            // id 已由正则限定为数字；返回文本仍只代表当前匹配。
            return safePrefix + "#" + id;
        });
    }
}

处理规则可以简单记成：null 表示该组没有参与这次匹配，"" 表示参与了匹配但内容长度为零，其他字符串才是普通捕获结果。业务默认值应该在替换函数内决定，不要在正则外部假设所有命中项拥有相同结构。

替换结果包含美元符号时先做字面量保护

函数返回的字符串仍然处在 Matcher 的替换语义中。返回值里的 $ 可能被解释为捕获组引用，反斜杠也可能触发转义。如果结果来自用户输入、配置文件或外部服务，且目标是原样输出，应先使用 Matcher.quoteReplacement。

import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class LiteralReplacement {
    public static String keepDollar(String input, String replacement) {
        // quoteReplacement 把 $ 和 \\ 当作普通字符，避免被替换语法再次解析。
        String literal = Matcher.quoteReplacement(replacement);
        return Pattern.compile("TOKEN").matcher(input).replaceAll(match -> literal);
    }
}

如果你确实需要在结果里使用捕获组引用，可以有意返回包含 $1 的模板；如果只想拼接当前匹配内容，则优先使用 match.group() 得到文本，再根据是否需要字面量保护决定是否调用 quoteReplacement。

迁移后的回归检查清单

从固定字符串或手写追加逻辑迁移时，可以按下面几项收尾：

1. 准备包含两个以上命中项的输入，确认替换函数会为每个命中项分别计算结果。
2. 准备没有任何命中的输入，确认原文保持不变。
3. 准备可选捕获组未命中的输入，确认 null 被转换成了业务默认值。
4. 准备包含 $ 和反斜杠的替换文本，确认字面量输出没有被当成组引用。
5. 不要在替换函数里调用当前 Matcher 的 reset、find 或其他会改变状态的方法；这会破坏替换过程，可能触发 ConcurrentModificationException。
6. 如果函数内部抛出异常，按调用方约定记录并向上交给错误处理层，不要默默返回空字符串掩盖问题。

常见问题

Matcher.replaceAll(Function) 从哪个版本开始可用？

Oracle Java SE API 将这个函数式重载标记为 Since 9，因此使用 JDK 9 或更高版本时可以直接调用；更老的运行环境需要保留 appendReplacement 方案。

替换函数能返回 null 吗？

不要把 null 当作合法替换文本。需要删除命中内容时返回空字符串；需要保留原匹配时返回 match.group()。

为什么函数里读取 group(name) 有时得到 null？

通常是可选捕获组没有参与这一次匹配。先判断 null，再做字符串拼接或截取；参与匹配但内容为空时得到的是空字符串。

总的迁移原则是：把扫描交给 Matcher，把每次命中项的业务变换写进 Function，并明确区分捕获组状态与替换文本转义。这样既能保留正则扫描能力，也能避免手工维护追加游标。