Soul源码阅读 - Extension机制

Soul的架构体系采用的是插件化的思想，这样做使整个架构的扩展性更强，可以在不修改核心代码的情况下进新增插件件的添加，而这个体系中最核心的机制是采用了SPI，为接口寻找服务实现的机制，这个机制与Spring中的IoC思想有些类似，将程序中接口与实现的强关联关系变成可插拔关系。

Java SPI

SPI全称为Service Provider Interface，是JDK内置的一种服务提供发现功能，一种动态替换发现的机制。

Soul的Extension实现

通过LoadBalance接口的SPI规范，来分析完整的Soul扩展点加载过程。

LoadBalance.java 定义SPI接口

// @SPI 代表是SPI，用户可以自定义实现该接口
@SPI
public interface LoadBalance {

    // 根据负载均衡策略选择上游服务的地址信息
    DivideUpstream select(List<DivideUpstream> upstreamList, String ip);
}

LoadBalance接口的Soul内置的三种实现类：

RoundRobinLoadBalance

@Join
public class RoundRobinLoadBalance extends AbstractLoadBalance {
    // ...
}

RandomLoadBalance

@Join
public class RandomLoadBalance extends AbstractLoadBalance {
    // ...
}

HashLoadBalance

@Join
public class HashLoadBalance extends AbstractLoadBalance {
    // ...
}

@Join注解主要功能是给@SPI注解的接口提供具体实现类的映射关系，该映射关系配置是在配置文件中配置，该文件在soul-plugin子模块的soul-plugin-divide包中：

当Soul网关启动的加载的时候会读取以下目录中的配置文件：

META-INF.soul/

扩展点加载

主要是通过ExtensionLoader.getExtensionLoader方法进行加载的，每个定义的SPI接口都会产生一个ExtensionLoader实例，保存在Map中。代码如下：


// ExtensionLoader从该配置文件中加载SPI配置
private static final String SOUL_DIRECTORY = "META-INF/soul/";

// LOADERS实例是一个ConcurrentHashMap实例，key是方法传过来的SPI接口头名，value是ExtensionLoader实例类。
private static final Map<Class<?>, ExtensionLoader<?>> LOADERS = new ConcurrentHashMap<>();

public static <T> ExtensionLoader<T> getExtensionLoader(final Class<T> clazz) {
    if (clazz == null) {
        throw new NullPointerException("extension clazz is null");
    }
    // 必须是接口类型
    if (!clazz.isInterface()) {
        throw new IllegalArgumentException("extension clazz (" + clazz + ") is not interface!");
    }
    // 只接受使用@SPI注解的接口类型
    if (!clazz.isAnnotationPresent(SPI.class)) {
        throw new IllegalArgumentException("extension clazz (" + clazz + ") without @" + SPI.class + " Annotation");
    }
    // 先从缓存中获取对应的ExtensionLoader实例
    ExtensionLoader<T> extensionLoader = (ExtensionLoader<T>) LOADERS.get(clazz);
    if (extensionLoader != null) {
        return extensionLoader;
    }
    // 如果为实例为null，则创建一个
    LOADERS.putIfAbsent(clazz, new ExtensionLoader<>(clazz));
    return (ExtensionLoader<T>) LOADERS.get(clazz);
}

ExtensionLoader.loadResources方法读取配置文件：META-INF/soul/org.dromara.soul.plugin.divide.balance

// 读取配置文件中的内容，参数url就是文件所在路径
// 文件内容要定义properties的格式 key=value
private void loadResources(final Map<String, Class<?>> classes, final URL url) throws IOException {
    // 读取文件中的流
    try (InputStream inputStream = url.openStream()) {
        Properties properties = new Properties();
        properties.load(inputStream);
        properties.forEach((k, v) -> {
            // key
            String name = (String) k;
            // class path
            String classPath = (String) v;
            if (StringUtils.isNotBlank(name) && StringUtils.isNotBlank(classPath)) {
                try {
                    // 加载类并创建类实例
                    loadClass(classes, name, classPath);
                } catch (ClassNotFoundException e) {
                    throw new IllegalStateException("load extension resources error", e);
                }
            }
        });
    } catch (IOException e) {
        throw new IllegalStateException("load extension resources error", e);
    }
}

// 加载类，并创建类实例
private void loadClass(final Map<String, Class<?>> classes,
                       final String name, final String classPath) throws ClassNotFoundException {
    // 加载类
    Class<?> subClass = Class.forName(classPath);
    // 如果该类不是实现类则抛异常
    if (!clazz.isAssignableFrom(subClass)) {
        throw new IllegalStateException("load extension resources error," + subClass + " subtype is not of " + clazz);
    }
    // 获取@Join注解
    Join annotation = subClass.getAnnotation(Join.class);
    // 如果不是@Join注解的类则抛异常
    if (annotation == null) {
        throw new IllegalStateException("load extension resources error," + subClass + " with Join annotation");
    }
    // 从map中获取，如果没有则put，如果存在则抛异常
    Class<?> oldClass = classes.get(name);
    if (oldClass == null) {
        classes.put(name, subClass);
    } else if (oldClass != subClass) {
        throw new IllegalStateException("load extension resources error,Duplicate class " + clazz.getName() + " name " + name + " on " + oldClass.getName() + " or " + subClass.getName());
    }
}

获取扩展点的过程

通过上面的代码我们实现了Soul网关启动加载SPI的扩展实现类信息。当我们需要指定具体的实现类，可以调用ExtensionLoader.getJoin方法获取具体实现类。

public T getJoin(final String name) {
    if (StringUtils.isBlank(name)) {
        throw new NullPointerException("get join name is null");
    }
    // 从缓存中获取
    Holder<Object> objectHolder = cachedInstances.get(name);
    if (objectHolder == null) {
        cachedInstances.putIfAbsent(name, new Holder<>());
        objectHolder = cachedInstances.get(name);
    }
    // 如果缓存中不存在，则创建
    Object value = objectHolder.getValue();
    if (value == null) {
        synchronized (cachedInstances) {
            value = objectHolder.getValue();
            if (value == null) {
                // 创建具体的实现类
                value = createExtension(name);
                objectHolder.setValue(value);
            }
        }
    }
    return (T) value;
}

private T createExtension(final String name) {
    // 从配置文件加载并创建实例
    Class<?> aClass = getExtensionClasses().get(name);
    if (aClass == null) {
        throw new IllegalArgumentException("name is error");
    }
    // 从缓存中获取
    Object o = joinInstances.get(aClass);
    if (o == null) {
        try {
            // 如果缓存中没有则创建类实例
            joinInstances.putIfAbsent(aClass, aClass.newInstance());
            o = joinInstances.get(aClass);
        } catch (InstantiationException | IllegalAccessException e) {
            throw new IllegalStateException("Extension instance(name: " + name + ", class: "
                    + aClass + ")  could not be instantiated: " + e.getMessage(), e);

        }
    }
    return (T) o;
}

总结

基于接口的编程＋策略模式＋配置文件的组合实现的动态加载机制。接口类必须加上@SPI, 实现类必须加上@Join。

Soul源码阅读 - Extension机制