02 Dubbo SPI——微内核与插件化架构

摘要

Dubbo SPI 是整个框架的”神经系统”——几乎所有的功能组件都通过 SPI 加载和扩展。理解 Dubbo SPI，不仅是理解 Dubbo 内部运作的关键，也是基于 Dubbo 做二次开发（自定义 Filter、自定义负载均衡、自定义注册中心）的必要前提。本文深入剖析 ExtensionLoader 的加载机制（从文件扫描到实例化的完整流程）、@Adaptive 自适应扩展的代码生成原理、以及 Wrapper 装饰器链的组装逻辑，解答”为什么 Dubbo 不用 Spring IoC 而要自己实现 SPI”的根本原因。

---

第 1 章 从 JDK SPI 到 Dubbo SPI：一次有针对性的改造

1.1 JDK SPI 的工作机制

Java 标准库从 JDK 6 开始提供 SPI（Service Provider Interface）机制，让框架定义接口，由第三方提供实现，通过配置文件解耦。

工作原理：

1. 在 META-INF/services/ 目录下创建以接口全限定名为文件名的配置文件；
2. 文件中每行写一个实现类的全限定名；
3. 通过 ServiceLoader.load(Interface.class) 加载所有实现。

示例：

# META-INF/services/java.sql.Driver
com.mysql.cj.jdbc.Driver
org.postgresql.Driver

ServiceLoader<Driver> loaders = ServiceLoader.load(Driver.class);
for (Driver driver : loaders) {
    // 遍历所有实现，每次迭代都会触发实例化
}

1.2 JDK SPI 的三个致命缺陷

缺陷一：全量实例化（资源浪费）

ServiceLoader 在遍历时，会将配置文件中所有的实现类逐一实例化。对于 Dubbo 这样的框架，Protocol 接口有十几种实现（DubboProtocol、TripleProtocol、HttpProtocol、GrpcProtocol……），但运行时通常只使用其中一种。JDK SPI 的全量实例化会将所有实现类全部加载，浪费内存和初始化时间。

缺陷二：无法按名称获取

JDK SPI 只能遍历所有实现，无法通过名称精准获取某一种实现。ServiceLoader 没有 getByName("dubbo") 这样的 API，如果需要根据运行时参数选择实现，必须自己遍历匹配，代码繁琐且低效。

缺陷三：不支持依赖注入

JDK SPI 通过反射调用无参构造方法创建实例，无法将 Spring Bean 或其他 Dubbo 组件注入到扩展实例中。这在 Dubbo 框架内部是硬伤——很多扩展实现需要依赖其他扩展（如 RegistryProtocol 需要注入 Cluster、ProxyFactory 等），JDK SPI 完全无法满足。

正是这三个缺陷，促使 Dubbo 团队实现了自己的 ExtensionLoader——保留了 SPI”通过配置文件发现实现”的核心思想，同时增加了按需加载、按名称获取、依赖注入、Adaptive 自适应扩展和 Wrapper 装饰器链五大增强特性。

---

第 2 章 ExtensionLoader：加载引擎的实现原理

2.1 配置文件的三个扫描目录

Dubbo SPI 的配置文件可以放在三个目录下（按优先级从高到低）：

META-INF/dubbo/internal/   ← Dubbo 框架内置扩展（最高优先级）
META-INF/dubbo/            ← 用户自定义扩展（推荐）
META-INF/services/         ← 兼容 JDK SPI 格式

配置文件名为接口的全限定名，格式为 key=value（key 是扩展名，value 是实现类全限定名）：

# META-INF/dubbo/org.apache.dubbo.rpc.Protocol
dubbo=org.apache.dubbo.rpc.protocol.dubbo.DubboProtocol
triple=org.apache.dubbo.rpc.protocol.tri.TripleProtocol
http=org.apache.dubbo.rpc.protocol.http.HttpProtocol

这与 JDK SPI 的区别在于：每个实现有一个显式的名称（key），这个名称是按需加载和 Adaptive 扩展的基础。

2.2 ExtensionLoader 的核心数据结构

每个扩展接口对应一个 ExtensionLoader 实例，ExtensionLoader 内部维护多级缓存：

public class ExtensionLoader<T> {
    // 全局缓存：接口类型 → ExtensionLoader 实例（每个接口只有一个 ExtensionLoader）
    private static final ConcurrentMap<Class<?>, ExtensionLoader<?>> EXTENSION_LOADERS
        = new ConcurrentHashMap<>();
 
    // 扩展名 → 扩展类（Class 对象，未实例化）
    private final Holder<Map<String, Class<?>>> cachedClasses = new Holder<>();
    
    // 扩展名 → 扩展实例（已实例化，单例）
    private final ConcurrentMap<String, Holder<Object>> cachedInstances
        = new ConcurrentHashMap<>();
    
    // Wrapper 类列表（装饰器）
    private Set<Class<?>> cachedWrapperClasses;
    
    // 默认扩展名（来自 @SPI("dubbo") 中的 "dubbo"）
    private String cachedDefaultName;
    
    // 自适应扩展实例（@Adaptive 修饰的类或动态生成的代理）
    private final Holder<Object> cachedAdaptiveInstance = new Holder<>();
}

2.3 getExtension 的完整加载流程

当调用 ExtensionLoader.getExtension("dubbo") 时，执行以下步骤：

步骤 1：检查 cachedInstances 缓存
  ├── 命中缓存 → 直接返回实例
  └── 未命中 → 进入创建流程

步骤 2：Double-Check Locking，防止并发重复创建
  synchronized(holder) {
      if (holder.get() == null) {
          创建实例...
      }
  }

步骤 3：调用 createExtension("dubbo")
  步骤 3.1：从 cachedClasses 获取类 → 如果 cachedClasses 为空，
            扫描三个配置目录，解析所有 key=value，填充 cachedClasses、
            cachedWrapperClasses、cachedAdaptiveClass
  步骤 3.2：通过反射实例化：clazz.getDeclaredConstructor().newInstance()
  步骤 3.3：依赖注入：injectExtension(instance)
            遍历实例的所有 setter 方法，如果 setter 参数类型是 Dubbo SPI 接口，
            注入对应的 Adaptive 扩展实例（而非具体实现，保持动态性）
  步骤 3.4：Wrapper 包装：
            遍历 cachedWrapperClasses，将真实实例逐一包裹进 Wrapper
            （每个 Wrapper 的构造方法接收同类型参数）

步骤 4：将实例存入 cachedInstances 缓存，返回

步骤 3.3 的依赖注入机制细节：

Dubbo SPI 的依赖注入不依赖 Spring，但模仿了 Spring 的 setter 注入：

private T injectExtension(T instance) {
    // 遍历所有 public setter 方法
    for (Method method : instance.getClass().getMethods()) {
        if (isSetter(method)) {  // 方法名以 set 开头，单参数，public
            Class<?> pt = method.getParameterTypes()[0];
            // 如果参数类型是 Dubbo SPI 接口（标注了 @SPI）
            if (ExtensionLoader.isExtensionPoint(pt)) {
                // 注入该接口的 Adaptive 扩展（动态代理，运行时根据 URL 选择实现）
                Object adaptiveExtension = ExtensionLoader
                    .getExtensionLoader(pt)
                    .getAdaptiveExtension();
                method.invoke(instance, adaptiveExtension);
            }
        }
    }
    return instance;
}

注意：注入的是 Adaptive 扩展而非具体实现。这确保了依赖的灵活性——被注入的组件在实际调用时，会根据 URL 动态选择具体实现，而不是在注入时就锁定。

---

第 3 章 Adaptive 自适应扩展：运行时动态路由

3.1 为什么需要 Adaptive 扩展

Dubbo 支持多种协议（Dubbo/Triple/HTTP/gRPC），同一个接口可以用不同协议暴露。当 Consumer 发起调用时，需要根据目标 Provider 的 URL 动态选择对应的 Protocol 实现。

如果没有 Adaptive 机制，每次调用前都需要手动 if/else 判断协议类型，然后手动调用 getExtension(protocolName) 获取实现——这既繁琐，又与框架代码深度耦合。

Adaptive 扩展解决了这个问题：它是一个代理对象，看起来是某个 SPI 接口的实现，但实际上在每次方法调用时，从传入参数的 URL 中读取指定的参数名，再动态调用对应的实现。

3.2 两种 Adaptive 实现方式

方式一：手动编写 @Adaptive 类

如果某个接口的适配逻辑比较复杂（无法用简单的 URL 参数决定），可以手动编写一个标注了 @Adaptive 的实现类：

@Adaptive
public class AdaptiveCompiler implements Compiler {
    private volatile String defaultCompiler;
    
    @Override
    public Class<?> compile(String code, ClassLoader classLoader) {
        Compiler compiler;
        String name = defaultCompiler;
        if (name == null || name.length() == 0) {
            // 没有配置时使用默认编译器
            compiler = ExtensionLoader.getExtensionLoader(Compiler.class)
                                     .getDefaultExtension();
        } else {
            compiler = ExtensionLoader.getExtensionLoader(Compiler.class)
                                     .getExtension(name);
        }
        return compiler.compile(code, classLoader);
    }
}

AdaptiveCompiler 是 Dubbo 内部真实存在的例子——Compiler 接口用于编译动态生成的代码，其实现选择取决于全局配置而非 URL 参数，所以手动编写了 Adaptive 类。

方式二：通过 @Adaptive 注解方法，自动生成代理代码

这是更常见的方式。在接口方法上标注 @Adaptive，Dubbo 会自动生成一个代理类：

@SPI("dubbo")
public interface Protocol {
    // value 指定从 URL 中读取哪个 key，默认是接口名的驼峰形式（"protocol"）
    @Adaptive
    <T> Exporter<T> export(Invoker<T> invoker) throws RpcException;
    
    @Adaptive
    <T> Invoker<T> refer(Class<T> type, URL url) throws RpcException;
    
    // 没有 @Adaptive 的方法，在生成的代理中会抛异常（不支持动态调用）
    int getDefaultPort();
}

3.3 自动生成的 Adaptive 代码解析

对于上面的 Protocol 接口，Dubbo 会自动生成类似以下的代理类（运行时动态编译）：

// 自动生成的类（由 Dubbo 在运行时通过 Javassist/JDK 编译）
public class Protocol$Adaptive implements Protocol {
    
    @Override
    public Exporter export(Invoker invoker) throws RpcException {
        if (invoker == null) {
            throw new IllegalArgumentException("invoker == null");
        }
        URL url = invoker.getUrl();
        if (url == null) {
            throw new IllegalArgumentException("url == null");
        }
        // 从 URL 中获取 "protocol" 参数，默认值为 "dubbo"（来自 @SPI("dubbo")）
        String extName = (url.getProtocol() == null) ? "dubbo" : url.getProtocol();
        if (extName == null) {
            throw new IllegalStateException("Failed to get extension name...");
        }
        // 根据名称获取真实实现（按需加载，带缓存）
        Protocol extension = (Protocol) ExtensionLoader
            .getExtensionLoader(Protocol.class)
            .getExtension(extName);
        // 调用真实实现
        return extension.export(invoker);
    }
    
    @Override
    public Invoker refer(Class type, URL url) throws RpcException {
        // 类似逻辑...
    }
    
    @Override
    public int getDefaultPort() {
        // 没有 @Adaptive，不支持动态调用
        throw new UnsupportedOperationException("...");
    }
}

这个生成的代理类实现了”运行时从 URL 中读取参数，动态路由到对应实现”的逻辑，且对调用方完全透明——调用方只需持有 Protocol 接口引用，无需关心具体实现。

3.4 @Adaptive 的 value 参数

@Adaptive 可以指定 URL 中的参数名（value 参数），如果不指定，默认从接口名推导：

@SPI("random")
public interface LoadBalance {
    // value = {"loadbalance"} → 从 URL 中读取 "loadbalance" 参数
    @Adaptive({"loadbalance"})
    <T> Invoker<T> select(List<Invoker<T>> invokers, URL url, Invocation invocation)
        throws RpcException;
}

生成的代理会从 URL 的 loadbalance 参数获取扩展名（如 loadbalance=random），然后加载 RandomLoadBalance。这就是 Dubbo 如何在不修改框架代码的情况下，通过 URL 参数动态切换负载均衡策略的机制。

---

第 4 章 Wrapper 装饰器链：透明的横切逻辑

4.1 Wrapper 的识别规则

Dubbo ExtensionLoader 在扫描配置文件时，对每个实现类做如下判断：

1. 该类是否实现了扩展接口？→ 是
2. 该类是否有一个接受扩展接口类型参数的构造方法？→ 如果是，则认为是 Wrapper 类

// 被识别为 Wrapper（有接受 Protocol 类型的构造方法）
public class ProtocolFilterWrapper implements Protocol {
    private final Protocol protocol;
    
    // ← 这个构造方法让 ExtensionLoader 识别它为 Wrapper
    public ProtocolFilterWrapper(Protocol protocol) {
        if (protocol == null) {
            throw new IllegalArgumentException("protocol == null");
        }
        this.protocol = protocol;
    }
    // ...
}

Wrapper 类不会出现在 cachedClasses（普通扩展实例的缓存），而是存入 cachedWrapperClasses（Wrapper 类集合）。

4.2 Wrapper 链的组装顺序

在 createExtension 的最后阶段，Dubbo 将 Wrapper 类依次包裹在真实扩展实例外面：

// 创建真实实例
T instance = (T) clazz.getDeclaredConstructor().newInstance();
// 依赖注入
injectExtension(instance);
// 逐一包裹 Wrapper
for (Class<?> wrapperClass : cachedWrapperClasses) {
    // 每次用 Wrapper 的构造方法包裹当前实例
    instance = (T) wrapperClass.getConstructor(type).newInstance(instance);
    // 对新的 Wrapper 实例也做依赖注入
    injectExtension(instance);
}
return instance;

包裹顺序取决于 cachedWrapperClasses 的迭代顺序（通常是 TreeSet，按类名字典序排列，Dubbo 3.x 支持通过 @Activate 控制顺序）。

实际效果（以 Protocol 为例）：

调用 getExtension("dubbo") 时，返回的实际上是：
ProtocolListenerWrapper(
    ProtocolFilterWrapper(
        DubboProtocol（真实实现）
    )
)

当 Consumer 调用 protocol.refer() 时，实际执行路径：

1. ProtocolListenerWrapper.refer() → 触发监听器通知
2. ProtocolFilterWrapper.refer() → 组装 Filter 链
3. DubboProtocol.refer() → 真正建立 Netty 连接

这种设计使 Filter 链、监听器通知等横切逻辑完全对调用方透明——调用方只持有 Protocol 接口，不知道也不需要知道其背后的 Wrapper 链。

4.3 Filter 链的组装：ProtocolFilterWrapper 的核心逻辑

ProtocolFilterWrapper 是 Dubbo Filter 机制的实际入口，理解它的实现可以看清 Filter 链是如何构建的：

public class ProtocolFilterWrapper implements Protocol {
    
    @Override
    public <T> Invoker<T> refer(Class<T> type, URL url) throws RpcException {
        // 对注册中心协议，不包装 Filter（注册中心协议处理的是元数据，不是业务调用）
        if (UrlUtils.isRegistry(url)) {
            return protocol.refer(type, url);
        }
        // 对业务协议（dubbo/triple/http 等），组装 Filter 链后包裹 Invoker
        return buildInvokerChain(
            protocol.refer(type, url),  // 先调用真实 Protocol 创建 Invoker
            Constants.REFERENCE_FILTER_KEY,  // 从 URL 读取 Filter 配置
            CommonConstants.CONSUMER
        );
    }
    
    private <T> Invoker<T> buildInvokerChain(Invoker<T> invoker, 
                                              String key, String group) {
        // 加载所有激活的 Filter（通过 @Activate 注解和 URL 参数控制）
        List<Filter> filters = ExtensionLoader.getExtensionLoader(Filter.class)
                                             .getActivateExtension(invoker.getUrl(), key, group);
        // 从后往前，将 Filter 链装配成 Invoker 链
        // 效果：filter1(filter2(filter3(realInvoker)))
        if (!CollectionUtils.isEmpty(filters)) {
            for (int i = filters.size() - 1; i >= 0; i--) {
                final Filter filter = filters.get(i);
                final Invoker<T> next = invoker;
                invoker = new CallbackRegistrationInvoker<>(
                    new FilterNode<T>(invoker.getUrl(), next, filter),
                    filters
                );
            }
        }
        return invoker;
    }
}

这就是 Filter 机制的全貌——每个 Filter 被包装成一个 FilterNode（实现了 Invoker 接口），多个 FilterNode 形成链表，最终暴露给调用方的是链头的 Invoker。

---

第 5 章 @Activate：条件激活的 Filter 管理

5.1 什么是 @Activate

@Activate 是 Dubbo SPI 的条件激活注解，用于控制扩展实例在什么条件下应该被激活（加入到集合中）：

@Activate(group = CommonConstants.CONSUMER, order = -10000)
public class ConsumerContextFilter implements Filter {
    // 只在 Consumer 侧激活，执行顺序为 -10000（越小越先执行）
}
 
@Activate(group = {CommonConstants.PROVIDER, CommonConstants.CONSUMER})
public class TimeoutFilter implements Filter {
    // 在 Provider 和 Consumer 侧都激活
}
 
@Activate(group = CommonConstants.PROVIDER, value = "token")
public class TokenFilter implements Filter {
    // 只在 Provider 侧激活，且只有当 URL 中存在 "token" 参数时才激活
}

getActivateExtension(url, key, group) 会根据 group 过滤（Consumer 还是 Provider）、根据 value 检查 URL 参数是否存在、根据 order 排序，最终返回应该激活的 Filter 列表。

5.2 用户自定义 Filter 的接入

基于 @Activate 机制，业务团队可以非常方便地接入自定义 Filter：

// 自定义限流 Filter
@Activate(group = CommonConstants.PROVIDER, order = 100)
public class RateLimitFilter implements Filter {
    @Override
    public Result invoke(Invoker<?> invoker, Invocation invocation) throws RpcException {
        // 在调用前执行限流逻辑
        if (rateLimiter.tryAcquire()) {
            return invoker.invoke(invocation);  // 放行
        } else {
            throw new RpcException("Rate limit exceeded");
        }
    }
}

配置文件（META-INF/dubbo/org.apache.dubbo.rpc.Filter）：

rateLimit=com.example.RateLimitFilter

添加这两个文件后，在所有 Provider 的 Filter 链中，RateLimitFilter 会自动以正确的顺序（order=100）插入，无需修改框架代码。这正是 Dubbo SPI 机制带来的扩展性价值。

---

第 6 章 SPI 与 Spring IoC 的协作

6.1 为什么不直接用 Spring

一个常见的问题：Dubbo 大量使用 Spring，为什么还要自己实现 SPI，而不是直接用 Spring IoC？

原因有三：

1. 独立性：Dubbo SPI 的核心机制（ExtensionLoader、Adaptive、Wrapper）不依赖 Spring，可以在非 Spring 环境中使用（如独立的 Java SE 程序、Android 端的 RPC 客户端）；

2. 性能与控制：Spring IoC 的 Bean 生命周期管理对于 Dubbo 框架层的扩展点过于重量级。框架层的扩展点（如 Protocol、Serialization）大多是单例且无状态，不需要 Spring 的完整生命周期管理，自己的 ExtensionLoader 更轻量；

3. 启动顺序：Dubbo 需要在 Spring 容器完全初始化之前完成部分 SPI 扩展的加载（如 Compiler，用于动态生成 Adaptive 代码），如果依赖 Spring，会产生启动顺序的循环依赖。

6.2 Dubbo SPI 与 Spring 的集成点

Dubbo 通过 SpringExtensionInjector（Dubbo 3.x 的命名，Dubbo 2.x 中是 SpringExtensionFactory）将 Spring Bean 作为 SPI 扩展的注入来源：

public class SpringExtensionInjector implements ExtensionInjector {
    private ApplicationContext context;
    
    @Override
    public <T> T getInstance(Class<T> type, String name) {
        // 优先从 Spring 容器中获取 Bean
        if (context.containsBean(name)) {
            Object bean = context.getBean(name);
            if (type.isInstance(bean)) {
                return (T) bean;
            }
        }
        // 按类型获取
        return context.getBean(type);
    }
}

这样，当 Dubbo SPI 在依赖注入阶段需要注入一个 Spring Bean 时（如用户自定义的 UserFilter 引用了 Spring 管理的 UserService），SpringExtensionInjector 会从 Spring 容器中获取。两套 IoC 系统优雅地协作，互不侵入。

---

小结

本文深度剖析了 Dubbo SPI 的三大核心机制：

• ExtensionLoader：三目录扫描 + 按名称按需加载 + 多级缓存 + setter 依赖注入（注入 Adaptive 扩展）——解决了 JDK SPI 全量加载和无法注入的缺陷；
• Adaptive 自适应扩展：对有 @Adaptive 方法的接口，自动生成代理代码，在每次方法调用时从 URL 中读取参数名，动态路由到对应实现——实现了”运行时根据 URL 选择实现”的无侵入动态性；
• Wrapper 装饰器链：通过识别”接受扩展接口类型参数的构造方法”自动组装装饰器链，Filter 链、监听器通知等横切逻辑对调用方完全透明。

三者组合，构成了 Dubbo “微内核 + 插件化”架构的骨架——框架本身只提供了空的扩展点定义，所有功能都通过 SPI 实现注册，且可以被无限替换和扩展。

下一篇文章将深入服务导出与服务引用的完整流程——从 @DubboService 注解到 Netty Server 监听端口的每一个步骤。

---

思考题

1. Dubbo 2.x 使用’接口级’服务注册——每个服务接口（如 com.example.UserService）注册为独立的节点。Dubbo 3.x 引入了’应用级’服务注册——一个应用只注册一次，包含该应用提供的所有服务。应用级注册在什么场景下显著减少了注册中心的压力？在数千微服务的集群中，接口级注册可能产生多少注册节点？
2. 注册中心（ZooKeeper、Nacos）是 Dubbo 的单点依赖——如果注册中心不可用，Consumer 无法发现新的 Provider。但 Dubbo 有本地缓存机制——Consumer 缓存了最近的 Provider 列表。注册中心短暂不可用时，已有的 Consumer 调用不受影响。那’新启动的 Consumer’能否正常工作？
3. 从 ZooKeeper 迁移到 Nacos 作为注册中心是常见需求（Nacos 部署更简单、支持配置管理）。Dubbo 3.x 支持多注册中心——可以同时注册到 ZK 和 Nacos。迁移期间如何保证平滑过渡？双注册双订阅的策略在什么时机可以安全切断旧注册中心？