Java HttpClient BodyHandlers.ofLines 怎样流式读取响应

Java HttpClient 的 BodyHandlers.ofLines() 会把响应正文交给一个按行产生字符串的 Stream。最小写法是把请求交给 client.send(request, BodyHandlers.ofLines())，拿到 HttpResponse> 后马上接过滤、映射或终端操作。它适合正文很大、业务只需要逐行处理的场景；如果要完整字符串或自定义字节读取，应选择其他 BodyHandler。

关键边界有三个：ofLines() 负责正文的按行转换，不会替你判断状态码；响应对象拿到后，正文流仍需要继续消费；如果提前停止，必须关闭这个 Stream，否则底层 HTTP 交换可能无法正常释放。

官方地址：https://docs.oracle.com/en/java/javase/21/docs/api/java.net.http/java/net/http/HttpResponse.BodyHandlers.html

下面按“最小可用写法—参数和结果—异常与资源—替代选择”的顺序展开，示例使用 Java 11 及以上的标准 java.net.http API。

先得到 HttpResponse>

BodyHandlers.ofLines() 的返回类型不是 String，而是 Stream。每个元素对应正文中的一行，因此可以在内存中只保留业务需要的内容，而不是先把完整响应拼成一个大字符串。

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.stream.Stream;

public class ReadLinesDemo {
    public static void main(String[] args) throws IOException, InterruptedException {
        // HttpClient 可以复用连接，避免每次请求都重新创建客户端。
        HttpClient client = HttpClient.newHttpClient();

        // 请求只负责声明目标地址；响应正文的处理交给 BodyHandler。
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://example.com/events.log"))
                .GET()
                .build();

        // ofLines 返回按行消费的流，响应类型因此是 Stream。
        HttpResponse> response =
                client.send(request, HttpResponse.BodyHandlers.ofLines());

        // BodyHandler 不检查状态码；业务仍要先决定哪些状态可以继续处理正文。
        if (response.statusCode() >= 200 && response.statusCode()  lines = response.body()) {
                lines.filter(line -> !line.isBlank())
                        .limit(20)
                        .forEach(System.out::println);
            }
        } else {
            // 不处理错误正文时也关闭返回的流，交还本次响应的资源。
            response.body().close();
            throw new IOException("HTTP状态异常：" + response.statusCode());
        }
    }
}

这里的 try 不是为了关闭 HttpClient，而是关闭 response.body() 这个 Stream。正常遍历到末尾时，资源也会完成释放；示例使用 try-with-resources 是为了让 limit 提前结束时仍然有确定的关闭动作。

BodyHandler 不等于状态码校验

预定义的 BodyHandlers 实现会按自己的方式接收正文，但不会替应用判断状态码。即使服务器返回 404 或 500，HttpResponse 仍然可能带有一个可读取的正文流。因此状态码判断应放在拿到响应对象之后，并明确错误正文是要记录、读取还是直接关闭。

BodyHandler 本身有能力在正文到达前查看响应状态和响应头，但 ofLines() 是固定行为的预定义处理器。如果业务要按状态码选择不同的订阅器，可以改用自定义 BodyHandler；单纯的“成功才处理”则在调用返回后判断更容易读。

import java.io.IOException;
import java.net.http.HttpResponse;
import java.util.stream.Stream;

public final class ResponseLines {
    private ResponseLines() {
        // 工具类不需要实例化。
    }

    public static long countNonEmpty(HttpResponse> response)
            throws IOException {
        if (response.statusCode() / 100 != 2) {
            // 非2xx响应不进入业务统计，先关闭尚未消费的正文流。
            response.body().close();
            throw new IOException("不接受的HTTP状态：" + response.statusCode());
        }

        // count 是终端操作；执行完成后流不能再次使用。
        try (Stream lines = response.body()) {
            return lines.filter(line -> !line.isBlank()).count();
        }
    }
}

不要在调用 count() 后再次调用 response.body().forEach(...)，因为同一个 Stream 只能消费一次。若要同时得到数量和部分内容，应在一次管道中完成收集，或让业务明确选择一个终端结果。

字符集和换行按响应正文契约处理

BodyHandlers.ofLines() 的类型签名没有字符集参数，它创建的是按响应信息处理的行流；底层按行订阅器的行定义与 BufferedReader.lines() 一致。服务端如果返回的字符集声明不符合实际编码，按行读取不会自动修复乱码，应该先修正服务端声明，或者在确实需要指定字符集时组合更底层的 BodySubscribers.ofLines(Charset)。

换行符也不应被业务代码当成普通字段内容。行流会按照读取器的行规则分割，返回的字符串不包含行结束符。若业务必须保留原始换行符或字节边界，ofLines() 就不是合适的结果形态。

提前结束时要关闭 Stream

按行读取并不意味着可以随时丢弃响应流。比如找到第一条匹配记录后调用 findFirst()，终端操作会提前结束；此时应使用 try-with-resources 关闭 Stream。如果愿意读完整个响应，也可以让流自然耗尽。

import java.net.http.HttpResponse;
import java.util.Optional;
import java.util.stream.Stream;

public class FirstMatchDemo {
    public static Optional findEvent(
            HttpResponse> response, String marker) {
        // try-with-resources 确保 findFirst 提前结束后关闭正文流。
        try (Stream lines = response.body()) {
            return lines.filter(line -> line.contains(marker))
                    .findFirst();
        }
    }
}

关闭流并不等于把响应正文“回滚”到开头。关闭之后不能再次读取同一条响应的 body()；如果后续逻辑需要多次遍历，应在一次消费过程中复制业务所需的数据，而不是保存这个流对象。

sendAsync 怎样继续按行处理

异步方式只改变等待响应的入口，不改变 Stream 的关闭规则。sendAsync 返回 CompletableFuture>>，可以在 thenApply 中取得响应，再由调用方在明确的消费范围内关闭行流。

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.concurrent.CompletableFuture;
import java.util.stream.Stream;

public class AsyncLinesDemo {
    public static CompletableFuture countAsync(
            HttpClient client, HttpRequest request) {
        // 异步请求完成时只代表响应可用，正文流仍要在后续阶段消费。
        return client.sendAsync(request, HttpResponse.BodyHandlers.ofLines())
                .thenApply(response -> {
                    if (response.statusCode() / 100 != 2) {
                        // 失败状态不进入统计，关闭未消费的正文流。
                        response.body().close();
                        throw new IllegalStateException(
                                "HTTP状态异常：" + response.statusCode());
                    }
                    try (Stream lines = response.body()) {
                        // 终端操作完成后，返回一个与正文流无关的数值结果。
                        return lines.filter(line -> !line.isBlank()).count();
                    }
                });
    }
}

异步链里不要把未关闭的 Stream 直接作为长期对象交给其他线程。更稳妥的边界是：在回调内完成消费并返回不可继续读取的结果，例如数量、摘要或少量业务记录。

几个容易混淆的问题

ofLines 会自动只处理 2xx 响应吗？

不会。预定义 BodyHandler 不替应用做状态码判断，必须由业务在响应返回后检查 statusCode()，或者自己构造按状态选择订阅器的 BodyHandler。

拿到 HttpResponse 就代表正文全部加载完成了吗？

不代表。按行 BodySubscriber 可以在响应头到达后提供响应对象，正文随后通过返回的 Stream 消费。消费速度和是否读到末尾仍由调用方决定。

只取第一行还需要关闭流吗？

需要。findFirst() 等提前结束的终端操作不会替代资源关闭；用 try-with-resources 包住 response.body() 即可。

想保留换行符该用 ofLines 吗？

不适合。ofLines() 返回的是不含行结束符的字符串元素；需要原始换行或字节级处理时，改用输入流或自定义订阅器。

总结：按行处理，按边界关闭

BodyHandlers.ofLines() 的价值是把 HTTP 响应正文转换成可消费的 Stream：状态码由业务判断，行内容由 Stream 管道处理，字符集和换行遵循正文契约。实际接入时记住四点：响应类型是 HttpResponse>；预定义 Handler 不负责成功判断；流只能消费一次；正常读完或提前停止都要让流得到关闭。这样才能把“流式读取”落实成清晰的输入、输出和资源责任。