Spring Cloud Gateway MVC 中 RewritePath 过滤器的正确配置方式

问题背景

在使用 Spring Cloud Gateway MVC 时，开发者经常需要对请求路径进行重写。RewritePath 是一个常用的过滤器，它允许开发者修改传入请求的路径。然而，许多开发者在通过 properties 文件配置时会遇到问题，而通过 @Bean 定义却能正常工作。

错误配置示例

在 properties 文件中，开发者可能会尝试以下配置方式：

spring.cloud.gateway.mvc.routesMap.suggestion1.predicates=Path=/api/suggestion/**
spring.cloud.gateway.mvc.routesMap.suggestion1.uri=${suggestion.application.url}
spring.cloud.gateway.mvc.routesMap.suggestion1.filters=RewritePath=/api/suggestion/(?<segment>.*), /api/$\\{segment}

这种配置会导致如下错误：

Factory method 'filterChain' threw exception with message: Error creating bean with name 'mvcHandlerMappingIntrospector'...
Unable to find operation interface org.springframework.web.servlet.function.HandlerFilterFunction for rewritePath with args...

正确配置方式

经过实践验证，正确的配置方式应该采用 YAML 风格的属性结构：

spring.cloud.gateway.mvc.routesMap.suggestion1.predicates=Path=/api/suggestion/**
spring.cloud.gateway.mvc.routesMap.suggestion1.uri=${suggestion.application.url}
spring.cloud.gateway.mvc.routesMap.suggestion1.filters[0].name=RewritePath
spring.cloud.gateway.mvc.routesMap.suggestion1.filters[0].args[regexp]=/api/suggestion/(?<segment>.*)
spring.cloud.gateway.mvc.routesMap.suggestion1.filters[0].args[replacement]=/api/${segment}

配置解析

1. 路由定义：首先定义路由的基本信息，包括匹配的路径和目标 URI
2. 过滤器数组：使用 filters[0] 表示第一个过滤器
3. 过滤器名称：明确指定过滤器名称为 RewritePath
4. 参数配置：
   • regexp：定义正则表达式匹配模式
   • replacement：定义替换后的路径模式

技术要点

1. 正则表达式捕获组：使用 (?<segment>.*) 创建命名捕获组，可以在替换模式中通过 ${segment} 引用
2. 转义处理：在替换模式中，$ 需要正确转义，但在 properties 文件中不需要额外转义
3. 数组索引：过滤器配置需要使用数组索引形式，即使只有一个过滤器

最佳实践建议

1. 对于复杂的路由配置，考虑使用 YAML 格式的配置文件，可读性更好
2. 在团队协作项目中，建议对路由配置进行文档化说明
3. 测试时可以先使用简单的重写规则验证基本功能，再逐步增加复杂性

通过以上配置方式，开发者可以顺利地在 Spring Cloud Gateway MVC 中使用 RewritePath 过滤器实现路径重写功能。