0
# Constants and Configuration
1

2
The Constants and Configuration system provides essential constants and configuration values used throughout the Sentinel API Gateway Adapter Common library. These constants define various strategies, modes, and behaviors for gateway flow control and API matching.
3

4
## Capabilities
5

6
### SentinelGatewayConstants
7

8
Central collection of constants used throughout the gateway adapter system for consistent configuration and behavior.
9

10
```java { .api }
11
/**
12
 * Constants for gateway adapter configuration and behavior
13
 */
14
final class SentinelGatewayConstants {
15
    // Application Type Constants
16
    
17
    /** Gateway application type identifier */
18
    static final int APP_TYPE_GATEWAY = 1;
19
    
20
    // Resource Mode Constants
21
    
22
    /** Resource identified by route ID */
23
    static final int RESOURCE_MODE_ROUTE_ID = 0;
24
    
25
    /** Resource identified by custom API name */
26
    static final int RESOURCE_MODE_CUSTOM_API_NAME = 1;
27
    
28
    // Parameter Parse Strategy Constants
29
    
30
    /** Parse client IP address */
31
    static final int PARAM_PARSE_STRATEGY_CLIENT_IP = 0;
32
    
33
    /** Parse host header */
34
    static final int PARAM_PARSE_STRATEGY_HOST = 1;
35
    
36
    /** Parse arbitrary header */
37
    static final int PARAM_PARSE_STRATEGY_HEADER = 2;
38
    
39
    /** Parse URL parameter */
40
    static final int PARAM_PARSE_STRATEGY_URL_PARAM = 3;
41
    
42
    /** Parse cookie value */
43
    static final int PARAM_PARSE_STRATEGY_COOKIE = 4;
44
    
45
    // URL Matching Strategy Constants
46
    
47
    /** Exact match */
48
    static final int URL_MATCH_STRATEGY_EXACT = 0;
49
    
50
    /** Prefix match */
51
    static final int URL_MATCH_STRATEGY_PREFIX = 1;
52
    
53
    /** Regular expression match */
54
    static final int URL_MATCH_STRATEGY_REGEX = 2;
55
    
56
    // Parameter Matching Strategy Constants
57
    
58
    /** Exact match */
59
    static final int PARAM_MATCH_STRATEGY_EXACT = 0;
60
    
61
    /** Prefix match */
62
    static final int PARAM_MATCH_STRATEGY_PREFIX = 1;
63
    
64
    /** Regular expression match */
65
    static final int PARAM_MATCH_STRATEGY_REGEX = 2;
66
    
67
    /** Contains match */
68
    static final int PARAM_MATCH_STRATEGY_CONTAINS = 3;
69
    
70
    // Context Constants
71
    
72
    /** Default gateway context name */
73
    static final String GATEWAY_CONTEXT_DEFAULT = "sentinel_gateway_context_default";
74
    
75
    /** Gateway context prefix */
76
    static final String GATEWAY_CONTEXT_PREFIX = "sentinel_gateway_context$$";
77
    
78
    /** Gateway route context prefix */
79
    static final String GATEWAY_CONTEXT_ROUTE_PREFIX = "sentinel_gateway_context$$route$$";
80
    
81
    // Parameter Constants
82
    
83
    /** Parameter for non-matching requests */
84
    static final String GATEWAY_NOT_MATCH_PARAM = "$NM";
85
    
86
    /** Default parameter marker */
87
    static final String GATEWAY_DEFAULT_PARAM = "$D";
88
}
89
```
90

91
## Application Type Configuration
92

93
### Gateway Application Type
94

95
The `APP_TYPE_GATEWAY` constant identifies applications as gateway services within the Sentinel ecosystem:
96

97
```java
98
// Usage in application configuration
99
public class GatewayAppConfig {
100
    static {
101
        // Mark this application as a gateway
102
        AppNameUtil.setAppType(SentinelGatewayConstants.APP_TYPE_GATEWAY);
103
    }
104
}
105
```
106

107
## Resource Mode Configuration
108

109
Resource modes determine how gateway resources are identified and matched:
110

111
### Route ID Mode (RESOURCE_MODE_ROUTE_ID = 0)
112

113
Resources are identified by specific route identifiers from the gateway configuration:
114

115
```java
116
// Route-based flow control
117
GatewayFlowRule routeRule = new GatewayFlowRule("user-service-route")
118
    .setResourceMode(SentinelGatewayConstants.RESOURCE_MODE_ROUTE_ID)
119
    .setGrade(RuleConstant.FLOW_GRADE_QPS)
120
    .setCount(100);
121

122
// Context creation for route-based resources
123
String routeContext = SentinelGatewayConstants.GATEWAY_CONTEXT_ROUTE_PREFIX + "user-service-route";
124
ContextUtil.enter(routeContext);
125
```
126

127
### Custom API Name Mode (RESOURCE_MODE_CUSTOM_API_NAME = 1)
128

129
Resources are identified by custom API names defined through `ApiDefinition`:
130

131
```java
132
// API-based flow control
133
GatewayFlowRule apiRule = new GatewayFlowRule("user-api")
134
    .setResourceMode(SentinelGatewayConstants.RESOURCE_MODE_CUSTOM_API_NAME)
135
    .setGrade(RuleConstant.FLOW_GRADE_QPS)
136
    .setCount(200);
137

138
// Must be used with corresponding ApiDefinition
139
ApiDefinition userApi = new ApiDefinition("user-api")
140
    .setPredicateItems(Set.of(
141
        new ApiPathPredicateItem()
142
            .setPattern("/api/users/**")
143
            .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_PREFIX)
144
    ));
145
```
146

147
## Parameter Parse Strategies
148

149
These constants define how parameters are extracted from gateway requests for parameter-based flow control:
150

151
### Client IP Strategy (PARAM_PARSE_STRATEGY_CLIENT_IP = 0)
152

153
Extracts the client's IP address:
154

155
```java
156
// IP-based flow control
157
GatewayParamFlowItem ipParam = new GatewayParamFlowItem()
158
    .setParseStrategy(SentinelGatewayConstants.PARAM_PARSE_STRATEGY_CLIENT_IP);
159

160
GatewayFlowRule ipRule = new GatewayFlowRule("api-endpoint")
161
    .setGrade(RuleConstant.FLOW_GRADE_QPS)
162
    .setCount(10)  // 10 QPS per IP
163
    .setParamItem(ipParam);
164
```
165

166
### Host Strategy (PARAM_PARSE_STRATEGY_HOST = 1)
167

168
Extracts the Host header value:
169

170
```java
171
// Host-based flow control
172
GatewayParamFlowItem hostParam = new GatewayParamFlowItem()
173
    .setParseStrategy(SentinelGatewayConstants.PARAM_PARSE_STRATEGY_HOST);
174

175
GatewayFlowRule hostRule = new GatewayFlowRule("multi-tenant-api")
176
    .setGrade(RuleConstant.FLOW_GRADE_QPS)
177
    .setCount(500)  // 500 QPS per host
178
    .setParamItem(hostParam);
179
```
180

181
### Header Strategy (PARAM_PARSE_STRATEGY_HEADER = 2)
182

183
Extracts a specific header value (requires `fieldName`):
184

185
```java
186
// Header-based flow control
187
GatewayParamFlowItem headerParam = new GatewayParamFlowItem()
188
    .setParseStrategy(SentinelGatewayConstants.PARAM_PARSE_STRATEGY_HEADER)
189
    .setFieldName("X-User-ID");
190

191
GatewayFlowRule userRule = new GatewayFlowRule("user-specific-api")
192
    .setGrade(RuleConstant.FLOW_GRADE_QPS)
193
    .setCount(50)  // 50 QPS per user
194
    .setParamItem(headerParam);
195
```
196

197
### URL Parameter Strategy (PARAM_PARSE_STRATEGY_URL_PARAM = 3)
198

199
Extracts a URL query parameter value (requires `fieldName`):
200

201
```java
202
// URL parameter-based flow control
203
GatewayParamFlowItem urlParam = new GatewayParamFlowItem()
204
    .setParseStrategy(SentinelGatewayConstants.PARAM_PARSE_STRATEGY_URL_PARAM)
205
    .setFieldName("api_key");
206

207
GatewayFlowRule apiKeyRule = new GatewayFlowRule("api-service")
208
    .setGrade(RuleConstant.FLOW_GRADE_QPS)
209
    .setCount(1000)  // 1000 QPS per API key
210
    .setParamItem(urlParam);
211
```
212

213
### Cookie Strategy (PARAM_PARSE_STRATEGY_COOKIE = 4)
214

215
Extracts a cookie value (requires `fieldName`):
216

217
```java
218
// Cookie-based flow control
219
GatewayParamFlowItem cookieParam = new GatewayParamFlowItem()
220
    .setParseStrategy(SentinelGatewayConstants.PARAM_PARSE_STRATEGY_COOKIE)
221
    .setFieldName("session_id");
222

223
GatewayFlowRule sessionRule = new GatewayFlowRule("session-api")
224
    .setGrade(RuleConstant.FLOW_GRADE_QPS)
225
    .setCount(20)  // 20 QPS per session
226
    .setParamItem(cookieParam);
227
```
228

229
## URL Matching Strategies
230

231
These constants define how URL patterns are matched against incoming requests:
232

233
### Exact Match (URL_MATCH_STRATEGY_EXACT = 0)
234

235
Requires exact string match:
236

237
```java
238
// Exact path matching
239
ApiPathPredicateItem exactMatch = new ApiPathPredicateItem()
240
    .setPattern("/api/users/profile")
241
    .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_EXACT);
242

243
// Only matches exactly "/api/users/profile"
244
```
245

246
### Prefix Match (URL_MATCH_STRATEGY_PREFIX = 1)
247

248
Matches any URL starting with the pattern:
249

250
```java
251
// Prefix matching (most common)
252
ApiPathPredicateItem prefixMatch = new ApiPathPredicateItem()
253
    .setPattern("/api/users")
254
    .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_PREFIX);
255

256
// Matches "/api/users", "/api/users/123", "/api/users/profile", etc.
257
```
258

259
### Regex Match (URL_MATCH_STRATEGY_REGEX = 2)
260

261
Uses regular expression matching:
262

263
```java
264
// Regex matching for complex patterns
265
ApiPathPredicateItem regexMatch = new ApiPathPredicateItem()
266
    .setPattern("/api/users/\\d+/orders")
267
    .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_REGEX);
268

269
// Matches "/api/users/123/orders", "/api/users/456/orders", etc.
270
```
271

272
## Parameter Matching Strategies
273

274
These constants define how parameter values are matched against patterns:
275

276
### Exact Match (PARAM_MATCH_STRATEGY_EXACT = 0)
277

278
Requires exact string match:
279

280
```java
281
// Exact parameter matching
282
GatewayParamFlowItem exactParam = new GatewayParamFlowItem()
283
    .setParseStrategy(SentinelGatewayConstants.PARAM_PARSE_STRATEGY_HEADER)
284
    .setFieldName("User-Type")
285
    .setPattern("premium")
286
    .setMatchStrategy(SentinelGatewayConstants.PARAM_MATCH_STRATEGY_EXACT);
287

288
// Only matches when User-Type header is exactly "premium"
289
```
290

291
### Prefix Match (PARAM_MATCH_STRATEGY_PREFIX = 1)
292

293
Matches parameters starting with the pattern:
294

295
```java
296
// Prefix parameter matching
297
GatewayParamFlowItem prefixParam = new GatewayParamFlowItem()
298
    .setParseStrategy(SentinelGatewayConstants.PARAM_PARSE_STRATEGY_HEADER)
299
    .setFieldName("API-Key")
300
    .setPattern("dev_")
301
    .setMatchStrategy(SentinelGatewayConstants.PARAM_MATCH_STRATEGY_PREFIX);
302

303
// Matches "dev_123", "dev_test", etc.
304
```
305

306
### Regex Match (PARAM_MATCH_STRATEGY_REGEX = 2)
307

308
Uses regular expression matching:
309

310
```java
311
// Regex parameter matching
312
GatewayParamFlowItem regexParam = new GatewayParamFlowItem()
313
    .setParseStrategy(SentinelGatewayConstants.PARAM_PARSE_STRATEGY_HEADER)
314
    .setFieldName("User-ID")
315
    .setPattern("user_\\d+")
316
    .setMatchStrategy(SentinelGatewayConstants.PARAM_MATCH_STRATEGY_REGEX);
317

318
// Matches "user_123", "user_456", etc.
319
```
320

321
### Contains Match (PARAM_MATCH_STRATEGY_CONTAINS = 3)
322

323
Matches parameters containing the pattern:
324

325
```java
326
// Contains parameter matching
327
GatewayParamFlowItem containsParam = new GatewayParamFlowItem()
328
    .setParseStrategy(SentinelGatewayConstants.PARAM_PARSE_STRATEGY_HEADER)
329
    .setFieldName("Authorization")
330
    .setPattern("Bearer")
331
    .setMatchStrategy(SentinelGatewayConstants.PARAM_MATCH_STRATEGY_CONTAINS);
332

333
// Matches "Bearer token123", "JWT Bearer abc", etc.
334
```
335

336
## Context Configuration
337

338
Gateway contexts are used to organize and isolate different types of gateway traffic:
339

340
### Default Gateway Context
341

342
```java
343
// Use default gateway context
344
ContextUtil.enter(SentinelGatewayConstants.GATEWAY_CONTEXT_DEFAULT);
345

346
// Context name: "sentinel_gateway_context_default"
347
```
348

349
### Custom Gateway Context
350

351
```java
352
// Create custom gateway context
353
String customContext = SentinelGatewayConstants.GATEWAY_CONTEXT_PREFIX + "api-v1";
354
ContextUtil.enter(customContext);
355

356
// Context name: "sentinel_gateway_context$$api-v1"
357
```
358

359
### Route-Specific Context
360

361
```java
362
// Create route-specific context
363
String routeContext = SentinelGatewayConstants.GATEWAY_CONTEXT_ROUTE_PREFIX + "payment-service";
364
ContextUtil.enter(routeContext);
365

366
// Context name: "sentinel_gateway_context$$route$$payment-service"
367
```
368

369
## Special Parameter Values
370

371
### Non-Matching Parameter (GATEWAY_NOT_MATCH_PARAM = "$NM")
372

373
Used internally when parameter extraction fails or doesn't match any pattern:
374

375
```java
376
// Internal usage - indicates parameter didn't match any pattern
377
// This constant is used by the parameter parsing system automatically
378
```
379

380
### Default Parameter (GATEWAY_DEFAULT_PARAM = "$D")
381

382
Used internally as a default parameter marker:
383

384
```java
385
// Internal usage - default parameter value
386
// This constant is used by the parameter parsing system automatically
387
```
388

389
## Configuration Best Practices
390

391
### Consistent Strategy Usage
392

393
```java
394
// Use consistent matching strategies within related rules
395
public class ConsistentMatchingExample {
396
    public void setupConsistentRules() {
397
        // All user-related APIs use prefix matching
398
        ApiDefinition userApi = new ApiDefinition("user-api")
399
            .setPredicateItems(Set.of(
400
                new ApiPathPredicateItem()
401
                    .setPattern("/api/users")
402
                    .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_PREFIX),
403
                new ApiPathPredicateItem()
404
                    .setPattern("/api/user-profile")
405
                    .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_PREFIX)
406
            ));
407
    }
408
}
409
```
410

411
### Performance Considerations
412

413
```java
414
public class PerformanceOptimizedConfig {
415
    public void setupOptimizedRules() {
416
        // Prefer exact/prefix matching over regex for better performance
417
        ApiPathPredicateItem fastMatch = new ApiPathPredicateItem()
418
            .setPattern("/api/health")
419
            .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_EXACT);  // Fast
420
        
421
        // Use regex sparingly and cache patterns
422
        ApiPathPredicateItem complexMatch = new ApiPathPredicateItem()
423
            .setPattern("/api/users/\\d+")
424
            .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_REGEX);  // Slower
425
        
426
        // Pre-cache regex patterns
427
        GatewayRegexCache.addRegexPattern("/api/users/\\d+");
428
    }
429
}
430
```
431

432
## Configuration Validation
433

434
```java
435
public class ConfigurationValidator {
436
    public boolean validateConfiguration(GatewayFlowRule rule) {
437
        // Validate resource mode
438
        if (rule.getResourceMode() != SentinelGatewayConstants.RESOURCE_MODE_ROUTE_ID && 
439
            rule.getResourceMode() != SentinelGatewayConstants.RESOURCE_MODE_CUSTOM_API_NAME) {
440
            return false;
441
        }
442
        
443
        // Validate parameter item if present
444
        GatewayParamFlowItem paramItem = rule.getParamItem();
445
        if (paramItem != null) {
446
            int strategy = paramItem.getParseStrategy();
447
            if (strategy < SentinelGatewayConstants.PARAM_PARSE_STRATEGY_CLIENT_IP || 
448
                strategy > SentinelGatewayConstants.PARAM_PARSE_STRATEGY_COOKIE) {
449
                return false;
450
            }
451
            
452
            // Check required field name for certain strategies
453
            if (strategy == SentinelGatewayConstants.PARAM_PARSE_STRATEGY_HEADER ||
454
                strategy == SentinelGatewayConstants.PARAM_PARSE_STRATEGY_URL_PARAM ||
455
                strategy == SentinelGatewayConstants.PARAM_PARSE_STRATEGY_COOKIE) {
456
                if (paramItem.getFieldName() == null || paramItem.getFieldName().isEmpty()) {
457
                    return false;
458
                }
459
            }
460
        }
461
        
462
        return true;
463
    }
464
}
465
```
466

467
## Best Practices
468

469
1. **Use appropriate matching strategies** - exact for specific endpoints, prefix for API groups, regex sparingly
470
2. **Validate constants usage** - ensure correct constant values are used for strategies and modes
471
3. **Pre-cache regex patterns** using `GatewayRegexCache` for better performance
472
4. **Use consistent context naming** following the established prefix patterns
473
5. **Prefer simpler matching strategies** (exact/prefix) over complex ones (regex) for performance
474
6. **Document custom constants** if extending the system with additional configuration values
475
7. **Validate configuration** programmatically before applying rules in production
476
8. **Use meaningful resource names** that align with your gateway routing configuration