or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

api-management.mdblock-handling.mdcore-integration.mdindex.mdrequest-processing.mdroute-matching.md
tile.json

tessl/maven-com-alibaba-csp--sentinel-spring-cloud-gateway-adapter

Integration module providing flow control, traffic shaping, concurrency limiting, circuit breaking and system adaptive overload protection for Spring Cloud Gateway applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.alibaba.csp/sentinel-spring-cloud-gateway-adapter@1.8.x

To install, run

npx @tessl/cli install tessl/maven-com-alibaba-csp--sentinel-spring-cloud-gateway-adapter@1.8.0

index.mddocs/

Sentinel Spring Cloud Gateway Adapter

Sentinel Spring Cloud Gateway Adapter provides comprehensive integration between Alibaba Sentinel and Spring Cloud Gateway, enabling flow control, traffic shaping, concurrency limiting, circuit breaking, and system adaptive overload protection for reactive Spring Cloud Gateway applications. The adapter leverages the Sentinel Reactor Adapter to provide seamless integration with Spring WebFlux and reactive streams.

Package Information

  • Package Name: sentinel-spring-cloud-gateway-adapter
  • Package Type: maven
  • Language: Java
  • Installation: 
    <dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-spring-cloud-gateway-adapter</artifactId>
    <version>1.8.8</version>
</dependency>

Core Imports

import com.alibaba.csp.sentinel.adapter.gateway.sc.SentinelGatewayFilter;
import com.alibaba.csp.sentinel.adapter.gateway.sc.exception.SentinelGatewayBlockExceptionHandler;
import com.alibaba.csp.sentinel.adapter.gateway.sc.callback.GatewayCallbackManager;
import com.alibaba.csp.sentinel.adapter.gateway.sc.callback.BlockRequestHandler;

Basic Usage

@Configuration
public class GatewayConfiguration {

    private final List<ViewResolver> viewResolvers;
    private final ServerCodecConfigurer serverCodecConfigurer;

    public GatewayConfiguration(ObjectProvider<List<ViewResolver>> viewResolversProvider,
                                ServerCodecConfigurer serverCodecConfigurer) {
        this.viewResolvers = viewResolversProvider.getIfAvailable(Collections::emptyList);
        this.serverCodecConfigurer = serverCodecConfigurer;
    }

    @Bean
    @Order(-1)
    public SentinelGatewayBlockExceptionHandler sentinelGatewayBlockExceptionHandler() {
        return new SentinelGatewayBlockExceptionHandler(viewResolvers, serverCodecConfigurer);
    }

    @Bean
    @Order(-1)
    public GlobalFilter sentinelGatewayFilter() {
        return new SentinelGatewayFilter();
    }
}

Architecture

Sentinel Spring Cloud Gateway Adapter is built around several key components:

  • Core Integration: Main filter and exception handler for Spring Cloud Gateway integration
  • Request Processing: Parsers and utilities for extracting parameters from Spring WebFlux ServerWebExchange
  • Block Request Handling: Customizable handlers for blocked requests with JSON, HTML, and redirect support
  • API Matching: System for defining and matching custom API definitions beyond route-based resources
  • Route Matching: Path matching utilities supporting exact, Ant-style, and regex patterns

Capabilities

Core Integration

Main components for integrating Sentinel with Spring Cloud Gateway, providing the primary filter and exception handling mechanisms for reactive flow control.

public class SentinelGatewayFilter implements GatewayFilter, GlobalFilter, Ordered {
    public SentinelGatewayFilter();
    public SentinelGatewayFilter(int order);
    public SentinelGatewayFilter(RequestItemParser<ServerWebExchange> serverWebExchangeItemParser);
    public SentinelGatewayFilter(int order, RequestItemParser<ServerWebExchange> requestItemParser);
    
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain);
    public int getOrder();
}

public class SentinelGatewayBlockExceptionHandler implements WebExceptionHandler {
    public SentinelGatewayBlockExceptionHandler(List<ViewResolver> viewResolvers, ServerCodecConfigurer serverCodecConfigurer);
    
    public Mono<Void> handle(ServerWebExchange exchange, Throwable ex);
}

Core Integration

Request Processing

Components for parsing and extracting parameters from Spring WebFlux ServerWebExchange objects, enabling parameter-based flow control rules.

public class ServerWebExchangeItemParser implements RequestItemParser<ServerWebExchange> {
    public ServerWebExchangeItemParser();
    
    public String getPath(ServerWebExchange exchange);
    public String getRemoteAddress(ServerWebExchange exchange);
    public String getHeader(ServerWebExchange exchange, String key);
    public String getUrlParam(ServerWebExchange exchange, String paramName);
    public String getCookieValue(ServerWebExchange exchange, String cookieName);
}

Request Processing

Block Request Handling

Customizable handlers for processing blocked requests, supporting JSON responses, HTML responses, and redirects with flexible callback management.

@FunctionalInterface
public interface BlockRequestHandler {
    Mono<ServerResponse> handleRequest(ServerWebExchange exchange, Throwable t);
}

public final class GatewayCallbackManager {
    public static BlockRequestHandler getBlockHandler();
    public static void setBlockHandler(BlockRequestHandler blockHandler);
    public static void resetBlockHandler();
    
    public static Function<ServerWebExchange, String> getRequestOriginParser();
    public static void setRequestOriginParser(Function<ServerWebExchange, String> requestOriginParser);
    public static void resetRequestOriginParser();
}

Block Request Handling

API Definition Management

System for managing custom API definitions that extend beyond simple route-based resource identification, enabling fine-grained control over resource matching.

public final class GatewayApiMatcherManager {
    public static Map<String, WebExchangeApiMatcher> getApiMatcherMap();
    public static Optional<WebExchangeApiMatcher> getMatcher(String apiName);
    public static Set<ApiDefinition> getApiDefinitionSet();
}

public class WebExchangeApiMatcher extends AbstractApiMatcher<ServerWebExchange> {
    public WebExchangeApiMatcher(ApiDefinition apiDefinition);
}

API Definition Management

Route Matching Utilities

Path matching utilities providing support for exact, Ant-style pattern, and regular expression-based path matching for flexible resource identification.

public final class RouteMatchers {
    public static com.alibaba.csp.sentinel.util.function.Predicate<ServerWebExchange> all();
    public static com.alibaba.csp.sentinel.util.function.Predicate<ServerWebExchange> antPath(String pathPattern);
    public static com.alibaba.csp.sentinel.util.function.Predicate<ServerWebExchange> exactPath(String path);
    public static com.alibaba.csp.sentinel.util.function.Predicate<ServerWebExchange> regexPath(String pathPattern);
}

Route Matching

Dependencies

The adapter requires the following provided dependencies:

  • Spring Cloud Gateway Core (spring-cloud-gateway-core) - Core Spring Cloud Gateway components
  • Spring WebFlux (spring-webflux) - Reactive web framework
  • Sentinel API Gateway Adapter Common (sentinel-api-gateway-adapter-common) - Common gateway adapter utilities
  • Sentinel Reactor Adapter (sentinel-reactor-adapter) - Reactive Sentinel integration

Common Integration Patterns

Basic Setup

  1. Add the Maven dependency to your project
  2. Create SentinelGatewayFilter as a @Bean with @Order(-1)
  3. Create SentinelGatewayBlockExceptionHandler as a @Bean with @Order(-1)

Custom Block Handling

Configure custom block request handlers via GatewayCallbackManager.setBlockHandler() to customize how blocked requests are handled.

API Definition Setup

Use GatewayApiMatcherManager in conjunction with the common adapter's GatewayApiDefinitionManager to define custom API resources beyond route-based matching.

Request Origin Parsing

Set custom request origin parsers via GatewayCallbackManager.setRequestOriginParser() to extract request origins for origin-based flow control rules.