做过网关开发的同学肯定都遇到过这个问题：后端服务返回一个较大的 JSON 响应，但经过 Spring Cloud Gateway 转发后，响应体被截断了。前端收到不完整的 JSON 数据后，解析失败导致页面异常。特别是在返回大量数据的场景，比如数据导出、批量查询等，这个问题尤为突出。

我之前就遇到过这样一个案例：一个数据报表接口返回了大约 500KB 的 JSON 数据，但经过 Gateway 转发后，前端只收到了约 64KB 的数据。排查后发现，Gateway 默认的响应缓冲区大小限制就是 64KB，超过这个大小的响应会被自动截断。

今天我们就来聊聊 Spring Cloud Gateway 响应体截断的原因和解决方案，让您的网关能够正确处理大响应数据。

响应体截断的根本原因

1. 默认缓冲区大小限制

Spring Cloud Gateway 使用 Netty 作为底层网络框架，Netty 默认的响应缓冲区大小是 64KB：

场景模拟：
- 后端返回：500KB JSON 数据
- Gateway 缓冲区：64KB
- 实际转发：64KB（后面的 436KB 被丢弃）

结果：前端收到不完整的 JSON，解析失败！

2. 响应体被全部读取到内存

Gateway 的默认处理方式是将整个响应体读取到内存中，然后再转发给客户端：

处理流程：
后端响应 → Gateway 读取到内存（缓冲区）→ 转发给客户端

问题：
- 大响应会导致内存占用过高
- 缓冲区大小有限，超出部分被截断
- 内存中同时存在多个大响应会引发 OOM

3. 缺少流式处理机制

对比：
传统方式：一次性读取 → 内存占用 = 响应大小
流式方式：边读边写 → 内存占用 = 缓冲区大小

Gateway 默认采用传统方式，没有启用流式处理

解决方案：调整 Buffer + 流式写入

1. 核心设计思想

我们的方案核心是三个关键步骤：

1. 调整缓冲区大小：根据业务需求合理设置缓冲区
2. 启用流式处理：边读取边转发，不等待完整响应
3. 配置响应超时：避免长响应超时被中断

架构图如下：

┌─────────────────────────────────────────────────────────────────┐
│                   Gateway 响应流式转发流程                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  后端服务 ──→ Gateway ──→ 客户端                                │
│                   │                                             │
│                   ▼                                             │
│         ┌─────────────────┐                                    │
│         │ 响应过滤器       │                                    │
│         │ (流式处理)       │                                    │
│         └─────────────────┘                                    │
│                   │                                             │
│         ┌─────────┴─────────┐                                  │
│         │                   │                                  │
│         ▼                   ▼                                  │
│  读取缓冲区(8KB)     写入响应流                                 │
│         │                   │                                  │
│         └─────────┬─────────┘                                  │
│                   │                                             │
│                   ▼                                             │
│            循环直到响应结束                                     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

2. 调整缓冲区配置

# application.yml 配置示例

spring:
  cloud:
    gateway:
      httpclient:
        # 调整响应缓冲区大小（默认 64KB）
        response-timeout: 30s
        pool:
          max-connections: 200
      streaming:
        # 启用流式响应
        enabled: true
        # 流式缓冲区大小
        buffer-size: 8192

server:
  tomcat:
    # 调整最大 HTTP 头大小
    max-http-form-post-size: 50MB

netty:
  http:
    server:
      max-initial-line-length: 4096
      max-header-size: 8192

3. 自定义响应过滤器

// 流式响应过滤器
class StreamingResponseFilter implements GlobalFilter, Ordered {
    
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        // 获取原始响应
        ServerHttpResponse originalResponse = exchange.getResponse();
        
        // 创建流式响应包装器
        StreamingHttpResponseWrapper wrapper = new StreamingHttpResponseWrapper(originalResponse);
        
        // 修改 exchange 使用包装后的响应
        ServerWebExchange newExchange = exchange.mutate()
                .response(wrapper)
                .build();
        
        // 继续过滤器链
        return chain.filter(newExchange)
                .doOnSuccess(aVoid -> {
                    // 响应完成后的清理工作
                    wrapper.flush();
                });
    }

    @Override
    public int getOrder() {
        return -1; // 优先级最高
    }
}

4. 流式响应包装器

// 流式响应包装器
class StreamingHttpResponseWrapper extends ServerHttpResponseDecorator {
    
    private DataBufferFactory bufferFactory;
    private DataBuffer currentBuffer;
    private static final int BUFFER_SIZE = 8192; // 8KB

    public StreamingHttpResponseWrapper(ServerHttpResponse delegate) {
        super(delegate);
        this.bufferFactory = delegate.bufferFactory();
        this.currentBuffer = bufferFactory.allocateBuffer(BUFFER_SIZE);
    }

    @Override
    public Mono<Void> writeWith(Publisher<? extends DataBuffer> body) {
        Flux<DataBuffer> flux = Flux.from(body)
                .flatMap(dataBuffer -> {
                    return Flux.create(emitter -> {
                        try {
                            byte[] bytes = new byte[dataBuffer.readableByteCount()];
                            dataBuffer.read(bytes);
                            
                            int offset = 0;
                            while (offset < bytes.length) {
                                int remaining = bytes.length - offset;
                                int writeSize = Math.min(remaining, currentBuffer.writableByteCount());
                                
                                if (writeSize > 0) {
                                    currentBuffer.write(bytes, offset, writeSize);
                                    offset += writeSize;
                                }
                                
                                if (!currentBuffer.writable()) {
                                    emitter.next(currentBuffer);
                                    currentBuffer = bufferFactory.allocateBuffer(BUFFER_SIZE);
                                }
                            }
                            
                            emitter.complete();
                        } finally {
                            DataBufferUtils.release(dataBuffer);
                        }
                    });
                });
        
        return super.writeWith(flux);
    }

    public void flush() {
        if (currentBuffer.readableByteCount() > 0) {
            // 写入剩余数据
            getDelegate().writeWith(Mono.just(currentBuffer)).subscribe();
        }
    }
}

5. 响应超时配置

// 响应超时配置
@Configuration
public class GatewayTimeoutConfig {

    @Bean
    public WebClient.Builder webClientBuilder() {
        return WebClient.builder()
                .clientConnector(new ReactorClientHttpConnector(
                        HttpClient.create()
                                .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 10000)
                                .responseTimeout(Duration.ofSeconds(60))
                ));
    }
}

最佳实践与注意事项

1. 合理设置缓冲区大小

缓冲区大小选择原则：

┌─────────────────────────────────────────────────────────────┐
│ 响应大小范围   │ 建议缓冲区大小   │ 说明                     │
├────────────────┼──────────────────┼──────────────────────────┤
│ < 100KB       │ 8KB - 16KB      │ 小响应，减少内存占用     │
│ 100KB - 1MB   │ 32KB - 64KB     │ 中等响应，平衡性能       │
│ 1MB - 10MB    │ 128KB - 256KB   │ 大响应，提高吞吐         │
│ > 10MB        │ 512KB - 1MB     │ 超大响应，流式处理       │
└────────────────┴──────────────────┴──────────────────────────┘

2. 启用 Gzip 压缩

压缩配置：

spring:
  cloud:
    gateway:
      httpclient:
        compression:
          enabled: true
          min-response-size: 2048
          mime-types:
            - application/json
            - application/xml
            - text/html

3. 监控响应大小

监控指标：

┌──────────────────┬─────────────────────────────────────────┐
│ 指标名称         │ 说明                                   │
├──────────────────┼─────────────────────────────────────────┤
│ responseSize     │ 响应体大小                             │
│ responseTime     │ 响应时间                               │
│ bufferUsage      │ 缓冲区使用率                           │
│ truncatedCount   │ 被截断的响应数量                       │
│ timeoutCount     │ 超时的响应数量                         │
└──────────────────┴─────────────────────────────────────────┘

4. 处理大文件下载

大文件下载配置：

spring:
  servlet:
    multipart:
      max-file-size: 100MB
      max-request-size: 100MB

server:
  tomcat:
    connection-timeout: 60000
    async-timeout: 300000

5. 优雅关闭连接

连接关闭处理：

function handleClose(exchange):
    if exchange.isDisconnected():
        // 客户端断开连接，停止读取后端响应
        cancelPendingRequests()
    
    // 确保资源被正确释放
    releaseResources()

效果对比

总结

Spring Cloud Gateway 响应体截断修复的核心原则：

1. 调整缓冲区大小：根据业务需求设置合理的缓冲区
2. 启用流式处理：边读边写，减少内存占用
3. 配置超时时间：避免长响应被中断
4. 启用压缩：减少传输数据量
5. 监控告警：实时监控响应大小和截断情况

记住：缓冲区不是无限的，流式处理才是王道。通过合理配置和流式处理，可以让 Gateway 轻松应对各种大小的响应数据。

源码获取

文章已同步至小程序博客栏目，需要源码的请关注小程序博客。

公众号：服务端技术精选

小程序码：