0
# Sentinel API Gateway Adapter Common
1

2
Sentinel API Gateway Adapter Common provides essential abstractions and utilities for implementing flow control and traffic shaping in API gateway environments within the Alibaba Sentinel ecosystem. This library enables API gateways to implement sophisticated traffic management capabilities including rate limiting, circuit breaking, concurrency control, and parameter-based flow control with dynamic rule configuration.
3

4
## Package Information
5

6
- **Package Name**: sentinel-api-gateway-adapter-common
7
- **Package Type**: maven
8
- **Group ID**: com.alibaba.csp
9
- **Language**: Java
10
- **Installation**: Add to your Maven pom.xml:
11

12
```xml
13
<dependency>  
14
    <groupId>com.alibaba.csp</groupId>
15
    <artifactId>sentinel-api-gateway-adapter-common</artifactId>
16
    <version>1.8.8</version>
17
</dependency>
18
```
19

20
## Core Imports
21

22
```java
23
import com.alibaba.csp.sentinel.adapter.gateway.common.SentinelGatewayConstants;
24
import com.alibaba.csp.sentinel.adapter.gateway.common.api.ApiDefinition;
25
import com.alibaba.csp.sentinel.adapter.gateway.common.api.GatewayApiDefinitionManager;
26
import com.alibaba.csp.sentinel.adapter.gateway.common.rule.GatewayFlowRule;
27
import com.alibaba.csp.sentinel.adapter.gateway.common.rule.GatewayRuleManager;
28
import com.alibaba.csp.sentinel.adapter.gateway.common.param.RequestItemParser;
29
import com.alibaba.csp.sentinel.adapter.gateway.common.slot.GatewayFlowSlot;
30
```
31

32
## Basic Usage
33

34
```java
35
import com.alibaba.csp.sentinel.adapter.gateway.common.api.*;
36
import com.alibaba.csp.sentinel.adapter.gateway.common.rule.*;
37
import static com.alibaba.csp.sentinel.adapter.gateway.common.SentinelGatewayConstants.*;
38

39
// Define API groups with predicates
40
ApiDefinition userApi = new ApiDefinition("user-api")
41
    .setPredicateItems(Set.of(
42
        new ApiPathPredicateItem()
43
            .setPattern("/api/users/**")
44
            .setMatchStrategy(URL_MATCH_STRATEGY_PREFIX)
45
    ));
46

47
// Load API definitions
48
Set<ApiDefinition> apis = Set.of(userApi);
49
GatewayApiDefinitionManager.loadApiDefinitions(apis);
50

51
// Create flow control rules
52
GatewayFlowRule flowRule = new GatewayFlowRule("user-api")
53
    .setResourceMode(RESOURCE_MODE_CUSTOM_API_NAME)
54
    .setGrade(FLOW_GRADE_QPS)
55
    .setCount(100)  // 100 QPS limit
56
    .setIntervalSec(1);
57

58
// Load gateway rules
59
Set<GatewayFlowRule> rules = Set.of(flowRule);
60
GatewayRuleManager.loadRules(rules);
61
```
62

63
## Architecture
64

65
Sentinel API Gateway Adapter Common is built around several key components:
66

67
- **Constants System**: `SentinelGatewayConstants` defining strategies and modes for gateway behavior
68
- **API Definition Management**: `ApiDefinition` and `GatewayApiDefinitionManager` for defining and managing API groups with flexible predicates
69
- **Rule Management**: `GatewayFlowRule` and `GatewayRuleManager` for flow control configuration with automatic conversion to core Sentinel rules
70
- **Parameter Parsing**: `RequestItemParser` interface and implementations for extracting parameters from gateway requests
71
- **Sentinel Integration**: `GatewayFlowSlot` providing flow control slot integration with Sentinel's processing chain
72
- **Command Interface**: REST-like handlers for dynamic rule and API definition management
73

74
## Capabilities
75

76
### API Definition System
77

78
Flexible system for defining and managing gateway API groups using predicates. Supports path-based matching with exact, prefix, and regex strategies.
79

80
```java { .api }
81
class ApiDefinition {
82
    ApiDefinition();
83
    ApiDefinition(String apiName);
84
    String getApiName();
85
    ApiDefinition setApiName(String apiName);
86
    Set<ApiPredicateItem> getPredicateItems();
87
    ApiDefinition setPredicateItems(Set<ApiPredicateItem> predicateItems);
88
}
89

90
class GatewayApiDefinitionManager {
91
    static void register2Property(SentinelProperty<Set<ApiDefinition>> property);
92
    static boolean loadApiDefinitions(Set<ApiDefinition> apiDefinitions);
93
    static ApiDefinition getApiDefinition(String apiName);
94
    static Set<ApiDefinition> getApiDefinitions();
95
    static boolean isValidApi(ApiDefinition apiDefinition);
96
}
97
```
98

99
[API Definition System](./api-definitions.md)
100

101
### Gateway Flow Rules
102

103
Comprehensive flow control rule system supporting QPS/thread-based limiting, burst control, and parameter-based flow control with automatic conversion to Sentinel core rules.
104

105
```java { .api }
106
class GatewayFlowRule {
107
    GatewayFlowRule();
108
    GatewayFlowRule(String resource);
109
    String getResource();
110
    GatewayFlowRule setResource(String resource);
111
    int getResourceMode();
112
    GatewayFlowRule setResourceMode(int resourceMode);
113
    int getGrade();
114
    GatewayFlowRule setGrade(int grade);
115
    double getCount();
116
    GatewayFlowRule setCount(double count);
117
    long getIntervalSec();
118
    GatewayFlowRule setIntervalSec(long intervalSec);
119
    int getControlBehavior();
120
    GatewayFlowRule setControlBehavior(int controlBehavior);
121
    GatewayParamFlowItem getParamItem();
122
    GatewayFlowRule setParamItem(GatewayParamFlowItem paramItem);
123
}
124

125
class GatewayRuleManager {
126
    static void register2Property(SentinelProperty<Set<GatewayFlowRule>> property);
127
    static boolean loadRules(Set<GatewayFlowRule> rules);
128
    static Set<GatewayFlowRule> getRules();
129
    static Set<GatewayFlowRule> getRulesForResource(String resourceName);
130
    static boolean isValidRule(GatewayFlowRule rule);
131
}
132
```
133

134
[Gateway Flow Rules](./gateway-flow-rules.md)
135

136
### Parameter Processing
137

138
System for extracting and processing parameters from gateway requests for parameter-based flow control. Supports client IP, headers, URL parameters, and cookies.
139

140
```java { .api }
141
interface RequestItemParser<T> {
142
    String getPath(T request);
143
    String getRemoteAddress(T request);
144
    String getHeader(T request, String key);
145
    String getUrlParam(T request, String paramName);
146
    String getCookieValue(T request, String cookieName);
147
}
148

149
class GatewayParamParser<T> {
150
    GatewayParamParser(RequestItemParser<T> requestItemParser);
151
    Object[] parseParameterFor(String resource, T request, Predicate<GatewayFlowRule> rulePredicate);
152
}
153
```
154

155
[Parameter Processing](./parameter-processing.md)
156

157
### Sentinel Integration
158

159
Integration components for embedding gateway flow control into Sentinel's processing chain with slot-based architecture.
160

161
```java { .api }
162
@Spi(order = -4000)
163
class GatewayFlowSlot extends AbstractLinkedProcessorSlot<DefaultNode> {
164
    void entry(Context context, ResourceWrapper resource, DefaultNode node, 
165
               int count, boolean prioritized, Object... args) throws Throwable;
166
    void exit(Context context, ResourceWrapper resourceWrapper, int count, Object... args);
167
}
168
```
169

170
[Sentinel Integration](./sentinel-integration.md)
171

172
### Command Handlers
173

174
REST-like command handlers for dynamic management of gateway rules and API definitions through Sentinel's command system.
175

176
```java { .api }
177
@CommandMapping(name = "gateway/getRules", desc = "Fetch all gateway rules")
178
class GetGatewayRuleCommandHandler implements CommandHandler<String> {
179
    CommandResponse<String> handle(CommandRequest request);
180
}
181

182
@CommandMapping(name = "gateway/updateRules", desc = "Update gateway rules")  
183
class UpdateGatewayRuleCommandHandler implements CommandHandler<String> {
184
    CommandResponse<String> handle(CommandRequest request);
185
    WritableDataSource<Set<GatewayFlowRule>> getWritableDataSource();
186
    void setWritableDataSource(WritableDataSource<Set<GatewayFlowRule>> gatewayFlowWds);
187
}
188
```
189

190
[Command Handlers](./command-handlers.md)
191

192
## Constants and Configuration
193

194
```java { .api }
195
class SentinelGatewayConstants {
196
    // Application type
197
    static final int APP_TYPE_GATEWAY = 1;
198
    
199
    // Resource modes
200
    static final int RESOURCE_MODE_ROUTE_ID = 0;
201
    static final int RESOURCE_MODE_CUSTOM_API_NAME = 1;
202
    
203
    // Parameter parse strategies
204
    static final int PARAM_PARSE_STRATEGY_CLIENT_IP = 0;
205
    static final int PARAM_PARSE_STRATEGY_HOST = 1;
206
    static final int PARAM_PARSE_STRATEGY_HEADER = 2;
207
    static final int PARAM_PARSE_STRATEGY_URL_PARAM = 3;
208
    static final int PARAM_PARSE_STRATEGY_COOKIE = 4;
209
    
210
    // URL matching strategies
211
    static final int URL_MATCH_STRATEGY_EXACT = 0;
212
    static final int URL_MATCH_STRATEGY_PREFIX = 1;
213
    static final int URL_MATCH_STRATEGY_REGEX = 2;
214
    
215
    // Parameter matching strategies
216
    static final int PARAM_MATCH_STRATEGY_EXACT = 0;
217
    static final int PARAM_MATCH_STRATEGY_PREFIX = 1;
218
    static final int PARAM_MATCH_STRATEGY_REGEX = 2;
219
    static final int PARAM_MATCH_STRATEGY_CONTAINS = 3;
220
}
221
```
222

223
[Constants and Configuration](./constants-configuration.md)