一次流式请求进来,网关把请求体转给上游,读到一半上游断了。网关准备重试,但请求体是流式的,已经被消费完,没法原样重发。如果请求体是一组可分割的事件帧,可以只保留最后一帧,在重试时带上它作为续传位置。
这段话对应的是实际故障现场:网关收到客户端的上传流,已经向上游转发了一部分,连接中断。重试时发现请求体已经不可用,因为流是一次性的。要处理这种情况,先不要急着改配置,应该先确认请求体是在哪一步丢失的。如果客户端是用 chunked 编码发送的,网关可能默认不会缓冲内容;如果客户端是 POST 一个文件流,那么即使日志显示请求进来了,网关也没有办法临时生成第二份请求体。
先搞清楚请求体是在哪一层丢失的
在写缓存逻辑之前,先检查网关和上游的访问日志。重点看两个时间:客户端请求到达网关的时间,和网关发起重试的时间。如果重试请求没有带 Content-Length 或 Transfer-Encoding: chunked,说明请求体已经被当作流消费掉了。这时候再检查上游是否支持续传标记,比如自定义头 X-Resume-Token 或查询参数中的 offset。否则,即使缓存了最后一帧,上游也不知道怎么用。
也可以先用 curl 模拟一个分段上传,观察网关是否在重试时丢体。执行命令时注意观察 TCP 连接断开时的提示,通常可以用 curl -v 看到 "Recv failure" 或 "Empty reply"。
curl -v -X POST http://gateway/api/stream \
-H "Transfer-Encoding: chunked" \
-d '{"frame":1}
{"frame":2}
{"frame":3}'如果重试发生在第二帧之后,第 2 和第 3 帧可能已经发给了上游,但第 1 帧可能在网关内存里被释放了。这时候需要确认网关是否配置了请求体缓存过滤器,比如 Spring Cloud Gateway 默认只缓存在 Predicate 阶段读取的请求体,不会为路由转发阶段保留原始流。
ReactiveAdapter 的核心作用不是缓存整个请求体,而是把响应式流里最近一次携带的数据快照出来。这个快照既可以用于诊断,也可以作为重试时的偏移量。使用时要先确认上游协议是否允许这种续传方式,否则等于白做。
这里的“数据快照”指的是 DataBuffer 的字节内容。需要注意的是,WebFlux 中的 DataBuffer 是从池里分配的,原 buffer 在订阅结束时会被释放。所以不能只保存 DataBuffer 引用,必须用 read(bytes) 把内容复制出来,或者调用 DataBufferUtils.retain 后再引用。下面就是一个基于 Spring Cloud Gateway 的过滤器示例,它读取请求体时复制每一帧的数据,并把最后一帧的字节数组放在 exchange 属性里。
用ReactiveAdapter缓存最后一帧:过滤器示例
import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.core.io.buffer.DataBufferUtils;
import org.springframework.http.server.reactive.ServerHttpRequest;
import org.springframework.http.server.reactive.ServerHttpRequestDecorator;
import org.springframework.cloud.gateway.filter.GatewayFilterChain;
import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.core.Ordered;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
import java.util.Base64;
import java.util.concurrent.atomic.AtomicReference;
public class LastFrameCachingFilter implements GlobalFilter, Ordered {
@Override
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
ServerHttpRequest request = exchange.getRequest();
AtomicReference<byte[]> lastFrameRef = new AtomicReference<>();
Flux<DataBuffer> bodyWithTap = request.getBody()
.map(dataBuffer -> {
byte[] bytes = new byte[dataBuffer.readableByteCount()];
dataBuffer.read(bytes);
DataBufferUtils.release(dataBuffer);
// 记录当前帧的副本,注意是每次覆盖,最终保留最后一帧
lastFrameRef.set(bytes);
// 用字节数组包装一个新的 DataBuffer,保持请求体完整
return exchange.getResponse().bufferFactory().wrap(bytes);
});
ServerHttpRequest newRequest = new ServerHttpRequestDecorator(request) {
@Override
public Flux<DataBuffer> getBody() {
return bodyWithTap;
}
};
exchange.getAttributes().put("lastFrameRef", lastFrameRef);
return chain.filter(exchange.mutate().request(newRequest).build());
}
@Override
public int getOrder() {
return -100; // 放在读取请求体的过滤器之后,路由转发之前
}
}这段代码的关键点有两个:一是用 map 对每个 DataBuffer 做一次复制,这样下游读取到的还是新的 buffer,不会影响原请求体的流转;二是每次复制后都把字节数组放到一个 AtomicReference 里,请求结束后这个引用就指向最后一个数据块。真正执行时,需要把过滤器注册到网关的过滤器链中,然后观察网关日志里有没有“lastFrameRef 为 null”的情况。如果为空,说明请求体本来就没有内容,或者过滤器顺序不对,没有在请求体读取之前执行。
注意,这个过滤器在每次请求时都会复制每个数据块,如果数据块很大,会额外占用内存。建议在过滤器里加一个长度判断,比如超过 2MB 就回退到“不缓存”模式。但这个数值要结合网关实例的内存上限和上游协议来定,不能拍脑袋。
缓存最后一帧是有代价的。DataBuffer 的生命周期和池复用会让直接引用失效,必须显式 copy 或 retain。同时,频繁的重试会让内存里堆积多个帧快照,必须设定上限和过期时间。
上面的代码已经用 byte[] 做了 copy,所以生命周期问题解决了。但“堆积多个帧快照”的问题依然存在,因为每次失败重试都有可能触发新的过滤器实例,而 exchange 属性里的引用只有在内置的缓存过期机制中才会被清理。如果不想在每个请求里都留一个引用,可以改用带 TTL 的本地缓存,例如 Caffeine,把最后帧按请求 ID 存放,这样在重试时可以根据同一个请求 ID 提取。
重试时把缓存帧变成续传标记
有了最后一帧的字节数组,下一步是在重试请求时把它通过 Header 或 Body 的一部分传给上游。一般来说,优先使用自定义 Header,因为这样不需要重新组装请求体,也容易被网关日志记录。下面是一个用 WebClient 发起重试的示例:
AtomicReference<byte[]> lastFrameRef = exchange.getAttribute("lastFrameRef");
if (lastFrameRef != null && lastFrameRef.get() != null) {
String resumeToken = Base64.getEncoder().encodeToString(lastFrameRef.get());
WebClient client = WebClient.builder()
.defaultHeader("X-Resume-Token", resumeToken)
.build();
return client.post()
.uri("http://upstream/api/stream")
.body(BodyInserters.fromValue("")) // 注意:这里 body 可以为空,因为续传信息在 Header
.retrieve()
.bodyToMono(Void.class)
.then();
} else {
return Mono.error(new IllegalStateException("无缓存帧,无法安全重试"));
}这段代码的执行位置是在原请求已经失败的回调里,比如 exchange.getResponse().setComplete() 之后。需要确保 lastFrameRef 在过滤器阶段已经写入,否则重试时拿不到。验证方式可以在网关日志里打印 X-Resume-Token 的长度,然后在上游服务代理里打印收到的 Header,看是否与最后一帧内容一致。如果上游返回 4xx,优先检查 Header 的编码是否被网关改变,或者 Base64 后是否超过了 Header 长度限制(通常 8KB 以内)。
另外,不要把 X-Resume-Token 直接拼到 URL 上,因为流式请求的 URL 通常会被 CDN 或日志系统截断,而且查询参数有字符转义问题。
改完后看这几个信号
部署之后,观察以下几个信号,而不是只看成功与否:
- 网关日志里重试请求的
X-Resume-Token是否总是存在,且下一次请求的 token 与上一次最后帧一致。 - 上游服务的访问日志中,重试请求是否带了正确的 Header,并且上游返回码与普通请求一致。
- 网关进程的堆内存变化。由于每一帧都被复制成字节数组,如果请求体很大,内存曲线会上升。建议用
jstat或Actuator监控heap,确认没有频繁 GC 或 OOM。 - 当客户端主动中断连接时,网关的重试次数是否被限制。如果重试逻辑是在响应式流回调里无限触发的,需要加一个重试上限,比如 3 次。
检查内存时,如果发现堆内存持续升高,优先检查是否在过滤器中释放了原始 DataBuffer。我们的示例使用了 DataBufferUtils.release,但如果你用的是 retain,就必须在读取完新 buffer 后调用 release,否则会内存泄漏。
边界与回滚:什么情况需要回退到全量缓冲
这里要明确适用范围。只有在上游协议支持“从某个偏移量继续接收”或者“以最后帧作为续传标记”时,缓存最后一帧才有效。常见的支持场景包括:服务端能根据携带的 X-Resume-Token 找到上下文并跳过已有数据。如果上游只是一个标准的 POST 接收方,它把整个 body 当作一个完整请求,那么只给最后一帧会让上游无法重建数据。此时应该回退到“全量请求体缓存”,即把整个 body 保存到文件或内存,重试时重新发送。
全量缓存的配置在 Spring Cloud Gateway 里可以使用 ModifyRequestBodyGatewayFilter 的扩展实现,或者直接使用 cachedRequestBody 的 filter key。但要注意,全量缓存会占用整个请求体的内存,流式上传场景下可能导致内存瓶颈。所以需要结合业务判断:如果请求体平均很小,全量缓存更简单可靠;如果请求体非常大且可分段,才值得用“缓存最后一帧”的方案。
回滚也很简单:取消过滤器注册,或者把过滤器顺序调整回默认,然后观察重试是否恢复为“请求体不可用”的旧表现。这里不能只关闭过滤器,还要确认上游没有因为收到多出来的一帧而重复处理数据。建议先在灰度环境跑一个批量上传任务,对比成功率和资源占用后再决定。