Spring Cloud Gateway Java Routes API 深度解析

Spring Cloud Gateway Java Routes API 深度解析

spring-cloud-gateway A Gateway built on Spring Framework and Spring Boot providing routing and more. 项目地址: https://gitcode.com/gh_mirrors/sp/spring-cloud-gateway

概述

Spring Cloud Gateway 作为 Spring Cloud 生态中的 API 网关组件，提供了强大的路由功能。本文将重点介绍其基于 Java 的 Routes API 实现方式，特别是与 Spring WebMvc.fn 模块的集成使用。

核心概念

RouterFunctions.Builder

Spring Cloud Gateway Server MVC 默认使用 RouterFunctions.Builder 来创建路由，这些路由实际上是 RouterFunction 实例。这种方式提供了类型安全且流畅的 API 来定义路由规则。

获取 RouterFunctions.Builder 实例的基本方式是通过静态方法 RouterFunctions.route()：

import static org.springframework.web.servlet.function.RouterFunctions.route;

@Bean
public RouterFunction<ServerResponse> basicRoute() {
    return route()  // 获取Builder实例
        .GET("/example", handler)  // 定义GET路由
        .build();  // 构建RouterFunction
}

基础路由配置

简单路由示例

下面是一个完整的简单路由配置示例：

import static org.springframework.web.servlet.function.RouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;

@Configuration
public class GatewayConfig {
    
    @Bean
    public RouterFunction<ServerResponse> getRoute() {
        return route()
            .GET("/get", http())  // 定义GET请求处理
            .before(uri("https://example.org"))  // 添加前置过滤器
            .build();
    }
}

在这个示例中：

1. 定义了一个匹配 /get 路径的 GET 请求路由
2. 使用 http() 作为处理器函数
3. 添加了一个前置过滤器将请求转发到 https://example.org

HTTP 方法支持

RouterFunctions.Builder 提供了全面的 HTTP 方法支持：

route()
    .GET("/get", handler)
    .POST("/post", handler)
    .PUT("/put", handler)
    .DELETE("/delete", handler)
    .build();

高级路由配置

带路由ID的配置

Spring Cloud Gateway 提供了 GatewayRouterFunctions 类来支持更高级的路由配置，特别是需要添加路由元数据的场景：

import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;

@Bean
public RouterFunction<ServerResponse> advancedRoute() {
    return route("custom_route_id")  // 指定路由ID
        .GET("/advanced", http())
        .before(uri("https://api.example.com"))
        .build();
}

这种方式会自动将路由ID作为请求元数据添加，便于后续过滤器处理。

处理器函数详解

HTTP 处理器函数

HandlerFunctions.http() 是最基础的处理器函数，用于代理HTTP请求。它有两种使用方式：

1. 静态目标URI：

.route().GET("/static", http("https://static.target.com"))

2. 动态目标URI（通过请求属性获取）：

.route().GET("/dynamic", http())
// 需要在过滤器中设置MvcUtils.GATEWAY_REQUEST_URL_ATTR属性

注意：从4.1.7版本开始，HandlerFunctions.http(String) 和 HandlerFunctions.http(URI) 已被弃用，推荐使用 HandlerFunctions.http() 结合 BeforeFilterFunctions.uri() 过滤器的方式。

Spring Cloud Function 集成

当项目中包含 Spring Cloud Function 依赖时，Gateway 可以自动将函数Bean暴露为路由端点。

基本配置

首先添加依赖：

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-function-context</artifactId>
</dependency>

然后定义函数Bean：

@SpringBootApplication
public class FunctionGatewayApplication {

    public static void main(String[] args) {
        SpringApplication.run(FunctionGatewayApplication.class, args);
    }

    @Bean
    public Function<String, String> uppercase() {
        return String::toUpperCase;
    }
    
    @Bean
    public Function<String, String> repeat() {
        return s -> s + s;
    }
}

函数调用方式

1. GET请求（路径参数）：

GET /uppercase/hello → 返回 "HELLO"

2. POST请求（请求体）：

curl -d '"hello"' -H "Content-Type: application/json" -X POST http://localhost:8080/repeat
# 返回 "hellohello"

3. 函数组合：

curl -d '"hello"' -H "Content-Type: application/json" -X POST http://localhost:8080/repeat,uppercase
# 返回 "HELLOHELLO"

最佳实践

1. 路由组织：对于复杂路由配置，建议按功能模块拆分到不同的配置类中
2. 过滤器顺序：注意过滤器的执行顺序，前置过滤器(before)会按照添加顺序执行
3. 路由ID：始终为路由指定有意义的ID，便于监控和调试
4. 函数式端点：对于简单转换逻辑，优先考虑使用Spring Cloud Function集成

总结

Spring Cloud Gateway 的 Java Routes API 提供了强大而灵活的方式来定义和管理API网关路由。通过结合 Spring WebMvc.fn 的函数式编程模型和 Spring Cloud Function 的支持，开发者可以构建出既简洁又强大的网关配置。无论是简单的请求转发还是复杂的函数处理，这套API都能提供优雅的解决方案。

spring-cloud-gateway A Gateway built on Spring Framework and Spring Boot providing routing and more. 项目地址: https://gitcode.com/gh_mirrors/sp/spring-cloud-gateway