Java Matcher.results 怎样把匹配项转成 Stream

如果已经有一个 Matcher，又想把每次匹配交给 Stream 管道处理，可以直接调用 matcher.results()。它返回按匹配顺序产生的 Stream，适合把匹配内容映射成字符串、记录对象或统计结果；但这个流是惰性的，真正的匹配会在终结操作开始时发生，而且不会替你重置 Matcher。

官方地址：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/regex/Matcher.html

最小写法是 matcher.results().map(MatchResult::group).toList()。如果同一个 Matcher 之前已经调用过 find()，results() 会从当前匹配位置继续；想重新扫描整段输入，先调用 reset()。

把 find 循环改成 results 流

传统写法把“继续寻找下一项”的控制权放在 while 循环里；results() 则把这些匹配包装成一个顺序 Stream。下面的代码只提取完整匹配文本：

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

public class TokenExtract {
    public static void main(String[] args) {
        Pattern word = Pattern.compile("[A-Za-z]+");
        Matcher matcher = word.matcher("Go Java Rust");

        // 终结操作 toList() 开始消费匹配结果，结果顺序与输入中的出现顺序一致。
        List words = matcher.results()
                // MatchResult::group 读取每次匹配到的完整文本。
                .map(MatchResult::group)
                .toList();

        System.out.println(words);
    }
}

这里的关键不是把 find() 机械替换成另一个方法，而是明确数据形态：输入仍由 Matcher 管理，输出变成一个顺序流。需要数组或集合时，用 toList() 之类的终结操作把它收口；只想统计数量时，也可以直接调用 count()。

MatchResult 里怎样读取内容和位置

results() 产生的元素类型是 MatchResult，不必把它立即变成字符串。除了 group()，还可以读取完整匹配的起止位置，或者读取捕获组：

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

record Hit(String text, int start, int end, String kind) {}

class HitReader {
    static List read(String input) {
        Pattern pattern = Pattern.compile("(?TODO|FIXME):\\s*(?[^\\n]+)");
        Matcher matcher = pattern.matcher(input);

        // 每个 MatchResult 代表一个匹配位置，可在同一个 map 中组装业务对象。
        return matcher.results()
                .map(result -> new Hit(
                        result.group("text"),
                        result.start(),
                        result.end(),
                        result.group("kind")))
                .toList();
    }
}

需要注意 end() 返回的是结束位置的后一位，这与 Java 的字符串区间习惯一致。捕获组没有匹配到内容时，相关 group 可能返回 null，所以把结果转成业务对象时仍应保留必要的空值处理。

为什么 results() 有时像是少了第一项

results() 不会重置 Matcher，而且匹配从终结操作启动时的当前区域和当前位置开始。如果此前已经成功调用过一次 find()，那一次匹配已经被消费，后续的 results() 会继续寻找下一项。

Pattern pattern = Pattern.compile("[A-Z]+");
Matcher matcher = pattern.matcher("AA bb CC");

// 先消费第一项，后面的 results() 不会自动回到输入开头。
boolean found = matcher.find();

// 这里得到的是后续匹配，而不是再次得到 AA。
List remaining = matcher.results()
        // group() 只读取当前 MatchResult 的完整匹配。
        .map(MatchResult::group)
        .toList();

// 重新扫描时显式恢复 Matcher 的起始状态。
matcher.reset();
List all = matcher.results()
        .map(MatchResult::group)
        .toList();

这种行为适合“先判断一项，再处理剩余项”的场景；如果你的业务目标是每次都完整扫描，建议在进入 Stream 管道前把 reset() 写清楚。不要把“返回空列表”直接归因于正则表达式，先检查 Matcher 是否已经被使用过，以及是否真的执行了终结操作。

不要在 Stream 消费期间修改 Matcher

官方文档把返回值定义为顺序 Stream，并明确说明匹配器状态不应在返回流的管道执行期间被修改。也就是说，下面这类写法把读取和重置混在同一个消费过程里，边界很难判断：

Matcher matcher = Pattern.compile("[A-Z]+").matcher("AA BB");

// 不要在 results() 的管道中调用 reset、find 或 region 修改同一个 Matcher。
List values = matcher.results()
        .map(result -> {
            // 这里只读取当前结果，避免改变 Matcher 的匹配状态。
            return result.group();
        })
        .toList();

如果确实需要换输入、换区域或重新匹配，先让当前流完成终结，再在外层调用 reset(CharSequence)、region() 等方法，之后重新创建一个结果流。把一个 Matcher 交给一个明确的消费阶段，也更容易避免状态被多个方法交叉使用。

results 和 find 怎样选择

因此，results() 更像“把匹配结果交给后续数据处理”的接口，而不是万能的循环替代品。只要保留 Matcher 的单一消费边界，Stream 写法就能减少索引变量、临时集合和手写循环状态。

常见疑问

Matcher.results() 从哪个 Java 版本开始提供？

官方 API 标注该方法自 Java 9 提供。如果项目需要兼容更早的 Java 版本，应继续使用 find() 循环，或在兼容层封装两种实现。

results() 返回的是并行 Stream 吗？

不是。官方定义返回顺序 Stream；文章中的示例也按顺序消费，不把 Matcher 的状态匹配改造成并行任务。

为什么调用 results() 后 Matcher 不能马上继续 find()？

应先让流完成终结操作，再继续使用 Matcher；如果要从头开始扫描，先调用 reset()。流管道执行期间修改 Matcher 会让状态和结果边界变得不可预测。

小结

Matcher.results() 解决的是“把连续匹配结果接入 Stream 管道”这个具体问题：用 MatchResult 读取文本和位置，用终结操作决定何时真正消费，用 reset() 明确复用边界。需要提前停止、频繁改变外部状态或处理复杂分支时，保留 find() 循环反而更容易读懂。