插件扩展
说明#
- 插件是
Apache ShenYu网关的核心执行者，每个插件在开启的情况下，都会对匹配的流量，进行自己的处理。 - 在
Apache ShenYu网关里面，插件分为两类。- 一类是单一职责的调用链，不能对流量进行自定义的筛选。
- 一类是能对匹配的流量，执行自己的职责调用链。
- 用户可以参考 shenyu-plugin 模块，新增自己的插件处理，如果有好的公用插件，可以向官网提交
pr。
单一职责插件#
- 引入如下依赖：
<dependency> <groupId>org.apache.shenyu</groupId> <artifactId>shenyu-plugin-api</artifactId> <version>${project.version}</version></dependency>- 用户新增一个类
MyShenyuPlugin，直接实现org.apache.shenyu.plugin.api.ShenyuPlugin
public interface ShenyuPlugin {
/** * Process the Web request and (optionally) delegate to the next * {@code WebFilter} through the given {@link ShenyuPluginChain}. * * @param exchange the current server exchange * @param chain provides a way to delegate to the next filter * @return {@code Mono<Void>} to indicate when request processing is complete */ Mono<Void> execute(ServerWebExchange exchange, ShenyuPluginChain chain);
/** * return plugin order . * This attribute To determine the plugin execution order in the same type plugin. * * @return int order */ int getOrder();
/** * acquire plugin name. * this is plugin name define you must Provide the right name. * if you impl AbstractShenyuPlugin this attribute not use. * * @return plugin name. */ default String named() { return ""; }
/** * plugin is execute. * if return true this plugin can not execute. * * @param exchange the current server exchange * @return default false. */ default Boolean skip(ServerWebExchange exchange) { return false; }}
接口方法详细说明
execute()方法为核心的执行方法，用户可以在里面自由的实现自己想要的功能。getOrder()指定插件的排序。named()指定插件的名称，命名采用Camel Case，如：dubbo、springCloud。skip()在特定的条件下，该插件是否被跳过。
- 注册成
Spring的bean，参考如下，或者直接在实现类上加@Component注解。
@Bean public ShenyuPlugin myShenyuPlugin() { return new MyShenyuPlugin(); }单一职责插件与多语言#
- 上述用java写单一职责插件，如果想用其他语言写插件，至少需要你擅长的语言支持
WASM，你可以在这里 找到一些资料。在你了解过WASM后，我们引入以下依赖来构建插件的java部分：
<dependency> <groupId>org.apache.shenyu</groupId> <artifactId>shenyu-plugin-wasm-api</artifactId> <version>${project.version}</version></dependency>- 用户新增一个类
MyShenyuWasmPlugin，直接继承org.apache.shenyu.plugin.wasm.api.AbstractWasmPlugin
package x.y.z;
public class MyShenyuWasmPlugin extends AbstractWasmPlugin { private static final Map<Long, String> RESULTS = new ConcurrentHashMap<>(); @Override public int getOrder() { // 你的插件顺序 return 0; } @Override public String named() { return "你的插件名称"; } @Override protected Mono<Void> doExecute(final ServerWebExchange exchange, final ShenyuPluginChain chain, final Long argumentId) { final String result = RESULTS.remove(argumentId); // 调用其他语言返回的结果 return chain.execute(exchange); } @Override protected Long getArgumentId(final ServerWebExchange exchange, final ShenyuPluginChain chain) { // 需要根据exchange和chain生成参数的唯一id return 0L; } @Override protected Map<String, Func> initWasmCallJavaFunc(final Store<Void> store) { Map<String, Func> funcMap = new HashMap<>(); funcMap.put("get_args", WasmFunctions.wrap(store, WasmValType.I64, WasmValType.I64, WasmValType.I32, WasmValType.I32, (argId, addr, len) -> { // 其他语言从java获取参数的回调 String config = "hello from java " + argId; LOG.info("java side->" + config); ByteBuffer buf = super.getBuffer(); for (int i = 0; i < len && i < config.length(); i++) { buf.put(addr.intValue() + i, (byte) config.charAt(i)); } return Math.min(config.length(), len); })); funcMap.put("put_result", WasmFunctions.wrap(store, WasmValType.I64, WasmValType.I64, WasmValType.I32, WasmValType.I32, (argId, addr, len) -> { // 其他语言把调用结果传给java的回调 ByteBuffer buf = super.getBuffer(); byte[] bytes = new byte[len]; for (int i = 0; i < len; i++) { bytes[i] = buf.get(addr.intValue() + i); } String result = new String(bytes, StandardCharsets.UTF_8); RESULTS.put(argId, result); LOG.info("java side->" + result); return 0; })); return funcMap; } }- 创建其他语言的项目，下面以rust语言为例：
cd {shenyu}/shenyu-plugin/{your_plugin_moodule}/src/maincargo new --lib your_plugin_name- 在
lib.rs中新增execute方法：
#[link(wasm_import_module = "shenyu")]extern "C" { fn get_args(arg_id: i64, addr: i64, len: i32) -> i32;
fn put_result(arg_id: i64, addr: i64, len: i32) -> i32;}
// 加上`#[no_mangle]`以防止rust编译器修改方法名，这是必须的#[no_mangle]pub unsafe extern "C" fn execute(arg_id: i64) { let mut buf = [0u8; 32]; let buf_ptr = buf.as_mut_ptr() as i64; eprintln!("rust side-> buffer base address: {}", buf_ptr); // 从java那边获取参数 let len = get_args(arg_id, buf_ptr, buf.len() as i32); let java_arg = std::str::from_utf8(&buf[..len as usize]).unwrap(); eprintln!("rust side-> recv:{}", java_arg); // 这里添加rust部分的插件逻辑，比如rpc调用等等 // 把rust的调用结果传给java let rust_result = "rust result".as_bytes(); let result_ptr = rust_result.as_ptr() as i64; _ = put_result(arg_id, result_ptr, rust_result.len() as i32);}- 在
Cargo.toml中新增[lib]并把crate-type改为["cdylib"]，最终你的Cargo.toml应该像这样：
[package]name = "your_plugin_name"version = "0.1.0"edition = "2021"
[dependencies]# ......
[lib]crate-type = ["cdylib"]- 生成wasm文件：
cargo build --target wasm32-wasi --release- 你将看到
{shenyu}/shenyu-plugin/{your_plugin_moodule}/src/main/{your_plugin_name}/target/wasm32-wasi/release/{your_plugin_name}.wasm，重命名wasm文件，结合x.y.z.MyShenyuWasmPlugin的类路径，wasm文件名是x.y.z.MyShenyuWasmPlugin.wasm，最后把wasm文件放到你插件模块的resources文件夹下。
匹配流量处理插件#
- 引入如下依赖：
<dependency> <groupId>org.apache.shenyu</groupId> <artifactId>shenyu-plugin-base</artifactId> <version>${project.version}</version> </dependency>新增一个类
CustomPlugin，继承org.apache.shenyu.plugin.base.AbstractShenyuPlugin以下是参考：
/** * This is your custom plugin. * He is running in after before plugin, implement your own functionality. * extends AbstractShenyuPlugin so you must user shenyu-admin And add related plug-in development. * * @author xiaoyu(Myth) */public class CustomPlugin extends AbstractShenyuPlugin {
/** * return plugin order . * The same plugin he executes in the same order. * * @return int */ @Override public int getOrder() { return 0; }
/** * acquire plugin name. * return you custom plugin name. * It must be the same name as the plug-in you added in the admin background. * * @return plugin name. */ @Override public String named() { return "shenYu"; }
/** * plugin is execute. * Do I need to skip. * if you need skip return true. * * @param exchange the current server exchange * @return default false. */ @Override public Boolean skip(final ServerWebExchange exchange) { return false; }
/** * this is Template Method child has Implement your own logic. * * @param exchange exchange the current server exchange * @param chain chain the current chain * @param selector selector * @param rule rule * @return {@code Mono<Void>} to indicate when request handling is complete */ @Override protected abstract Mono<Void> doExecute(ServerWebExchange exchange, ShenyuPluginChain chain, SelectorData selector, RuleData rule) { LOGGER.debug(".......... function plugin start.............."); /* * Processing after your selector matches the rule. * rule.getHandle() is you Customize the json string to be processed. * for this example. * Convert your custom json string pass to an entity class. */ final String ruleHandle = rule.getHandle();
final Test test = GsonUtils.getInstance().fromJson(ruleHandle, Test.class);
/* * Then do your own business processing. * The last execution chain.execute(exchange). * Let it continue on the chain until the end. */ System.out.println(test.toString()); return chain.execute(exchange); }}
详细讲解：
继承该类的插件，插件会进行选择器规则匹配。
首先在
shenyu-admin后台管理系统 --> 基础配置 --> 插件管理 中，新增一个插件，注意 名称与 你自定义插件的named()方法要一致。重新登陆
shenyu-admin后台，可以看见刚新增的插件，然后就可以进行选择器规则匹配。在规则中，有个
handler字段，是自定义处理数据，在doExecute()方法中，通过final String ruleHandle = rule.getHandle();获取，然后进行你的操作。
注册成
Spring的bean，参考如下或者直接在实现类上加@Component注解。
@Bean public ShenyuPlugin customPlugin() { return new CustomPlugin(); }匹配流量处理插件与多语言#
- 大体逻辑与单一职责插件与多语言 类似，但java部分的依赖、其他语言需要新增的方法与
单一职责插件与多语言不同。以下是多语言匹配流量处理插件java部分所需要的依赖：
<dependency> <groupId>org.apache.shenyu</groupId> <artifactId>shenyu-plugin-wasm-base</artifactId> <version>${project.version}</version></dependency>- 以下是必须新增的方法(以rust语言为例)：
#[no_mangle]pub unsafe extern "C" fn doExecute(arg_id: i64) { //......}- 以下是可选的方法(以rust语言为例)：
#[no_mangle]pub unsafe extern "C" fn before(arg_id: i64) { //......}
#[no_mangle]pub unsafe extern "C" fn after(arg_id: i64) { //......}订阅你的插件数据，进行自定义的处理#
- 新增一个类
PluginDataHandler，实现org.apache.shenyu.plugin.base.handler.PluginDataHandler
public interface PluginDataHandler {
/** * Handler plugin. * * @param pluginData the plugin data */ default void handlerPlugin(PluginData pluginData) { }
/** * Remove plugin. * * @param pluginData the plugin data */ default void removePlugin(PluginData pluginData) { }
/** * Handler selector. * * @param selectorData the selector data */ default void handlerSelector(SelectorData selectorData) { }
/** * Remove selector. * * @param selectorData the selector data */ default void removeSelector(SelectorData selectorData) { }
/** * Handler rule. * * @param ruleData the rule data */ default void handlerRule(RuleData ruleData) { }
/** * Remove rule. * * @param ruleData the rule data */ default void removeRule(RuleData ruleData) { }
/** * Plugin named string. * * @return the string */ String pluginNamed();
}注意
pluginNamed()要和你自定义的插件名称相同。注册成
Spring的bean，参考如下或者直接在实现类上加@Component注解。
@Beanpublic PluginDataHandler pluginDataHandler() { return new PluginDataHandler();}动态加载自定义插件#
当使用此功能时候，上述扩展
ShenyuPlugin,PluginDataHandler, 不用成为spring bean。只需要构建出扩展项目的jar包即可。使用以下配置：
shenyu: extPlugin: path: //加载扩展插件jar包路径 enabled: true //是否开启 threads: 1 //加载插件线程数量 scheduleTime: 300 //间隔时间（单位：秒） scheduleDelay: 30 //网关启动后延迟多久加载（单位：秒）插件加载路径详解#
此路径是为存放扩展插件jar包的目录。
可以使用
-Dplugin-ext=xxxx指定，也可以使用shenyu.extPlugin.path配置文件指定，如果都没配置，默认会加载网关启动路径下的ext-lib目录。优先级 ：
-Dplugin-ext=xxxx>shenyu.extPlugin.path>ext-lib(default)
插件jar包上传#
- 当使用这个功能时候, 需要把上述扩展的
ShenyuPlugin打包成自定义的 ShenyuPlugin Jar 包 - 并且在 ShenyuAdmin 进行配置
- 进入 ShenyuAdmin - BasicConfig - Plugin 进行添加 plugin 在 pluginJar 中可以添加自定义的 plugin Jar 包
- 自定义的 ShenyuPlugin 如果依赖了其他的第三方包可以 ShenyuBootstrap 启动时加载到 -cp 的第三方jar包目录
注意:
上传jar包插件支持热加载
如果你需要在线修改jar包. 你可以重新打一个jar包. 并且提升版本号, 例如 1.0.1 升高至 1.0.2