java SPI 05-dubbo adaptive extension 自适应拓展

逃离我推掉我的手 2023-02-19 02:29 24阅读 0赞

## 系列目录 ##

[spi 01-spi 是什么？入门使用][spi 01-spi]

[spi 02-spi 的实战解决 slf4j 包冲突问题][spi 02-spi _ slf4j]

[spi 03-spi jdk 实现源码解析][spi 03-spi jdk]

[spi 04-spi dubbo 实现源码解析][spi 04-spi dubbo]

[spi 05-dubbo adaptive extension 自适应拓展][spi 05-dubbo adaptive extension]

[spi 06-自己从零手写实现 SPI 框架][spi 06-_ SPI]

[spi 07-自动生成 SPI 配置文件实现方式][spi 07-_ SPI]

## dubbo 自适应拓展 ##

### 原理 ###

在 Dubbo 中，很多拓展都是通过 SPI 机制进行加载的，比如 Protocol、Cluster、LoadBalance 等。

有时，有些拓展并不想在框架启动阶段被加载，而是希望在拓展方法被调用时，根据运行时参数进行加载。

这听起来有些矛盾。拓展未被加载，那么拓展方法就无法被调用（静态方法除外）。拓展方法未被调用，拓展就无法被加载。

对于这个矛盾的问题，Dubbo 通过自适应拓展机制很好的解决了。自适应拓展机制的实现逻辑比较复杂，首先 Dubbo 会为拓展接口生成具有代理功能的代码。然后通过 javassist 或 jdk 编译这段代码，得到 Class 类。最后再通过反射创建代理类，整个过程比较复杂。

### 例子 ###

为了让大家对自适应拓展有一个感性的认识，下面我们通过一个示例进行演示。这是一个与汽车相关的例子，我们有一个车轮制造厂接口 WheelMaker：

public interface WheelMaker { 
        Wheel makeWheel(URL url);
    }

WheelMaker 接口的自适应实现类如下：

public class AdaptiveWheelMaker implements WheelMaker { 
        public Wheel makeWheel(URL url) { 
            if (url == null) { 
                throw new IllegalArgumentException("url == null");
            }
            
        	// 1.从 URL 中获取 WheelMaker 名称
            String wheelMakerName = url.getParameter("Wheel.maker");
            if (wheelMakerName == null) { 
                throw new IllegalArgumentException("wheelMakerName == null");
            }
            
            // 2.通过 SPI 加载具体的 WheelMaker
            WheelMaker wheelMaker = ExtensionLoader
                .getExtensionLoader(WheelMaker.class).getExtension(wheelMakerName);
            
            // 3.调用目标方法
            return wheelMaker.makeWheel(url);
        }
    }

AdaptiveWheelMaker 是一个代理类，与传统的代理逻辑不同，AdaptiveWheelMaker 所代理的对象是在 makeWheel 方法中通过 SPI 加载得到的。

makeWheel 方法主要做了三件事情：

1.  从 URL 中获取 WheelMaker 名称
2.  通过 SPI 加载具体的 WheelMaker 实现类
3.  调用目标方法

接下来，我们来看看汽车制造厂 CarMaker 接口与其实现类。

public interface CarMaker { 
        Car makeCar(URL url);
    }
    
    public class RaceCarMaker implements CarMaker { 
        WheelMaker wheelMaker;
     
        // 通过 setter 注入 AdaptiveWheelMaker
        public setWheelMaker(WheelMaker wheelMaker) { 
            this.wheelMaker = wheelMaker;
        }
     
        public Car makeCar(URL url) { 
            Wheel wheel = wheelMaker.makeWheel(url);
            return new RaceCar(wheel, ...);
        }
    }

RaceCarMaker 持有一个 WheelMaker 类型的成员变量，在程序启动时，我们可以将 AdaptiveWheelMaker 通过 setter 方法注入到 RaceCarMaker 中。

在运行时，假设有这样一个 url 参数传入：

dubbo://192.168.0.101:20880/XxxService?wheel.maker=MichelinWheelMaker

RaceCarMaker 的 makeCar 方法将上面的 url 作为参数传给 AdaptiveWheelMaker 的 makeWheel 方法，makeWheel 方法从 url 中提取 wheel.maker 参数，得到 MichelinWheelMaker。之后再通过 SPI 加载配置名为 MichelinWheelMaker 的实现类，得到具体的 WheelMaker 实例。

上面的示例展示了自适应拓展类的核心实现 ---- 在拓展接口的方法被调用时，通过 SPI 加载具体的拓展实现类，并调用拓展对象的同名方法。

接下来，我们深入到源码中，探索自适应拓展类生成的过程。

## 源码分析 ##

在对自适应拓展生成过程进行深入分析之前，我们先来看一下与自适应拓展息息相关的一个注解，即 Adaptive 注解。

该注解的定义如下：

@Documented
    @Retention(RetentionPolicy.RUNTIME)
    @Target({ ElementType.TYPE, ElementType.METHOD})
    public @interface Adaptive { 
        String[] value() default { };
    }

从上面的代码中可知，Adaptive 可注解在类或方法上。

当 Adaptive 注解在类上时，Dubbo 不会为该类生成代理类。

注解在方法（接口方法）上时，Dubbo 则会为该方法生成代理逻辑。

Adaptive 注解在类上的情况很少，在 Dubbo 中，仅有两个类被 Adaptive 注解了，分别是 AdaptiveCompiler 和 AdaptiveExtensionFactory。

此种情况，表示拓展的加载逻辑由人工编码完成。

更多时候，Adaptive 是注解在接口方法上的，表示拓展的加载逻辑需由框架自动生成。

Adaptive 注解的地方不同，相应的处理逻辑也是不同的。

注解在类上时，处理逻辑比较简单，本文就不分析了。注解在接口方法上时，处理逻辑较为复杂，本章将会重点分析此块逻辑。

### 获取自适应拓展 ###

getAdaptiveExtension 方法是获取自适应拓展的入口方法，因此下面我们从这个方法进行分析。

相关代码如下：

// 通过反射获取所有的方法
    Method[] methods = type.getMethods();
    boolean hasAdaptiveAnnotation = false;
    // 遍历方法列表
    for (Method m : methods) { 
        // 检测方法上是否有 Adaptive 注解
        if (m.isAnnotationPresent(Adaptive.class)) { 
            hasAdaptiveAnnotation = true;
            break;
        }
    }
    
    if (!hasAdaptiveAnnotation)
        // 若所有的方法上均无 Adaptive 注解，则抛出异常
        throw new IllegalStateException("No adaptive method on extension ...");

### 生成类 ###

通过 Adaptive 注解检测后，即可开始生成代码。

代码生成的顺序与 Java 文件内容顺序一致，首先会生成 package 语句，然后生成 import 语句，紧接着生成类名等代码。

整个逻辑如下：

// 生成 package 代码：package + type 所在包
    codeBuilder.append("package ").append(type.getPackage().getName()).append(";");
    // 生成 import 代码：import + ExtensionLoader 全限定名
    codeBuilder.append("\nimport ").append(ExtensionLoader.class.getName()).append(";");
    // 生成类代码：public class + type简单名称 + $Adaptive + implements + type全限定名 + { 
    codeBuilder.append("\npublic class ")
        .append(type.getSimpleName())
        .append("$Adaptive")
        .append(" implements ")
        .append(type.getCanonicalName())
        .append(" {");
    
    // ${生成方法}
    
    codeBuilder.append("\n}");

这里使用 `${...}` 占位符代表其他代码的生成逻辑，该部分逻辑将在随后进行分析。

上面代码不是很难理解，下面直接通过一个例子展示该段代码所生成的内容。

以 Dubbo 的 Protocol 接口为例，生成的代码如下：

package com.alibaba.dubbo.rpc;
    import com.alibaba.dubbo.common.extension.ExtensionLoader;
    public class Protocol$Adaptive implements com.alibaba.dubbo.rpc.Protocol { 
        // 省略方法代码
    }

### 生成方法 ###

一个方法可以被 Adaptive 注解修饰，也可以不被修饰。

这里将未被 Adaptive 注解修饰的方法称为“无 Adaptive 注解方法”，下面我们先来看看此种方法的代码生成逻辑是怎样的。

#### 无 Adaptive 注解方法代码生成逻辑 ####

对于接口方法，我们可以按照需求标注 Adaptive 注解。

以 Protocol 接口为例，该接口的 destroy 和 getDefaultPort 未标注 Adaptive 注解，其他方法均标注了 Adaptive 注解。

Dubbo 不会为没有标注 Adaptive 注解的方法生成代理逻辑，对于该种类型的方法，仅会生成一句抛出异常的代码。

生成逻辑如下：

for (Method method : methods) { 
        
        // 省略无关逻辑
    
        Adaptive adaptiveAnnotation = method.getAnnotation(Adaptive.class);
        StringBuilder code = new StringBuilder(512);
        // 如果方法上无 Adaptive 注解，则生成 throw new UnsupportedOperationException(...) 代码
        if (adaptiveAnnotation == null) { 
            // 生成的代码格式如下：
            // throw new UnsupportedOperationException(
            // "method " + 方法签名 + of interface + 全限定接口名 + is not adaptive method!”)
            code.append("throw new UnsupportedOperationException(\"method ")
                .append(method.toString()).append(" of interface ")
                .append(type.getName()).append(" is not adaptive method!\");");
        } else { 
            // 省略无关逻辑
        }
        
        // 省略无关逻辑
    }

以 Protocol 接口的 destroy 方法为例，上面代码生成的内容如下：

throw new UnsupportedOperationException(
                "method public abstract void com.alibaba.dubbo.rpc.Protocol.destroy() of interface com.alibaba.dubbo.rpc.Protocol is not adaptive method!");

#### 获取 URL 数据 ####

前面说过方法代理逻辑会从 URL 中提取目标拓展的名称，因此代码生成逻辑的一个重要的任务是从方法的参数列表或者其他参数中获取 URL 数据。

举例说明一下，我们要为 Protocol 接口的 refer 和 export 方法生成代理逻辑。

在运行时，通过反射得到的方法定义大致如下：

Invoker refer(Class<T> arg0, URL arg1) throws RpcException;
    Exporter export(Invoker<T> arg0) throws RpcException;

对于 refer 方法，通过遍历 refer 的参数列表即可获取 URL 数据，这个还比较简单。

对于 export 方法，获取 URL 数据则要麻烦一些。export 参数列表中没有 URL 参数，因此需要从 Invoker 参数中获取 URL 数据。

获取方式是调用 Invoker 中可返回 URL 的 getter 方法，比如 getUrl。如果 Invoker 中无相关 getter 方法，此时则会抛出异常。

整个逻辑如下：

for (Method method : methods) { 
        Class<?> rt = method.getReturnType();
        Class<?>[] pts = method.getParameterTypes();
        Class<?>[] ets = method.getExceptionTypes();
    
        Adaptive adaptiveAnnotation = method.getAnnotation(Adaptive.class);
        StringBuilder code = new StringBuilder(512);
        if (adaptiveAnnotation == null) { 
            // ${无 Adaptive 注解方法代码生成逻辑}
        } else { 
        	int urlTypeIndex = -1;
            // 遍历参数列表，确定 URL 参数位置
            for (int i = 0; i < pts.length; ++i) { 
                if (pts[i].equals(URL.class)) { 
                    urlTypeIndex = i;
                    break;
                }
            }
            
            // urlTypeIndex != -1，表示参数列表中存在 URL 参数
            if (urlTypeIndex != -1) { 
                // 为 URL 类型参数生成判空代码，格式如下：
                // if (arg + urlTypeIndex == null) 
                // throw new IllegalArgumentException("url == null");
                String s = String.format("\nif (arg%d == null) throw new IllegalArgumentException(\"url == null\");",
                                         urlTypeIndex);
                code.append(s);
    
                // 为 URL 类型参数生成赋值代码，形如 URL url = arg1
                s = String.format("\n%s url = arg%d;", URL.class.getName(), urlTypeIndex);
                code.append(s);
                
            // 参数列表中不存在 URL 类型参数
            } else { 
                String attribMethod = null;
    
                LBL_PTS:
                // 遍历方法的参数类型列表
                for (int i = 0; i < pts.length; ++i) { 
                    // 获取某一类型参数的全部方法
                    Method[] ms = pts[i].getMethods();
                    // 遍历方法列表，寻找可返回 URL 的 getter 方法
                    for (Method m : ms) { 
                        String name = m.getName();
                        // 1. 方法名以 get 开头，或方法名大于3个字符
                        // 2. 方法的访问权限为 public
                        // 3. 非静态方法
                        // 4. 方法参数数量为0
                        // 5. 方法返回值类型为 URL
                        if ((name.startsWith("get") || name.length() > 3)
                            && Modifier.isPublic(m.getModifiers())
                            && !Modifier.isStatic(m.getModifiers())
                            && m.getParameterTypes().length == 0
                            && m.getReturnType() == URL.class) { 
                            urlTypeIndex = i;
                            attribMethod = name;
                            
                            // 结束 for (int i = 0; i < pts.length; ++i) 循环
                            break LBL_PTS;
                        }
                    }
                }
                if (attribMethod == null) { 
                    // 如果所有参数中均不包含可返回 URL 的 getter 方法，则抛出异常
                    throw new IllegalStateException("fail to create adaptive class for interface ...");
                }
    
                // 为可返回 URL 的参数生成判空代码，格式如下：
                // if (arg + urlTypeIndex == null) 
                // throw new IllegalArgumentException("参数全限定名 + argument == null");
                String s = String.format("\nif (arg%d == null) throw new IllegalArgumentException(\"%s argument == null\");",
                                         urlTypeIndex, pts[urlTypeIndex].getName());
                code.append(s);
    
                // 为 getter 方法返回的 URL 生成判空代码，格式如下：
                // if (argN.getter方法名() == null) 
                // throw new IllegalArgumentException(参数全限定名 + argument getUrl() == null);
                s = String.format("\nif (arg%d.%s() == null) throw new IllegalArgumentException(\"%s argument %s() == null\");",
                                  urlTypeIndex, attribMethod, pts[urlTypeIndex].getName(), attribMethod);
                code.append(s);
    
                // 生成赋值语句，格式如下：
                // URL全限定名 url = argN.getter方法名()，比如 
                // com.alibaba.dubbo.common.URL url = invoker.getUrl();
                s = String.format("%s url = arg%d.%s();", URL.class.getName(), urlTypeIndex, attribMethod);
                code.append(s);
            }
            
            // 省略无关代码
        }
        
        // 省略无关代码
    }

上面代码有点多，需要耐心看一下。

这段代码主要目的是为了获取 URL 数据，并为之生成判空和赋值代码。

以 Protocol 的 refer 和 export 方法为例，上面的代码为它们生成如下内容（代码已格式化）：

refer:
    if (arg1 == null) 
        throw new IllegalArgumentException("url == null");
    com.alibaba.dubbo.common.URL url = arg1;
    
    export:
    if (arg0 == null) 
        throw new IllegalArgumentException("com.alibaba.dubbo.rpc.Invoker argument == null");
    if (arg0.getUrl() == null) 
        throw new IllegalArgumentException("com.alibaba.dubbo.rpc.Invoker argument getUrl() == null");
    com.alibaba.dubbo.common.URL url = arg0.getUrl();

#### 获取 Adaptive 注解值 ####

Adaptive 注解值 value 类型为 String\[\]，可填写多个值，默认情况下为空数组。

若 value 为非空数组，直接获取数组内容即可。若 value 为空数组，则需进行额外处理。

处理过程是将类名转换为字符数组，然后遍历字符数组，并将字符放入 StringBuilder 中。

若字符为大写字母，则向 StringBuilder 中添加点号，随后将字符变为小写存入 StringBuilder 中。

比如 LoadBalance 经过处理后，得到 load.balance。

#### 检测 Invocation 参数 ####

此段逻辑是检测方法列表中是否存在 Invocation 类型的参数，若存在，则为其生成判空代码和其他一些代码。

相应的逻辑如下：

for (Method method : methods) { 
        Class<?> rt = method.getReturnType();
        Class<?>[] pts = method.getParameterTypes();    // 获取参数类型列表
        Class<?>[] ets = method.getExceptionTypes();
    
        Adaptive adaptiveAnnotation = method.getAnnotation(Adaptive.class);
        StringBuilder code = new StringBuilder(512);
        if (adaptiveAnnotation == null) { 
            // ${无 Adaptive 注解方法代码生成逻辑}
        } else { 
            // ${获取 URL 数据}
            
            // ${获取 Adaptive 注解值}
            
            boolean hasInvocation = false;
            // 遍历参数类型列表
            for (int i = 0; i < pts.length; ++i) { 
                // 判断当前参数名称是否等于 com.alibaba.dubbo.rpc.Invocation
                if (pts[i].getName().equals("com.alibaba.dubbo.rpc.Invocation")) { 
                    // 为 Invocation 类型参数生成判空代码
                    String s = String.format("\nif (arg%d == null) throw new IllegalArgumentException(\"invocation == null\");", i);
                    code.append(s);
                    // 生成 getMethodName 方法调用代码，格式为：
                    // String methodName = argN.getMethodName();
                    s = String.format("\nString methodName = arg%d.getMethodName();", i);
                    code.append(s);
                    
                    // 设置 hasInvocation 为 true
                    hasInvocation = true;
                    break;
                }
            }
        }
        
        // 省略无关逻辑
    }

#### 生成拓展名获取逻辑 ####

本段逻辑用于根据 SPI 和 Adaptive 注解值生成“获取拓展名逻辑”，同时生成逻辑也受 Invocation 类型参数影响，综合因素导致本段逻辑相对复杂。

本段逻辑可能会生成但不限于下面的代码：

String extName = (url.getProtocol() == null ? "dubbo" : url.getProtocol());

String extName = url.getMethodParameter(methodName, "loadbalance", "random");

String extName = url.getParameter("client", url.getParameter("transporter", "netty"));

本段逻辑复杂之处在于条件分支比较多，大家在阅读源码时需要知道每个条件分支的意义是什么，否则不太容易看懂相关代码。

下面开始分析本段逻辑。

for (Method method : methods) { 
        Class<?> rt = method.getReturnType();
        Class<?>[] pts = method.getParameterTypes();
        Class<?>[] ets = method.getExceptionTypes();
    
        Adaptive adaptiveAnnotation = method.getAnnotation(Adaptive.class);
        StringBuilder code = new StringBuilder(512);
        if (adaptiveAnnotation == null) { 
            // $无 Adaptive 注解方法代码生成逻辑}
        } else { 
            // ${获取 URL 数据}
            
            // ${获取 Adaptive 注解值}
            
            // ${检测 Invocation 参数}
            
            // 设置默认拓展名，cachedDefaultName 源于 SPI 注解值，默认情况下，
            // SPI 注解值为空串，此时 cachedDefaultName = null
            String defaultExtName = cachedDefaultName;
            String getNameCode = null;
            
            // 遍历 value，这里的 value 是 Adaptive 的注解值，2.2.3.3 节分析过 value 变量的获取过程。
            // 此处循环目的是生成从 URL 中获取拓展名的代码，生成的代码会赋值给 getNameCode 变量。注意这
            // 个循环的遍历顺序是由后向前遍历的。
            for (int i = value.length - 1; i >= 0; --i) { 
                // 当 i 为最后一个元素的坐标时
                if (i == value.length - 1) { 
                    // 默认拓展名非空
                    if (null != defaultExtName) { 
                        // protocol 是 url 的一部分，可通过 getProtocol 方法获取，其他的则是从
                        // URL 参数中获取。因为获取方式不同，所以这里要判断 value[i] 是否为 protocol
                        if (!"protocol".equals(value[i]))
                        	// hasInvocation 用于标识方法参数列表中是否有 Invocation 类型参数
                            if (hasInvocation)
                                // 生成的代码功能等价于下面的代码：
                                // url.getMethodParameter(methodName, value[i], defaultExtName)
                                // 以 LoadBalance 接口的 select 方法为例，最终生成的代码如下：
                                // url.getMethodParameter(methodName, "loadbalance", "random")
                                getNameCode = String.format("url.getMethodParameter(methodName, \"%s\", \"%s\")", value[i], defaultExtName);
                        	else
                        		// 生成的代码功能等价于下面的代码：
    	                        // url.getParameter(value[i], defaultExtName)
    	                        getNameCode = String.format("url.getParameter(\"%s\", \"%s\")", value[i], defaultExtName);
                        else
                        	// 生成的代码功能等价于下面的代码：
                            // ( url.getProtocol() == null ? defaultExtName : url.getProtocol() )
                            getNameCode = String.format("( url.getProtocol() == null ? \"%s\" : url.getProtocol() )", defaultExtName);
                        
                    // 默认拓展名为空
                    } else { 
                        if (!"protocol".equals(value[i]))
                            if (hasInvocation)
                            	// 生成代码格式同上
                                getNameCode = String.format("url.getMethodParameter(methodName, \"%s\", \"%s\")", value[i], defaultExtName);
    	                    else
    	                    	// 生成的代码功能等价于下面的代码：
    	                        // url.getParameter(value[i])
    	                        getNameCode = String.format("url.getParameter(\"%s\")", value[i]);
                        else
                        	// 生成从 url 中获取协议的代码，比如 "dubbo"
                            getNameCode = "url.getProtocol()";
                    }
                } else { 
                    if (!"protocol".equals(value[i]))
                        if (hasInvocation)
                            // 生成代码格式同上
                            getNameCode = String.format("url.getMethodParameter(methodName, \"%s\", \"%s\")", value[i], defaultExtName);
    	                else
    	                	// 生成的代码功能等价于下面的代码：
    	                    // url.getParameter(value[i], getNameCode)
    	                    // 以 Transporter 接口的 connect 方法为例，最终生成的代码如下：
    	                    // url.getParameter("client", url.getParameter("transporter", "netty"))
    	                    getNameCode = String.format("url.getParameter(\"%s\", %s)", value[i], getNameCode);
                    else
                        // 生成的代码功能等价于下面的代码：
                        // url.getProtocol() == null ? getNameCode : url.getProtocol()
                        // 以 Protocol 接口的 connect 方法为例，最终生成的代码如下：
                        // url.getProtocol() == null ? "dubbo" : url.getProtocol()
                        getNameCode = String.format("url.getProtocol() == null ? (%s) : url.getProtocol()", getNameCode);
                }
            }
            // 生成 extName 赋值代码
            code.append("\nString extName = ").append(getNameCode).append(";");
            // 生成 extName 判空代码
            String s = String.format("\nif(extName == null) " +
                                     "throw new IllegalStateException(\"Fail to get extension(%s) name from url(\" + url.toString() + \") use keys(%s)\");",
                                     type.getName(), Arrays.toString(value));
            code.append(s);
        }
        
        // 省略无关逻辑
    }

上面代码比较复杂，不是很好理解。

对于这段代码，建议大家写点测试用例，对 Protocol、LoadBalance 以及 Transporter 等接口的自适应拓展类代码生成过程进行调试。

这里我以 Transporter 接口的自适应拓展类代码生成过程举例说明。

首先看一下 Transporter 接口的定义，如下：

@SPI("netty")
    public interface Transporter { 
    	// @Adaptive({server, transporter})
        @Adaptive({ Constants.SERVER_KEY, Constants.TRANSPORTER_KEY}) 
        Server bind(URL url, ChannelHandler handler) throws RemotingException;
    
        // @Adaptive({client, transporter})
        @Adaptive({ Constants.CLIENT_KEY, Constants.TRANSPORTER_KEY})
        Client connect(URL url, ChannelHandler handler) throws RemotingException;
    }

下面对 connect 方法代理逻辑生成的过程进行分析，此时生成代理逻辑所用到的变量如下：

String defaultExtName = "netty";
    boolean hasInvocation = false;
    String getNameCode = null;
    String[] value = ["client", "transporter"];

下面对 value 数组进行遍历，此时 i = 1, value\[i\] = “transporter”，生成的代码如下：

getNameCode = url.getParameter("transporter", "netty");

接下来，for 循环继续执行，此时 i = 0, value\[i\] = “client”，生成的代码如下：

getNameCode = url.getParameter("client", url.getParameter("transporter", "netty"));

for 循环结束运行，现在为 extName 变量生成赋值和判空代码，如下：

String extName = url.getParameter("client", url.getParameter("transporter", "netty"));
    if (extName == null) { 
        throw new IllegalStateException(
            "Fail to get extension(com.alibaba.dubbo.remoting.Transporter) name from url(" + url.toString()
            + ") use keys([client, transporter])");
    }

#### 生成拓展加载与目标方法调用逻辑 ####

本段代码逻辑用于根据拓展名加载拓展实例，并调用拓展实例的目标方法。