升级Play Framework至2.8.19后Forwarding Body Parser随机失效

触发原因 #

这个错误的核心是单订阅类型的Publisher被重复订阅，结合Play版本升级的背景，核心诱因有两点：

1. Play 2.8.x 采用的AhcWSClient（基于AsyncHttpClient）在处理Reactive Streams请求体时，依赖Sink.asPublisher(fanout=false)创建的单订阅Publisher——这类Publisher严格遵循Reactive Streams规范，不允许二次订阅。
2. 你的自定义ForwardingBodyParser在新增的请求头处理逻辑中，可能无意中触发了请求体Source的订阅（比如提前读取Body流、或逻辑中对Accumulator的Source做了额外消费），而Play框架本身在后续处理流程中会再次订阅这个Source，最终导致冲突。
   另外，应用启动后高频出现的现象，大概率是启动阶段的预热请求、健康检查请求触发了重复订阅的逻辑路径。

解决方案 #

针对自定义BodyParser的场景，按优先级推荐以下修复方式：

1. 严格隔离请求头与请求体处理逻辑 #

确保ForwardingBodyParser中新增的请求头处理逻辑完全不触碰请求体流：

• 仅操作RequestHeader对象，不要调用任何会触发Body读取的方法（比如request.body()相关操作）。
• 所有Body相关的处理完全委托给原始目标BodyParser，避免手动订阅Accumulator对应的Source。

2. 复用请求体时先做缓存处理 #

如果业务逻辑需要同时处理请求头和复用请求体（比如转发Body到其他服务），必须先将Body缓存为可复用的格式：

// 示例：先收集Body为ByteString，再生成可多次订阅的Source
Accumulator<ByteString, Result> accumulator = Accumulator.byteString().map(byteString -> {
    // 处理请求头逻辑
    RequestHeader modifiedHeader = requestHeader.withHeaders(...);
    // 复用Body：将ByteString转为可多次订阅的Source
    Source<ByteString, NotUsed> reusableBody = Source.single(byteString);
    // 继续委托给目标BodyParser处理
    return delegate.apply(modifiedHeader).run(reusableBody, materializer);
}, executionContext);

这种方式通过先收集Body到内存（大文件场景用Accumulator.diskFile()缓存到磁盘），生成可多次订阅的Source，从根源避免重复订阅冲突。

3. 改用官方DelegatingBodyParser实现 #

Play 2.8.x 提供了DelegatingBodyParser抽象类，已经封装了安全的委托逻辑，避免手动实现Forwarding时的订阅问题：

public class CustomHeaderHandlingBodyParser extends DelegatingBodyParser<Result> {
    public CustomHeaderHandlingBodyParser(BodyParser<Result> delegate, ExecutionContext ec) {
        super(delegate, ec);
    }

    @Override
    protected RequestHeader modifyRequestHeader(RequestHeader requestHeader) {
        // 在这里处理请求头逻辑，完全不会触碰Body流
        return requestHeader.withHeaders(/* 自定义头修改逻辑 */);
    }
}

官方实现已经确保Body的Source只会被订阅一次，是最安全的替代方案。

4. 排查WSClient的请求体传递逻辑 #

如果错误发生在通过WSClient转发请求的场景，确保传递给WSRequest的Body是可复用的Source：

• 不要直接将原始请求的Body Source传递给WSRequest，而是先缓存为ByteString或文件后再生成新的Source。
• 避免使用Sink.asPublisher(fanout=false)生成的Publisher直接作为WSRequest的请求体，改用支持多订阅的Source转换方式。

内容的提问来源于stack exchange，提问作者archie_by