插件扩展

说明

  • 插件是 Apache ShenYu 网关的核心执行者,每个插件在开启的情况下,都会对匹配的流量,进行自己的处理。
  • Apache ShenYu 网关里面,插件分为两类。
    • 一类是单一职责的调用链,不能对流量进行自定义的筛选。
    • 一类是能对匹配的流量,执行自己的职责调用链。
  • 用户可以参考 shenyu-plugin 模块,新增自己的插件处理,如果有好的公用插件,可以向官网提交pr

单一职责插件

  • 引入如下依赖:
  1. <dependency>
  2. <groupId>org.apache.shenyu</groupId>
  3. <artifactId>shenyu-plugin-api</artifactId>
  4. <version>${project.version}</version>
  5. </dependency>
  • 用户新增一个类 MyShenyuPlugin,直接实现 org.apache.shenyu.plugin.api.ShenyuPlugin
  1. public interface ShenyuPlugin {
  2. /**
  3. * Process the Web request and (optionally) delegate to the next
  4. * {@code WebFilter} through the given {@link ShenyuPluginChain}.
  5. *
  6. * @param exchange the current server exchange
  7. * @param chain provides a way to delegate to the next filter
  8. * @return {@code Mono<Void>} to indicate when request processing is complete
  9. */
  10. Mono<Void> execute(ServerWebExchange exchange, ShenyuPluginChain chain);
  11. /**
  12. * return plugin order .
  13. * This attribute To determine the plugin execution order in the same type plugin.
  14. *
  15. * @return int order
  16. */
  17. int getOrder();
  18. /**
  19. * acquire plugin name.
  20. * this is plugin name define you must Provide the right name.
  21. * if you impl AbstractShenyuPlugin this attribute not use.
  22. *
  23. * @return plugin name.
  24. */
  25. default String named() {
  26. return "";
  27. }
  28. /**
  29. * plugin is execute.
  30. * if return true this plugin can not execute.
  31. *
  32. * @param exchange the current server exchange
  33. * @return default false.
  34. */
  35. default Boolean skip(ServerWebExchange exchange) {
  36. return false;
  37. }
  38. }
  • 接口方法详细说明

    • execute() 方法为核心的执行方法,用户可以在里面自由的实现自己想要的功能。

    • getOrder() 指定插件的排序。

    • named() 指定插件的名称,命名采用Camel Case,如:dubbospringCloud

    • skip() 在特定的条件下,该插件是否被跳过。

  • 注册成Springbean,参考如下,或者直接在实现类上加 @Component 注解。

  1. @Bean
  2. public ShenyuPlugin myShenyuPlugin() {
  3. return new MyShenyuPlugin();
  4. }

匹配流量处理插件

  • 引入如下依赖:
  1. <dependency>
  2. <groupId>org.apache.shenyu</groupId>
  3. <artifactId>shenyu-plugin-base</artifactId>
  4. <version>${project.version}</version>
  5. </dependency>
  • 新增一个类 CustomPlugin,继承 org.apache.shenyu.plugin.base.AbstractShenyuPlugin

  • 以下是参考:

  1. /**
  2. * This is your custom plugin.
  3. * He is running in after before plugin, implement your own functionality.
  4. * extends AbstractShenyuPlugin so you must user shenyu-admin And add related plug-in development.
  5. *
  6. * @author xiaoyu(Myth)
  7. */
  8. public class CustomPlugin extends AbstractShenyuPlugin {
  9. /**
  10. * return plugin order .
  11. * The same plugin he executes in the same order.
  12. *
  13. * @return int
  14. */
  15. @Override
  16. public int getOrder() {
  17. return 0;
  18. }
  19. /**
  20. * acquire plugin name.
  21. * return you custom plugin name.
  22. * It must be the same name as the plug-in you added in the admin background.
  23. *
  24. * @return plugin name.
  25. */
  26. @Override
  27. public String named() {
  28. return "shenYu";
  29. }
  30. /**
  31. * plugin is execute.
  32. * Do I need to skip.
  33. * if you need skip return true.
  34. *
  35. * @param exchange the current server exchange
  36. * @return default false.
  37. */
  38. @Override
  39. public Boolean skip(final ServerWebExchange exchange) {
  40. return false;
  41. }
  42. /**
  43. * this is Template Method child has Implement your own logic.
  44. *
  45. * @param exchange exchange the current server exchange
  46. * @param chain chain the current chain
  47. * @param selector selector
  48. * @param rule rule
  49. * @return {@code Mono<Void>} to indicate when request handling is complete
  50. */
  51. @Override
  52. protected abstract Mono<Void> doExecute(ServerWebExchange exchange, ShenyuPluginChain chain, SelectorData selector, RuleData rule) {
  53. LOGGER.debug(".......... function plugin start..............");
  54. /*
  55. * Processing after your selector matches the rule.
  56. * rule.getHandle() is you Customize the json string to be processed.
  57. * for this example.
  58. * Convert your custom json string pass to an entity class.
  59. */
  60. final String ruleHandle = rule.getHandle();
  61. final Test test = GsonUtils.getInstance().fromJson(ruleHandle, Test.class);
  62. /*
  63. * Then do your own business processing.
  64. * The last execution chain.execute(exchange).
  65. * Let it continue on the chain until the end.
  66. */
  67. System.out.println(test.toString());
  68. return chain.execute(exchange);
  69. }
  70. }
  • 详细讲解:

    • 继承该类的插件,插件会进行选择器规则匹配。

    • 首先在 shenyu-admin 后台管理系统 —> 基础配置 —> 插件管理 中,新增一个插件,注意 名称与 你自定义插件的 named() 方法要一致。

    • 重新登陆 shenyu-admin 后台,可以看见刚新增的插件,然后就可以进行选择器规则匹配。

    • 在规则中,有个 handler 字段,是自定义处理数据,在 doExecute() 方法中,通过 final String ruleHandle = rule.getHandle(); 获取,然后进行你的操作。

  • 注册成Springbean,参考如下或者直接在实现类上加 @Component 注解。

  1. @Bean
  2. public ShenyuPlugin customPlugin() {
  3. return new CustomPlugin();
  4. }

订阅你的插件数据,进行自定义的处理

  • 新增一个类 PluginDataHandler,实现 org.apache.shenyu.plugin.base.handler.PluginDataHandler
  1. public interface PluginDataHandler {
  2. /**
  3. * Handler plugin.
  4. *
  5. * @param pluginData the plugin data
  6. */
  7. default void handlerPlugin(PluginData pluginData) {
  8. }
  9. /**
  10. * Remove plugin.
  11. *
  12. * @param pluginData the plugin data
  13. */
  14. default void removePlugin(PluginData pluginData) {
  15. }
  16. /**
  17. * Handler selector.
  18. *
  19. * @param selectorData the selector data
  20. */
  21. default void handlerSelector(SelectorData selectorData) {
  22. }
  23. /**
  24. * Remove selector.
  25. *
  26. * @param selectorData the selector data
  27. */
  28. default void removeSelector(SelectorData selectorData) {
  29. }
  30. /**
  31. * Handler rule.
  32. *
  33. * @param ruleData the rule data
  34. */
  35. default void handlerRule(RuleData ruleData) {
  36. }
  37. /**
  38. * Remove rule.
  39. *
  40. * @param ruleData the rule data
  41. */
  42. default void removeRule(RuleData ruleData) {
  43. }
  44. /**
  45. * Plugin named string.
  46. *
  47. * @return the string
  48. */
  49. String pluginNamed();
  50. }
  • 注意 pluginNamed() 要和你自定义的插件名称相同。

  • 注册成Springbean,参考如下或者直接在实现类上加 @Component 注解。

  1. @Bean
  2. public PluginDataHandler pluginDataHandler() {
  3. return new PluginDataHandler();
  4. }

动态加载自定义插件

  • 当使用此功能时候,上述扩展 ShenyuPlugin, PluginDataHandler, 不用成为 spring bean。只需要构建出扩展项目的jar包即可。

  • 使用以下配置:

  1. shenyu:
  2. extPlugin:
  3. path: //加载扩展插件jar包路径
  4. enabled: true //是否开启
  5. threads: 1 //加载插件线程数量
  6. scheduleTime: 300 //间隔时间(单位:秒)
  7. scheduleDelay: 30 //网关启动后延迟多久加载(单位:秒)

插件加载路径详解

  • 此路径是为存放扩展插件jar包的目录。

  • 可以使用 -Dplugin-ext=xxxx 指定,也可以使用 shenyu.extPlugin.path配置文件指定,如果都没配置,默认会加载网关启动路径下的 ext-lib目录。

  • 优先级 :-Dplugin-ext=xxxx > shenyu.extPlugin.path > ext-lib(default)