Selector And Rule Config
#
FeaturesThis document will introduce the use of selectors and rules in the Apache ShenYu background management system. For the concept and design of selectors and rules, please refer to Flow Control
.
Please refer to the deployment
document, choose a way to start shenyu-admin
. For example, local deployment. After startup, visit http://localhost:9095
, the default username and password are: admin
and 123456
.
#
SelectorAll plugins are displayed in the PluginList, and selectors and rules can be added to each plugin:
For example, add a selector to the divide
plugin:
selector detailed explanation:
- Name: create your selector with a distinguish name.
- Type: Choose request matching strategy.
custom
: Only handle requests that meet the following matching conditions.full
: Handle all requests.
- MatchType: Condition combination type.
and
: Need to meet all conditions.or
: Meet any of the conditions.
- Conditions:
- uri: filter request with uri.
- header: filter request with request header.
- query: filter request with query string.
- ip: filter request with your real ip.
- host: filter request with your real host.
- post: not recommend to use.
- cookie: filter request with cookie.
- req_method: filter request with request method.
- condition match:
- match : fuzzy string matching,recommend to combine with uri,support path-matching.(/test/**).
- = : matches only if they are equal.
- regEx : regex matching,match characters in regex expression.
- contains: when it contains the specified value, it matches.
- TimeBefore: before the specified time.
- TimeAfter: after the specified time.
- exclude: the inverse of the method of
match
. - startsWith: when its prefix is equal to the specified value, it matches. In certain scenarios,
match
can be replaced (such as/test/
instead of/test/**
) for better performance. - endsWith: when its suffix is equal to the specified value, it matches.
- pathPatter: it's an optimized version of
match
, which has better performance thanmatch
, but does not support writing**
in the middle of the path (such as/api/**/xxx
).
- Continued: whether the subsequent selector is still executed.
- PrintLogs: it will print the matching log with the open option enabled.
- Enable: whether to enable the plugin.
- Order:the smaller will have high priority to execute among multi-selectors.
- Handler: The operation when the request matches the selector.
the above picture means: when the prefix of the request uri is
/http
, it will redirect to this service127.0.0.1:8080
.selector advice : combine
uri
condition andstartsWith
prefix(/contextPath/)as the first request filter.selector(the same for rule) match condition fuzzy string matching rule:
?
matches one character*
matches zero or more characters**
matches zero or more directories in a path
#
Rulewhen the request was passed by the selector, then it will be processed by the rule, the final filter.
rule is the final confirmation about how to execute request logically.
rule detailed explanation:
Name:create your rule with a distinguish name.
MatchType: you can combine these conditions with 'and' , 'or' operators.
Conditions:
uri: filter request with uri.
header: filter request with request header.
query: filter request with query string.
ip: filter request with your real ip.
host: filter request with your real host.
post: not recommend to use.
cookie: filter request with cookie.
req_method: filter request with request method.
condition match:
- match : fuzzy string matching,recommend to combine with uri,support path-matching.(/test/**).
- = : matches only if they are equal.
- regEx : regex matching,match characters in regex expression.
- contains: when it contains the specified value, it matches.
- TimeBefore: before the specified time.
- TimeAfter: after the specified time.
- exclude: Same function as
match
, flow selection is opposite. - startsWith: when its prefix is equal to the specified value, it matches. In certain scenarios,
match
can be replaced (such as/test/
instead of/test/**
) for better performance. - endsWith: when its suffix is equal to the specified value, it matches.
- pathPatter: it's an optimized version of
match
, which has better performance thanmatch
, but does not support writing**
in the middle of the path (such as/api/**/xxx
).
PrintLogs: it will print the matching log with the open option enabled.
Enable: whether to enable the plugin.
Order:the smaller will have high priority to execute among multi-rules.
handle: The operation when the request matches the rule.
above picture means: when the request
uri
equals to/http/order/save
, it will execute based on this rule,load strategy israndom
.rule advice: combine
uri
condition withmatch
the realuri path
condition as the final filter.combine selector means :when the request
uri
is/http/order/save
, it will be redicted to127.0.0.1:8080
byrandom
method.
#
Match StrategyMatching mode refers to the matching mode between multiple conditions when a selector or rule is matched. Currently, and
and or
are supported.
and
and
indicates that a selector or rule can be matched only if more than one condition is met.The example below shows that a request must meet both the condition
uri = /http/order/findById
and the conditionid = 100
to match this rule.For example, a real request
http://localhost:9195/http/order/findById?id=100
satisfies both conditions, this rule can be matched.
or
or
indicates that one of the conditions matches a selector or rule.The example below shows that a request matches this rule if it meets either the condition
uri = /http/order/findById
or the conditionid = 100
.For example, a real request
http://localhost:9195/http/order/findById?id=99
satisfies the first conditionuri = /http/order/findById
, so it can also match this rule.
#
Condition Parameter DataConditional parameter Settings in selectors and rules are explained again. Suppose the following is a request header for an Http
request:
GET http://localhost:9195/http/order/findById?id=100Accept: application/jsonCookie: shenyu=shenyu_cookieMyHeader: custom-header
In ShenYu
you can set different conditional parameters to get real data from the request information.
- If the condition parameter is
uri
, then the actual data retrieved is/http/order/findById
; - If the condition parameter is
header
, the field name isMyHeader
, then the actual data retrieved iscustom-header
; - If the condition parameter is
query
, the field name isid
, then the actual data retrieved is100
; - If the condition parameter is
ip
, then the actual data retrieved is0:0:0:0:0:0:0:1
; - If the condition parameter is
host
, then the actual data retrieved is0:0:0:0:0:0:0:1
; - If the condition parameter is
post
, the field name iscontextPath
, then the actual data retrieved is/http
; - If the condition parameter is
cookie
, the field name isshenyu
, then the actual data retrieved isshenyu_cookie
; - If the condition parameter is
req_method
, then the actual data retrieved isGET
;
uri
(recommended)uri
matches are based on theuri
in the path you requested, and there is almost no change in the front end when accessing the gateway.When using
match
, the principle is the same asSpringMVC
fuzzy matching.In selectors, it is recommended to use prefixes in
URI
for matching, while in rules, specific paths are used for matching.When using this matching method, fill in the value of the matching field, as shown in the figure
/http/**
.
header
The
header
is matched against the field values in yourhttp
request header.When using this matching method, you need to fill in the field name and field value. The examples in the figure are
MyHeader
andcustom-header
respectively
query
This matches the query parameters in your
uri
, such as/test?id=1
, then the matching method can be selected.When using this matching method, you need to fill in the field name and field value. The examples in the figure are
id
and 1 respectively.
ip
This is matched against the
http
caller'sip
.Especially in waf plugin, if an
ip
address is found to be attacked, you can add a matching condition, fill in theip
, deny theip
access.If you use nginx proxy before ShenYu, you can get the right ip with refering to parsing-ip-and-host
When using this matching method, fill in the value of the matching field, as shown in the example
192.168.236.75
.
host
This is matched against the
http
caller'shost
.Especially in waf plugin, if an
host
address is found to be attacked, you can add a matching condition, fill in thehost
, deny thehost
access.If you use nginx proxy before ShenYu, you can get the right ip with refering to parsing-ip-and-host
When using this matching method, fill in the value of the matching field, as shown in the example
localhost
.
post
To get condition parameters from the request context(
org.apache.shenyu.plugin.api.context.ShenyuContext
), reflection is required to get the value of the field, which is not recommended.When using this matching method, the field name and value need to be specified. The examples in the figure are
contextPath
and/http
respectively.
cookie
This is matched against the
Cookie
in thehttp
caller's request header as a condition parameter.When using this matching method, you need to fill in the field name and field value. The examples in the figure are
shenyu
andshenyu_cookie
respectively.
req_method
This matches the request form of the
http
caller, such asGET
,POST
, etc.When using this matching method, fill in the value of the matching field, as shown in the example
GET
.
For a more in-depth understanding of condition parameter fetching, read the source code, package name is org.apache.shenyu.plugin.base.condition.data
:
Condition Parameter | Class |
---|---|
uri | URIParameterData |
header | HeaderParameterData |
query | QueryParameterData |
ip | IpParameterData |
host | HostParameterData |
post | PostParameterData |
cookie | CookieParameterData |
req_method | RequestMethodParameterData |
#
Condition Match StrategyCondition parameters allow you to retrieve the actual data of the request. How the real data matches the conditional data preset by the selector or rule is realized through the condition match strategy.
match
match
supports fuzzy matching (/**
). Request/http/order/findById
will match if your selector condition is set as follows.=
=
means that the requested real data is equal to the preset condition data. If your selector condition is set to request uri equal to/http/order/findById
, then request/http/order/findById?id=1
can match it.regex
regex
means that the requested real data can meet the preset condition of the regular expression to match successfully. Suppose your rule conditions are sets as follows: the request parameter contains anid
and is a three-digit number. So request/http/order/findById?id=900
will match.contains
contains
means that the requested real data contains the default condition data. Suppose your rule condition is set as follows: request uri containsfindById
. Request/http/order/findById?id=1
will match.TimeBefore
TimeBefore
indicates that the request time will be matched before the preset condition time. Suppose your rule conditions are sets as follows: request parameters containdate
anddate
is less than2021-09-26 06:12:10
. Request/http/order/findById?id=100&date=2021-09-22 06:12:10
will match.TimeAfter
TimeAfter
indicates that the request time will be matched before the preset condition time. Suppose your rule conditions are sets as follows: request parameters containdate
anddate
is greater than2021-09-26 06:12:10
. Request/http/order/findById?id=100&date=2021-09-22 06:12:10
will match.exclude
exclude
is the inverse of the method ofmatch
, and some functions ofmatch
are also available, but it is a matching filter. If your selector condition is set as follows, the request/http/order/findById
will filter this.startsWith
startsWith
indicates that the prefix of the requested real data is equal to the preset condition data. Suppose your rule conditions are sets as follows: the prefix in the requesturi
is equal to/http/
, the request/http/order/findById?id=1
can be matched.endsWith
endsWith
indicates that the suffix of the requested real data is equal to the preset condition data. Suppose your rule conditions are sets as follows: requesturi
suffix equalsId
. Then the request/http/order/findById?id=1
can be matched.pathPatter
Like
match
,pathPatter
supports fuzzy matching (/**
). If your rule conditions are sets as follows, then the request/http/order/findById
can be matched;Notice: writing
**
in the middle of the path (such as/api/**/xxx
) is not supported!
If you want to further understand conditions matching strategy, please read the source code, the package name is org.apache.shenyu.plugin.base.condition.judge
:
Match Strategy | Class |
---|---|
match | MatchPredicateJudge |
= | EqualsPredicateJudge |
regex | RegexPredicateJudge |
contains | ContainsPredicateJudge |
TimeBefore | TimerBeforePredicateJudge |
TimeAfter | TimerAfterPredicateJudge |
exclude | ExcludePredicateJudge |
startsWith | StartsWithPredicateJudge |
endsWith | EndsWithPredicateJudge |
pathPatter | PathPatternPredicateJudge |
The examples in this article illustrate the use of selectors and rules. The Settings of specific conditions need to be selected according to actual conditions.