0
# Sentinel Spring Cloud Gateway Adapter
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: sentinel-spring-cloud-gateway-adapter
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
      <groupId>com.alibaba.csp</groupId>
13
      <artifactId>sentinel-spring-cloud-gateway-adapter</artifactId>
14
      <version>1.8.8</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import com.alibaba.csp.sentinel.adapter.gateway.sc.SentinelGatewayFilter;
22
import com.alibaba.csp.sentinel.adapter.gateway.sc.exception.SentinelGatewayBlockExceptionHandler;
23
import com.alibaba.csp.sentinel.adapter.gateway.sc.callback.GatewayCallbackManager;
24
import com.alibaba.csp.sentinel.adapter.gateway.sc.callback.BlockRequestHandler;
25
```
26

27
## Basic Usage
28

29
```java
30
@Configuration
31
public class GatewayConfiguration {
32

33
    private final List<ViewResolver> viewResolvers;
34
    private final ServerCodecConfigurer serverCodecConfigurer;
35

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

42
    @Bean
43
    @Order(-1)
44
    public SentinelGatewayBlockExceptionHandler sentinelGatewayBlockExceptionHandler() {
45
        return new SentinelGatewayBlockExceptionHandler(viewResolvers, serverCodecConfigurer);
46
    }
47

48
    @Bean
49
    @Order(-1)
50
    public GlobalFilter sentinelGatewayFilter() {
51
        return new SentinelGatewayFilter();
52
    }
53
}
54
```
55

56
## Architecture
57

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

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

66
## Capabilities
67

68
### Core Integration
69

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

72
```java { .api }
73
public class SentinelGatewayFilter implements GatewayFilter, GlobalFilter, Ordered {
74
    public SentinelGatewayFilter();
75
    public SentinelGatewayFilter(int order);
76
    public SentinelGatewayFilter(RequestItemParser<ServerWebExchange> serverWebExchangeItemParser);
77
    public SentinelGatewayFilter(int order, RequestItemParser<ServerWebExchange> requestItemParser);
78
    
79
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain);
80
    public int getOrder();
81
}
82

83
public class SentinelGatewayBlockExceptionHandler implements WebExceptionHandler {
84
    public SentinelGatewayBlockExceptionHandler(List<ViewResolver> viewResolvers, ServerCodecConfigurer serverCodecConfigurer);
85
    
86
    public Mono<Void> handle(ServerWebExchange exchange, Throwable ex);
87
}
88
```
89

90
[Core Integration](./core-integration.md)
91

92
### Request Processing  
93

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

96
```java { .api }
97
public class ServerWebExchangeItemParser implements RequestItemParser<ServerWebExchange> {
98
    public ServerWebExchangeItemParser();
99
    
100
    public String getPath(ServerWebExchange exchange);
101
    public String getRemoteAddress(ServerWebExchange exchange);
102
    public String getHeader(ServerWebExchange exchange, String key);
103
    public String getUrlParam(ServerWebExchange exchange, String paramName);
104
    public String getCookieValue(ServerWebExchange exchange, String cookieName);
105
}
106
```
107

108
[Request Processing](./request-processing.md)
109

110
### Block Request Handling
111

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

114
```java { .api }
115
@FunctionalInterface
116
public interface BlockRequestHandler {
117
    Mono<ServerResponse> handleRequest(ServerWebExchange exchange, Throwable t);
118
}
119

120
public final class GatewayCallbackManager {
121
    public static BlockRequestHandler getBlockHandler();
122
    public static void setBlockHandler(BlockRequestHandler blockHandler);
123
    public static void resetBlockHandler();
124
    
125
    public static Function<ServerWebExchange, String> getRequestOriginParser();
126
    public static void setRequestOriginParser(Function<ServerWebExchange, String> requestOriginParser);
127
    public static void resetRequestOriginParser();
128
}
129
```
130

131
[Block Request Handling](./block-handling.md)
132

133
### API Definition Management
134

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

137
```java { .api }
138
public final class GatewayApiMatcherManager {
139
    public static Map<String, WebExchangeApiMatcher> getApiMatcherMap();
140
    public static Optional<WebExchangeApiMatcher> getMatcher(String apiName);
141
    public static Set<ApiDefinition> getApiDefinitionSet();
142
}
143

144
public class WebExchangeApiMatcher extends AbstractApiMatcher<ServerWebExchange> {
145
    public WebExchangeApiMatcher(ApiDefinition apiDefinition);
146
}
147
```
148

149
[API Definition Management](./api-management.md)
150

151
### Route Matching Utilities
152

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

155
```java { .api }
156
public final class RouteMatchers {
157
    public static com.alibaba.csp.sentinel.util.function.Predicate<ServerWebExchange> all();
158
    public static com.alibaba.csp.sentinel.util.function.Predicate<ServerWebExchange> antPath(String pathPattern);
159
    public static com.alibaba.csp.sentinel.util.function.Predicate<ServerWebExchange> exactPath(String path);
160
    public static com.alibaba.csp.sentinel.util.function.Predicate<ServerWebExchange> regexPath(String pathPattern);
161
}
162
```
163

164
[Route Matching](./route-matching.md)
165

166
## Dependencies
167

168
The adapter requires the following provided dependencies:
169

170
- **Spring Cloud Gateway Core** (`spring-cloud-gateway-core`) - Core Spring Cloud Gateway components
171
- **Spring WebFlux** (`spring-webflux`) - Reactive web framework
172
- **Sentinel API Gateway Adapter Common** (`sentinel-api-gateway-adapter-common`) - Common gateway adapter utilities
173
- **Sentinel Reactor Adapter** (`sentinel-reactor-adapter`) - Reactive Sentinel integration
174

175
## Common Integration Patterns
176

177
### Basic Setup
178
1. Add the Maven dependency to your project
179
2. Create `SentinelGatewayFilter` as a `@Bean` with `@Order(-1)` 
180
3. Create `SentinelGatewayBlockExceptionHandler` as a `@Bean` with `@Order(-1)`
181

182
### Custom Block Handling
183
Configure custom block request handlers via `GatewayCallbackManager.setBlockHandler()` to customize how blocked requests are handled.
184

185
### API Definition Setup
186
Use `GatewayApiMatcherManager` in conjunction with the common adapter's `GatewayApiDefinitionManager` to define custom API resources beyond route-based matching.
187

188
### Request Origin Parsing
189
Set custom request origin parsers via `GatewayCallbackManager.setRequestOriginParser()` to extract request origins for origin-based flow control rules.