Java HttpClient BodyHandler 怎么限制响应体大小

用 Java HttpClient 请求第三方接口时，BodyHandlers.ofString() 和 ofByteArray() 都会把正文交给内存中的结果对象；如果对方返回异常大的响应，调用方往往在解析 JSON 之前就承担了内存压力。JDK 25 直接用 BodyHandlers.limiting 包住原来的处理器即可，超出容量时会以 IOException 结束下游，并取消上游订阅。

运行 JDK 25 及以上时，把最大字节数作为 capacity 传给 BodyHandlers.limiting；运行 JDK 11 到 24 时，则在 Flow.Subscriber> 中累计字节并在超限时 cancel()。Content-Length 只能提前判断，不能替代读取过程中的硬上限。

JDK 25 先把 BodyHandler 包起来

新 API 的位置很明确：BodyHandler 负责在响应头可用时创建 BodySubscriber，limiting 是它的外层约束，内部仍然可以使用 ofString、ofByteArray 或 ofFile。例如只允许接收 1 MiB：

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.nio.charset.StandardCharsets;

long maxBytes = 1_048_576; // 限制响应体原始字节数
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(
        URI.create("https://api.example.test/data"))
    .GET()
    .build();

try {
    HttpResponse response = client.send(request,
        HttpResponse.BodyHandlers.limiting(
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8),
            maxBytes)); // 超限由 HttpClient 取消上游并报告 IOException
    System.out.println(response.body()); // 只有完整正文才到达这里
} catch (IOException ex) {
    System.err.println("响应体超过上限或读取失败：" + ex.getMessage());
} catch (InterruptedException ex) {
    Thread.currentThread().interrupt(); // 保留线程的中断状态
}

这里的容量是字节数，字符集解码发生在下游的 ofString。因此中文文本不能按“字符数量乘 2”估算；如果业务限制的是字符数，应在解码后另做业务校验，但内存保护仍应保留字节上限。

未知 Content-Length 也要在读取时限制

服务器可能使用分块传输，或者根本不发送可用的 Content-Length。这时不能只写下面这种头部判断：

long declared = responseInfo.headers()
    .firstValueAsLong("Content-Length")
    .orElse(-1L); // -1 表示没有可用的声明长度
if (declared > maxBytes) {
    // 这里只能提前拒绝已知过大的响应，不能覆盖未知长度
}

BodyHandlers.limiting 会在收到的正文超过容量时通知下游 IOException，同时取消上游订阅。取消是尽快停止后续数据的信号，但并不保证已经到达网络栈的最后一小段数据完全不会出现，所以不要把它理解成精确到一个 TCP 包的断路器。

如果要把超限和其他网络错误区分开，可以检查异常链中的消息或类型，并把“响应过大”映射为业务错误。不要在捕获异常后再次调用同一个请求而不改变上限，否则重试只会重复消耗带宽。

JDK 11 到 24 自己计数并取消上游

较早 JDK 没有公开的 BodyHandlers.limiting，可以用 BodySubscribers.fromSubscriber 接收 List。关键是按每个缓冲区的 remaining() 计数，而不是把一次 onNext 当成一个固定大小的数据包：

static HttpResponse.BodyHandler limitedBytes(long limit) {
    if (limit = 0");
    return info -> {
        LimitedSubscriber subscriber = new LimitedSubscriber(limit);
        return HttpResponse.BodySubscribers.fromSubscriber(
            subscriber, LimitedSubscriber::result);
    };
}

static final class LimitedSubscriber
        implements Flow.Subscriber> {
    private final long limit;
    private final ByteArrayOutputStream output = new ByteArrayOutputStream();
    private Flow.Subscription subscription;
    private long total;
    private boolean stopped;

    LimitedSubscriber(long limit) { this.limit = limit; }

    public void onSubscribe(Flow.Subscription s) {
        subscription = s;
        s.request(1); // 一次请求一个数据批次，保持背压
    }

    public void onNext(List buffers) {
        if (stopped) return;
        for (ByteBuffer source : buffers) {
            ByteBuffer copy = source.asReadOnlyBuffer();
            int size = copy.remaining();
            if ((long) size > limit - total) {
                stopped = true;
                subscription.cancel(); // 先停止继续接收正文
                onError(new IOException("response body exceeds limit"));
                return;
            }
            byte[] part = new byte[size];
            copy.get(part);
            output.writeBytes(part);
            total += size;
        }
        subscription.request(1); // 当前批次已处理，再申请下一批
    }

    public void onError(Throwable error) { stopped = true; }
    public void onComplete() { stopped = true; }
    byte[] result() { return output.toByteArray(); }
}

示例只展示兼容层的核心责任：读取、计数、背压、取消和失败完成。生产代码还应按项目需要保留原始异常、避免重复终止，并决定超限前已经收集的前缀是否允许落盘。图中的取消与 IOException 是同一个失败分支，不代表正常完成。

几个容易混淆的限制边界

文件下载也可以把 BodyHandlers.ofFile(path) 放到 limiting 内部，但容量只约束本次 HTTP 响应交给处理器的字节数。若业务需要“磁盘上最终文件不超过多少”或“解压后不超过多少”，应在文件处理、解压和临时文件清理处分别设限。

常见问题

BodyHandlers.ofString 本身会限制大小吗？

不会。它负责把完整响应转换为字符串；需要限制时，在外层使用 JDK 25 的 limiting，或在旧 JDK 使用自定义订阅器。

限制值能写成 0 吗？

可以表示不允许接收正文，但只要响应仍有字节，就会很快进入超限失败。是否允许空响应，应由接口契约决定。

sendAsync 超限时捕获 IOException 可以吗？

异步调用不会在调用现场直接抛出读取异常，通常要在 CompletableFuture 的异常完成中检查 CompletionException 及其 cause；同步 send 则按常规处理 IOException。