Dubbo Adaptive机制详解实战

开篇

 本文尝试通过一个示例来讲解Adaptive机制的用法,然后会从源码的角度对其实现原理进行讲解


Adaptive机制

 对应于Adaptive机制,Dubbo提供了一个注解@Adaptive,该注解可以用于接口的某个实现类上,也可以用于接口方法上。如果用在接口的子类上,则表示Adaptive机制的实现会按照该子类的方式进行自定义实现;如果用在方法上,则表示Dubbo会为该接口自动生成一个子类,并且按照一定的格式重写该方法,而其余没有标注@Adaptive注解的方法将会默认抛出异常。

 对于第一种Adaptive的使用方式,Dubbo里只有ExtensionFactory接口使用了,其有一个子类AdaptiveExtensionFactory就使用了@Adaptive注解进行了标注,主要作用就是在获取目标对象时,分别通过ExtensionLoader和Spring容器两种方式获取,主要用在SPI的IOC实现中用于获取上下文的Bean对象。

 对于第二种使用@Adaptive注解标注在接口方法上以实现Adaptive机制的使用原理,通过一个下面的例子进行说明。


用法示例

例子说明

  • 定义PlantsWater的接口并通过@SPI注解进行注解,注解可选择带默认值。
  • 将watering()方法使用@Adaptive注解进行了标注,表示该方法在自动生成的子类中是需要动态实现的方法。
  • 增加grant()方法是为了表明不带@Adaptive在自动生成的子类方法内部会抛出异常。
  • 为PlantsWater增加两个实现,AppleWater和BananaWater,实际调用通过参数控制。
  • 在META-INF/dubbo下创建一个文件,该文件的名称是目标接口的全限定名,这里是org.apache.dubbo.spi.example.PlantsWater,在该文件中需要指定该接口所有可提供服务的子类。
  • 定义主函数ExtensionLoaderDemo模拟SPI调用的验证。
----定义基础应用类

public interface Fruit {}
public class Apple implements Fruit {}
public class Banana implements Fruit{}



----定义SPI类

@SPI("banana")
public interface PlantsWater {

    Fruit grant();

    @Adaptive
    String watering(URL url);
}


public class AppleWater implements PlantsWater {
    public Fruit grant() {
        return new Apple();
    }

    public String watering(URL url) {
        System.out.println("watering apple");
        return "watering finished";
    }
}


public class BananaWater implements PlantsWater {

    public Fruit grant() {
        return new Banana();
    }

    public String watering(URL url) {
        System.out.println("watering banana");
        return "watering success";
    }
}



----resources文件 org.apache.dubbo.spi.example.PlantsWater

apple=org.apache.dubbo.spi.example.AppleWater
banana=org.apache.dubbo.spi.example.BananaWater


------测试代码内容

public class ExtensionLoaderDemo {

    public static void main(String[] args) {
        // 首先创建一个模拟用的URL对象
        URL url = URL.valueOf("dubbo://192.168.0.101:20880?plants.water=apple");
        // 通过ExtensionLoader获取一个PlantsWater对象,getAdaptiveExtension已经加载了所有SPI类
        PlantsWater plantsWater = ExtensionLoader.getExtensionLoader(PlantsWater.class)
                .getAdaptiveExtension();
        // 使用该PlantsWater调用其"自适应标注的"方法,获取调用结果
        String result = plantsWater.watering(url);
        System.out.println(result);
    }
}


-----实际输出内容

十月 11, 2019 7:48:51 下午 org.apache.dubbo.common.logger.LoggerFactory info
信息: using logger: org.apache.dubbo.common.logger.jcl.JclLoggerAdapter
watering apple
watering finished

Process finished with exit code 0

原理补充

  • 这里提供了AppleWater和BananaWater表示的其实是两种基础服务类,本质上它们三者的关系是PlantsWater用于对外提供一个规范,而AppleWater和BananaWater则是实现了这种规范的两种基础服务。至于调用方需要使用哪种基础服务来实现其功能,这就需要根据调用方指定的参数来动态选取的,而@Adaptive机制就是提供了这样一种选取功能。
  • 模拟调用构造了一个URL对象,这个URL对象是Dubbo中进行参数传递所使用的一个基础类,在配置文件中配置的属性都会被封装到该对象中。这里我们主要要注意该对象是通过一个url构造的,并且url的最后我们有一个参数plants.water=apple,这里其实就是我们所指定的使用哪种基础服务类的参数。比如这里指定的就是使用apple对应的AppleWater。
  • ExtensionLoader.getExtensionLoader(PlantsWater.class).getAdaptiveExtension()的过程中会生成PlantsWater类对应的ExtensionLoader,在该Loader里面保存了PlantsWater对应的SPI的各个具体实现类。


PlantsWater$Adaptive

说明:

  • PlantsWater$Adaptive是PlantsWater接口动态生成的子类,通过ExtensionLoader.getAdaptiveExtension()方法动态生成
  • 针对没有@Adaptive修饰的方法,子类中实现的方法体内部直接抛出UnsupportedOperationException。
  • 针对有@Adaptive修饰的方法,子类会重新实现动态获取PlantsWater 实例的方法,ExtensionLoader.getExtensionLoader(PlantsWater.class).getExtension(extName)。
  • 在使用@Adaptive注解标注的方法中,其参数中必须有一个参数类型为URL,或者其某个参数提供了某个方法,该方法可以返回一个URL对象。
  • 在方法的实现中会通过URL对象获取某个参数对应的参数值,如果在接口的@SPI注解中指定了默认值,那么在使用URL对象获取参数值时,如果没有取到,就会使用该默认值。url.getParameter("plants.water", "banana")中plants.water取URL中带的参数,"banana"属于SPI指定的默认值。
  • 根据获取到的参数值,在ExtensionLoader中获取该参数值对应的服务提供类对象(通过ExtensionLoader.getExtensionLoader().getExtension(extName)),然后将真正的调用委托给该服务提供类对象进行。
  • 在通过URL对象获取参数时,参数key获取的对应规则是,首先会从@Adaptive注解的参数值中获取,如果该注解没有指定参数名,那么就会默认将目标接口的类名转换为点分形式作为参数名,比如这里PlantsWater转换为点分形式就是plants.water。
package org.apache.dubbo.spi.example;
import org.apache.dubbo.common.extension.ExtensionLoader;

public class PlantsWater$Adaptive implements org.apache.dubbo.spi.example.PlantsWater {

    public java.lang.String watering(org.apache.dubbo.common.URL arg0)  {
        if (arg0 == null) throw new IllegalArgumentException("url == null");
        
        org.apache.dubbo.common.URL url = arg0;
        String extName = url.getParameter("plants.water", "banana");
        
        if(extName == null) throw new IllegalStateException("Failed to get extension (org.apache.dubbo.spi.example.PlantsWater) name from url (" + url.toString() + ") use keys([plants.water])");
        
        org.apache.dubbo.spi.example.PlantsWater extension = (org.apache.dubbo.spi.example.PlantsWater)ExtensionLoader
                                             .getExtensionLoader(org.apache.dubbo.spi.example.PlantsWater.class)
                                             .getExtension(extName);
        
        return extension.watering(arg0);
    }

    public org.apache.dubbo.spi.example.Fruit grant()  {
        throw new UnsupportedOperationException("The method public abstract org.apache.dubbo.spi.example.Fruit org.apache.dubbo.spi.example.PlantsWater.grant() of interface org.apache.dubbo.spi.example.PlantsWater is not adaptive method!");
    }
}


实现原理

Dubbo Adaptive的实现机制根据上面的讲解其实步骤已经比较清晰了,主要分为如下三个步骤:

  • 1、加载标注有@Adaptive注解的接口,如果不存在,则不支持Adaptive机制;
  • 2、为目标接口按照一定的模板生成子类代码,并且编译生成的代码,然后通过反射生成该类的对象;
  • 3、结合生成的对象实例,通过传入的URL对象,获取指定key的配置,然后加载该key对应的类对象,最终将调用委托给该类对象进行。

可以看到,通过这种方式,Dubbo就实现了一种通过配置参数动态选择所使用的服务的目的,而实现这种机制的入口主要在ExtensionLoader.getAdaptiveExtension()方法

public class ExtensionLoaderDemo {

    public static void main(String[] args) {
        // 首先创建一个模拟用的URL对象
        URL url = URL.valueOf("dubbo://192.168.0.101:20880?plants.water=apple");
        // 通过ExtensionLoader获取一个FruitGranter对象
        PlantsWater plantsWater = ExtensionLoader.getExtensionLoader(PlantsWater.class)
                .getAdaptiveExtension();
        // 使用该FruitGranter调用其"自适应标注的"方法,获取调用结果
        String result = plantsWater.watering(url);
        System.out.println(result);
    }
}

说明:

  • 上面的代码作为整个动态生成代码的入口,关注ExtensionLoader.getExtensionLoader(PlantsWater.class)
    .getAdaptiveExtension()就可以了。


public T getAdaptiveExtension() {
  Object instance = cachedAdaptiveInstance.get();
  if (instance == null) {
    if (createAdaptiveInstanceError == null) {
      synchronized (cachedAdaptiveInstance) {
        instance = cachedAdaptiveInstance.get();
        if (instance == null) {
          try {
            // 创建Adaptive实例
            instance = createAdaptiveExtension();
            cachedAdaptiveInstance.set(instance);
          } catch (Throwable t) {
            createAdaptiveInstanceError = t;
            throw new IllegalStateException("Failed to create adaptive " 
                + "instance: " + t.toString(), t);
          }
        }
      }
    } else {
      throw new IllegalStateException("Failed to create adaptive instance: " 
          + createAdaptiveInstanceError.toString(), createAdaptiveInstanceError);
    }
  }

  return (T) instance;
}

说明:
上面的代码首先通过双检查法来从缓存中获取Adaptive实例,如果没获取到,则创建一个。我们这里继续看createAdaptiveExtension()方法的实现。


    private T createAdaptiveExtension() {
        try {
            return injectExtension((T) getAdaptiveExtensionClass().newInstance());
        } catch (Exception e) {
            throw new IllegalStateException("Can't create adaptive extension " + type + ", cause: " + e.getMessage(), e);
        }
    }

说明:
上面代码是创建Adaptive实例的方法是一个主干方法,从这里调用方法的顺序就可以看出其主要作用:

  • 获取一个Adaptive类的class对象,不存在则创建一个,该方法会保证一定存在一个该class对象;
  • 通过反射创建一个Adaptive类的实例;
  • 对创建的Adaptive注入相关属性,需要注意的是,Dubbo目前只支持通过setter方法注入属性。


    private Class<?> getAdaptiveExtensionClass() {

  // 通过读取Dubbo的配置文件,获取其中的SPI类,其主要处理了四部分的类:
  // 1. 标注了@Activate注解的类,该注解的主要作用是将某个实现子类标注为自动激活,也就是在加载
  //    实例的时候也会加载该类的对象;

  // 2. 记录目标接口是否标注了@Adaptive注解,如果标注了该注解,则表示需要为该接口动态生成子类,或者说
  //    目标接口是否存在标注了@Adaptive注解的子类,如果存在,则直接使用该子类作为Adaptive类;
  
  // 3. 检查加载到的类是否包含有传入目标接口参数的构造方法,如果是,则表示该类是一个代理类,也可以
  //    将其理解为最终会被作为责任链进行调用的类,这些类最终会在目标类被调用的时候以类似于AOP的方式,
  //    将目标类包裹起来,然后将包裹之后的类对外提供服务;

  // 4. 剩余的一般类就是实现了目标接口,并且作为基础服务提供的类。

        getExtensionClasses();



  // 经过上面的类加载过程,如果目标接口某个子类存在@Adaptive注解,就会将其class对象缓存到
  // cachedAdaptiveClass对象中。这里我们就可以看到@Adaptive注解的两种使用方式的分界点,也就是说,
  // 如果某个子类标注了@Adaptive注解,那么就会使用该子类所自定义的Adaptive机制,如果没有子类标注了
  // 该注解,那么就会使用下面的createAdaptiveExtensionClass()方式来创建一个目标类class对象
        if (cachedAdaptiveClass != null) {
            return cachedAdaptiveClass;
        }

  // 创建一个目标接口的子类class对象
        return cachedAdaptiveClass = createAdaptiveExtensionClass();
    }


    private Class<?> createAdaptiveExtensionClass() {
  // 为目标接口生成子类代码,以字符串形式表示
        String code = new AdaptiveClassCodeGenerator(type, cachedDefaultName).generate();

  // 获取classloader
        ClassLoader classLoader = findClassLoader();

  // 通过jdk或者javassist的方式编译生成的子类字符串(默认是javassist),从而得到一个class对象
        org.apache.dubbo.common.compiler.Compiler compiler = ExtensionLoader.getExtensionLoader(org.apache.dubbo.common.compiler.Compiler.class).getAdaptiveExtension();
        return compiler.compile(code, classLoader);
    }

说明:
上面的代码中主要是一个骨架代码,首先通过getExtensionClasses()获取配置文件中配置的各个类对象,其加载的原理可阅读文章Dubbo之SPI原理详解;加载完成后,会通过AdaptiveClassCodeGenerator来为目标类生成子类代码,并以字符串的形式返回,最后通过javassist或jdk的方式进行编译然后返回class对象。这里我们主要阅读AdaptiveClassCodeGenerator.generate()方法是如何生成目标接口的子类的。


   public String generate() {
        //判断目标接口是否有方法标注了@Adaptive注解,如果没有则抛出异常
        if (!hasAdaptiveMethod()) {
            throw new IllegalStateException("No adaptive method exist on extension " + type.getName() + ", refuse to create the adaptive class!");
        }

        StringBuilder code = new StringBuilder();
        code.append(generatePackageInfo()); // 生成package信息
        code.append(generateImports()); // 生成import信息,这里只导入了ExtensionLoader类,其余的类都通过全限定名的方式来使用
        code.append(generateClassDeclaration()); // 生成类声明信息
        
        Method[] methods = type.getMethods();
        for (Method method : methods) {
            code.append(generateMethod(method)); // 为各个方法生成实现方法信息
        }
        code.append("}");
        
        if (logger.isDebugEnabled()) {
            logger.debug(code.toString());
        }
        return code.toString(); // 返回生成的class代码
    }

说明:
上面代码的generate()方法是生成目标类的主干方法,其主要分为如下几个步骤:

  • 生成package信息;
  • 生成import信息;
  • 生成类声明信息;
  • 生成各个方法的实现;
    前面几个步骤实现原理都相较比较简单,继续阅读generateMethod()方法的实现原理。


    private String generateMethod(Method method) {
        String methodReturnType = method.getReturnType().getCanonicalName(); // 生成返回值信息
        String methodName = method.getName(); // 生成方法名信息
        String methodContent = generateMethodContent(method); // 生成方法体信息
        String methodArgs = generateMethodArguments(method); // 生成方法参数信息
        String methodThrows = generateMethodThrows(method); // 生成异常信息
        return String.format(CODE_METHOD_DECLARATION, methodReturnType, methodName, methodArgs, methodThrows, methodContent); // 对方法进行格式化返回
    }

说明:
上面代码的方法的生成,也拆分成了几个子步骤,主要包括:

  • 生成返回值信息;
  • 生成方法名信息;
  • 生成方法参数信息;
  • 生成方法的异常信息;
  • 生成方法体信息;
    需要注意的是,这里所使用的所有类都是使用的其全限定类名,通过前面我们展示的PlantsWater的子类代码也可以看出这一点。上面生成的信息中,方法的返回值,方法名,方法参数以及异常信息都可以通过接口声明获取到,而方法体则需要根据一定的逻辑来生成。关于方法参数,需要说明的是,Dubbo并没有使用接口中对应参数的名称,而是对每一个参数的参数名依次使用arg0、arg1等名称。这里我们继续阅读Dubbo生成方法体内容的代码。


    private String generateMethodContent(Method method) {

        // 获取方法上标注的@Adaptive注解,前面讲到,Dubbo会使用该注解的值作为动态参数的key值
        Adaptive adaptiveAnnotation = method.getAnnotation(Adaptive.class);
        StringBuilder code = new StringBuilder(512);

        // 如果当前方法没有标注@Adaptive注解,该方法的实现就会默认抛出异常
        if (adaptiveAnnotation == null) {
            return generateUnsupported(method);
        } else {

            // 获取参数中类型为URL的参数所在的参数索引位置,因为我们的参数都是通过arg[i]的形式编排的,因而
            // 获取其索引就可以得到该参数的引用。这里URL参数的主要作用是获取目标参数对应的参数值
            int urlTypeIndex = getUrlTypeIndex(method);
            
            if (urlTypeIndex != -1) {
                // 如果参数中存在URL类型的参数,那么就为该参数进行空值检查,如果为空,则抛出异常
                code.append(generateUrlNullCheck(urlTypeIndex));
            } else {
                // 如果参数中不存在URL类型的参数,那么就会检查每个参数,判断其是否有某个方法的返回值是URL类型,
                // 如果存在该方法,则首先对该参数进行空指针检查,如果为空则抛出异常。然后调用该对象的目标方法,
                // 以获取到一个URL对象,然后对获取到的URL对象进行空值检查,为空也会抛出异常。
                code.append(generateUrlAssignmentIndirectly(method));
            }

            // 这里主要是获取@Adaptive注解的参数,如果没有配置,就会使用目标接口的类型由驼峰形式转换为点分形式
            // 的名称作为将要获取的参数值的key名称,比如前面的PlantsWater转换后为plants.water。
            // 这里需要注意的是,返回值是一个数组类型,这是因为Dubbo会通过嵌套获取的方式来的到目标参数,
            // 比如我们使用了@Adaptive({"client", "transporter"})的形式,那么最终就会在URL对象中获取两次
            // 参数,如String extName = url.getParameter("client", url.getParameter("transporter"))
            String[] value = getMethodAdaptiveValue(adaptiveAnnotation);

            // 判断是否存在Invocation类型的参数
            boolean hasInvocation = hasInvocationArgument(method);
            
            // 为Invocation类型的参数添加空值检查的逻辑
            code.append(generateInvocationArgumentNullCheck(method));
            
            // 生成获取extName的逻辑,也即前面通过String[] value生成的通过url.getParameter()的
            // 逻辑代码,最终会得到用户配置的扩展的名称,从而对应某个基础服务类
            code.append(generateExtNameAssignment(value, hasInvocation));

            // 为extName添加空值检查代码
            code.append(generateExtNameNullCheck(value));
            
            // 通过extName在ExtensionLoader中获取其对应的基础服务类,比如前面的PlantsWater,在这里就是
            // PlantsWater extension = ExtensionLoader.getExtensionLoader(ExtensionLoader.class)
            // .getExtension(extName),这样就得到了一个PlantsWater的实例对象
            code.append(generateExtensionAssignment());

            // 生成目标实例的当前方法的调用逻辑,然后将结果返回。比如PlantsWater就是
            // return extension.watering(arg0);
            // 这里方法名就是当前实现的方法的名称,而参数就是当前方法传入的参数,
            // 就是目标接口中的同一方法,而方法参数前面已经讲到,都是使用arg[i]的形式命名的,因而这里直接
            // 将其依次罗列出来即可
            code.append(generateReturnAndInvocation(method));
        }
        
        // 将生成的代码返回
        return code.toString();
    }

说明:
上面的逻辑主要分为了如下几个步骤:

  • 判断当前方法是否标注了@Adaptive注解,如果没有标注,则为其生成一个默认实现,该实现中会默认抛出异常,也就是说只有使用@Adaptive注解标注的方法才是作为自适应机制的方法;
  • 获取方法参数中类型为URL的参数,如果不存在,则获取参数中某个存在可以返回URL类型对象的方法的参数,并且调用该方法获取URL参数;
  • 通过@Adaptive注解的配置获取目标参数的key值,然后通过前面得到的URL参数获取该key对应的参数值,从而得到了基础服务类对应的名称;
  • 通过ExtensionLoader获取该名称对应的基础服务类实例;
  • 通过调用基础服务类的实例的当前方法来实现最终的基础服务。

    可以看到,这里实现的自适应机制逻辑结构是非常清晰的,读者通过阅读这里的源码也就比较好的理解了Dubbo所提供的自适应机制的原理,也能够比较好的通过自适应机制来完成某些定制化的工作。


参考

Dubbo Adaptive机制详解

上一篇:ice v1.18.3更新 (改进插件情况、修复编码模块错误)


下一篇:Java容器使用总结