在 Zuul 过滤器中修改响应体

1. 概述

本文将深入探讨 Netflix Zuul 中的 post 过滤器（Post Filter）。

Zuul 是 Netflix 提供的网关组件，常作为微服务架构中的边缘服务（Edge Service），位于客户端与后端多个微服务之间，承担路由、过滤、监控等职责。

其中，post 过滤器在最终响应返回给客户端之前执行。这意味着我们有机会对原始响应体进行干预，比如做日志记录、数据脱敏、格式转换等操作。

✅ 举个实际场景：你希望统一在网关层给所有接口响应添加一个 requestId 字段用于链路追踪，post 过滤器就是最佳选择。

⚠️ 但要注意：修改响应体属于“踩坑高发区”，处理不当容易引发流已关闭、内存溢出等问题。

2. 依赖配置

我们使用 Spring Cloud 环境集成 Zuul。在 pom.xml 中添加如下依赖：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2020.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-netflix-zuul</artifactId>
        <version>2.2.2.RELEASE</version>
    </dependency>
</dependencies>

🔍 最新版本可参考 Maven Central

3. 创建 Post 过滤器

Post 过滤器本质是一个继承 ZuulFilter 的普通 Java 类，并将 filterType() 返回值设为 post。

下面是一个简单的日志记录过滤器示例：

public class ResponseLogFilter extends ZuulFilter {

    private static final Logger logger = LoggerFactory.getLogger(ResponseLogFilter.class);

    @Override
    public String filterType() {
        return POST_TYPE; // 标识为 post 类型
    }

    @Override
    public int filterOrder() {
        return 0; // 执行顺序，越小越早执行
    }

    @Override
    public boolean shouldFilter() {
        return true; // 是否启用该过滤器
    }

    @Override
    public Object run() throws ZuulException {
        return null;
    }
}

关键点说明：

✅ filterType() 返回 POST_TYPE，表示这是个 post 阶段的过滤器
✅ shouldFilter() 返回 true 表示始终执行（生产环境建议通过配置控制）
✅ filterOrder() 控制多个 post 过滤器的执行顺序
⚠️ run() 是核心逻辑入口，接下来重点讲它如何修改响应体

4. 修改响应体内容

Zuul 允许我们在 post 阶段读取并修改响应体，但必须小心处理输入流（InputStream），否则极易出错。

4.1 完整示例：读取 + 修改 + 回写

@Override
public Object run() throws ZuulException {
    RequestContext context = RequestContext.getCurrentContext();
    
    try (final InputStream responseDataStream = context.getResponseDataStream()) {

        // 响应流可能为空（如服务超时、降级等情况）
        if (responseDataStream == null) {
            logger.info("BODY: {}", "");
            return null;
        }

        // 将流读取为字符串
        String responseData = CharStreams.toString(
            new InputStreamReader(responseDataStream, "UTF-8")
        );
        
        logger.info("原始响应体: {}", responseData);

        // ✅ 关键：必须重新设置回上下文，否则后续会报流已关闭
        context.setResponseBody(responseData);

    } catch (Exception e) {
        throw new ZuulException(e, INTERNAL_SERVER_ERROR.value(), e.getMessage());
    }

    return null;
}

4.2 要点解析

步骤	说明
`RequestContext.getCurrentContext()`	获取当前请求上下文，这是 Zuul 的“全局变量”容器
`getResponseDataStream()`	获取原始响应体输入流，只能读一次 ❗
流判空处理	微服务无响应或异常时流可能为 null，必须判断
`CharStreams.toString()`	来自 Guava，简单粗暴地把流转成字符串
`setResponseBody()`	✅ 必须调用！否则下游会抛 `IOException: Attempted read on a closed stream`

4.3 常见坑点

❌ 错误写法：不回写响应体

// 错！读完流没回写，后续 Zuul 自身处理时会报错
String body = IOUtils.toString(context.getResponseDataStream(), "UTF-8");
logger.info(body);
// 忘记 setResponseBody(body)

✅ 正确做法：读完必须重置

String body = IOUtils.toString(context.getResponseDataStream(), "UTF-8");
context.setResponseBody(body); // 回写，Zuul 后续会从这里取

⚠️ 性能提醒：如果响应体很大（如文件下载），直接转字符串可能导致 OOM。此时应考虑：

使用流式处理（如 JSON Streaming）
或仅对特定接口启用 body 修改逻辑

5. 总结

通过 post 过滤器，我们可以在响应返回客户端前灵活地操作响应体，适用于：

✅ 统一添加 traceId、responseTime 等公共字段
✅ 敏感信息脱敏（如手机号掩码）
✅ 响应格式标准化（如包装成统一 Result 结构）
✅ 记录完整响应日志用于排查

但也要注意：

❌ 避免在 post 过滤器中执行耗时操作，会阻塞主线程，拉长接口响应时间
❌ 谨慎处理大体积响应体，防止内存溢出
❌ 切勿遗漏 setResponseBody()，否则会触发流关闭异常

💡 源码示例已上传至 GitHub：https://github.com/eugenp/tutorials/tree/master/spring-cloud-modules/spring-cloud-zuul

Zuul 虽然逐渐被 Gateway 取代，但在老系统中仍广泛使用。掌握其过滤机制，尤其是响应体修改技巧，是网关开发的必备技能。

Persistence

REST

Security