RewriteResponseHeader GatewayFilter Factory

概述

RewriteResponseHeader（重写响应头）GatewayFilter 工厂是 Spring Cloud Gateway 中用于修改下游服务响应头信息的过滤器。它通过 Java 正则表达式提供了灵活的方式来重写响应头的值，常用于敏感信息脱敏、数据格式转换等场景。

解决的业务问题

在微服务架构中，我们经常遇到以下场景需要修改响应头：

敏感信息脱敏：隐藏响应中的密码、令牌等敏感信息
数据格式标准化：统一不同服务返回的数据格式
安全增强：移除或修改可能暴露内部信息的响应头
版本兼容：为了向后兼容，修改响应头中的版本信息

参数说明

RewriteResponseHeader过滤器接受三个参数：

参数名	类型	描述
`name`	String	要重写的响应头名称
`regexp`	String	用于匹配的 Java 正则表达式
`replacement`	String	替换的内容，支持正则表达式组引用

参数使用逗号分隔，如果参数值本身包含逗号，需要进行适当的转义处理。

配置示例

YAML 配置方式

yaml

spring:
  cloud:
    gateway:
      routes:
        - id: rewriteresponseheader_route
          uri: https://example.org
          filters:
            # 将X-Response-Red头中的密码信息替换为***
            - RewriteResponseHeader=X-Response-Red, password=[^&]+, password=***

Kotlin DSL 配置方式

GatewayConfig.ktGatewayConfig.java

kotlin

import org.springframework.cloud.gateway.route.RouteLocator
import org.springframework.cloud.gateway.route.builder.RouteLocatorBuilder
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration
class GatewayConfig {

    @Bean
    fun customRouteLocator(builder: RouteLocatorBuilder): RouteLocator {
        return builder.routes()
            .route("rewriteresponseheader_route") { r ->
                r.path("/api/**")
                    .filters { f ->
                        // 重写响应头，隐藏敏感信息
                        f.rewriteResponseHeader(
                            "X-Response-Red",          // 响应头名称
                            "password=[^&]+",          // 匹配密码参数的正则表达式
                            "password=***"             // 替换为星号
                        )
                        // 支持链式调用，添加多个过滤器
                        f.rewriteResponseHeader(
                            "Location",                // 重写Location头
                            "http://",                 // 匹配http协议
                            "https://"                 // 替换为https协议
                        )
                    }
                    .uri("https://example.org")
            }
            .build()
    }
}

java

import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.cloud.gateway.route.builder.RouteLocatorBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class GatewayConfig {

    @Bean
    public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
        return builder.routes()
            .route("rewriteresponseheader_route", r ->
                r.path("/api/**")
                    .filters(f ->
                        f.rewriteResponseHeader(
                            "X-Response-Red",
                            "password=[^&]+",
                            "password=***"
                        )
                    )
                    .uri("https://example.org")
            )
            .build();
    }
}

实际业务场景示例

场景 1：用户信息脱敏

假设有一个用户服务，返回的响应头中包含用户详细信息，我们需要隐藏敏感信息：

kotlin

@Configuration
class UserServiceGatewayConfig {

    @Bean
    fun userServiceRoute(builder: RouteLocatorBuilder): RouteLocator {
        return builder.routes()
            .route("user_service") { r ->
                r.path("/user/**")
                    .filters { f ->
                        // 隐藏手机号中间4位
                        f.rewriteResponseHeader(
                            "X-User-Phone",
                            "(\\d{3})\\d{4}(\\d{4})",
                            "$1****$2"
                        )
                        // 隐藏邮箱用户名部分
                        f.rewriteResponseHeader(
                            "X-User-Email",
                            "([^@]{1,3})[^@]*(@.*)",
                            "$1***$2"
                        )
                    }
                    .uri("lb://user-service")
            }
            .build()
    }
}

场景 2：API 版本兼容

为了保持 API 的向后兼容性，将新版本的响应头格式转换为旧版本格式：

kotlin

@Configuration
class ApiVersionCompatibilityConfig {

    @Bean
    fun apiCompatibilityRoute(builder: RouteLocatorBuilder): RouteLocator {
        return builder.routes()
            .route("api_v1_compatibility") { r ->
                r.path("/api/v1/**")
                    .filters { f ->
                        // 将新版本的Content-Type转换为旧版本格式
                        f.rewriteResponseHeader(
                            "Content-Type",
                            "application/vnd\\.api\\+json;version=2",
                            "application/vnd.api+json;version=1"
                        )
                        // 移除新版本特有的响应头
                        f.rewriteResponseHeader(
                            "X-API-Features",
                            ".*",
                            ""
                        )
                    }
                    .uri("lb://api-service")
            }
            .build()
    }
}

场景 3：安全增强

移除可能暴露系统信息的响应头：

kotlin

@Configuration
class SecurityEnhancementConfig {

    @Bean
    fun securityRoute(builder: RouteLocatorBuilder): RouteLocator {
        return builder.routes()
            .route("secure_api") { r ->
                r.path("/secure/**")
                    .filters { f ->
                        // 移除服务器信息
                        f.rewriteResponseHeader(
                            "Server",
                            ".*",
                            "Gateway"
                        )
                        // 隐藏技术栈信息
                        f.rewriteResponseHeader(
                            "X-Powered-By",
                            ".*",
                            ""
                        )
                        // 统一错误信息格式
                        f.rewriteResponseHeader(
                            "X-Error-Detail",
                            "Internal.*",
                            "系统繁忙，请稍后重试"
                        )
                    }
                    .uri("lb://secure-service")
            }
            .build()
    }
}

正则表达式进阶用法

分组捕获和替换

kotlin

// 假设原始响应头: "X-Location: /api/v1/users/123/profile"
// 需要转换为: "/api/v2/users/123/profile"
f.rewriteResponseHeader(
    "X-Location",
    "/api/v1(/users/\\d+/.*)",  // 捕获除版本号外的路径
    "/api/v2$1"                 // 使用捕获组进行替换
)

复杂模式匹配

kotlin

// 处理复杂的URL参数重写
f.rewriteResponseHeader(
    "Location",
    "(.*[?&])token=([^&]+)(&.*|$)",  // 匹配token参数
    "$1token=***$3"                   // 保留其他参数，隐藏token
)

注意事项和最佳实践

在 YAML 配置中，如果需要使用`$`符号，必须写成`$\`，这是由于 YAML 规范的要求。

建议在开发环境中充分测试正则表达式，确保匹配和替换的准确性。

过滤器的执行顺序很重要，`RewriteResponseHeader`应该在其他可能修改响应头的过滤器之后执行。

性能优化建议

使用精确的正则表达式：避免使用过于宽泛的正则表达式，以提高匹配效率
合理使用过滤器：不要对不需要的路由应用此过滤器
监控过滤器性能：在生产环境中监控过滤器的执行时间

kotlin

@Component
class ResponseHeaderRewriteMetrics {

    private val meterRegistry: MeterRegistry

    constructor(meterRegistry: MeterRegistry) {
        this.meterRegistry = meterRegistry
    }

    @EventListener
    fun handleGatewayFilterEvent(event: GatewayFilterEvent) {
        // 记录过滤器执行时间和次数
        Timer.Sample.start(meterRegistry)
            .stop(Timer.builder("gateway.filter.rewrite.response.header")
                .description("RewriteResponseHeader filter execution time")
                .register(meterRegistry))
    }
}

常见问题和解决方案

问题 1：正则表达式不匹配

Details

解决方案检查正则表达式的转义字符，特别是在 YAML 配置中。可以使用在线正则表达式测试工具验证表达式的正确性。

问题 2：替换后的值为空

Details

解决方案确保替换字符串的格式正确，如果需要完全移除响应头，可以将 replacement 设置为空字符串。

问题 3：过滤器不生效

Details

解决方案检查路由匹配规则和过滤器的执行顺序，确保请求能够正确匹配到配置的路由。

总结

RewriteResponseHeader过滤器是 Spring Cloud Gateway 中一个强大的响应头处理工具，通过灵活的正则表达式支持，可以满足各种复杂的业务需求。在实际使用中，需要注意正则表达式的性能影响和配置的正确性，合理使用可以大大提升 API 网关的安全性和兼容性。

TIP

在设计 API 网关的响应头重写策略时，建议制定统一的规范，确保整个微服务体系的一致性和可维护性。

RewriteResponseHeader GatewayFilter Factory ​

概述 ​

解决的业务问题 ​

参数说明 ​

配置示例 ​

YAML 配置方式 ​

Kotlin DSL 配置方式 ​

实际业务场景示例 ​

场景 1：用户信息脱敏 ​

场景 2：API 版本兼容 ​

场景 3：安全增强 ​

正则表达式进阶用法 ​

分组捕获和替换 ​

复杂模式匹配 ​

注意事项和最佳实践 ​

性能优化建议 ​

常见问题和解决方案 ​

问题 1：正则表达式不匹配 ​

问题 2：替换后的值为空 ​

问题 3：过滤器不生效 ​

总结 ​

RewriteResponseHeader GatewayFilter Factory

概述

解决的业务问题

参数说明

配置示例

YAML 配置方式

Kotlin DSL 配置方式

实际业务场景示例

场景 1：用户信息脱敏

场景 2：API 版本兼容

场景 3：安全增强

正则表达式进阶用法

分组捕获和替换

复杂模式匹配

注意事项和最佳实践

性能优化建议

常见问题和解决方案

问题 1：正则表达式不匹配

问题 2：替换后的值为空

问题 3：过滤器不生效

总结