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.