Skip to content

3.4-2 Dubbo SPI:ExtensionLoader、@Adaptive、@Activate ​

所属:03 主流框架 / 3.4 Dubbo 分级:A 状态:◐ 初稿 关联:3.4-1、3.4-3、3.4-4、3.4-6、3.4-7

  • 题型:原理 / 源码 / 对比

  • 一句话结论:Dubbo SPI 是 按名字加载、按需实例化、带 IoC 和 AOP 的扩展机制:ExtensionLoader.getExtensionLoader(接口) 读取 META-INF/dubbo*/ 下的 name=实现类 文件,getExtension(name) 只创建被选中的实现,并通过 ExtensionFactory/ExtensionInjector 注入依赖、用 Wrapper 类层层包装。@SPI 声明默认扩展名,@Adaptive 让框架在运行时按 URL 参数选出实现(类上标记则手写自适应类,方法上标记则动态生成 Xxx$Adaptive 字节码/源码),@Activate 让 Filter/Listener 这类扩展按 group 和配置自动激活并排序。这正是 dubbo:// URL 里一个 protocol=dubbo 就能决定用哪个 Protocol 的原因。

  • 分层要点:

    1. 先说 JDK SPI 的三个短板:只能全量加载(ServiceLoader 迭代即实例化)、没有扩展名(无法按配置选实现)、没有依赖注入和包装(实现类之间无法组合)。Dubbo 要在运行时按 URL 选 Protocol/Cluster/LoadBalance,还要给 Filter 排序、给扩展注入 Spring Bean,所以自己实现了一套。
    2. 加载入口是 ExtensionLoader:静态缓存 EXTENSION_LOADERS(接口 → loader)、EXTENSION_INSTANCES(实现类 → 单例);每个 loader 缓存 cachedClasses(name → Class)、cachedNames(Class → name)、cachedAdaptiveClass、cachedWrapperClasses、cachedActivateClasses。同一个扩展名全局只实例化一次。
    3. SPI 文件有三个位置:META-INF/dubbo/internal/<接口全限定名>(Dubbo 内置)、META-INF/dubbo/<接口全限定名>(用户扩展)、META-INF/services/<接口全限定名>(兼容 JDK SPI)。内容格式是 name=com.foo.BarImpl,不是 JDK 的一行一个类名。
    4. @SPI 声明“这是扩展接口 + 默认实现名”:如 @SPI("javassist") 表示默认 javassist;getDefaultExtension() 走默认名,getExtension(name) 走指定名,getSupportedExtensions() 只返回名字不实例化。
    5. @Adaptive 解决“运行时才知道用哪个实现”:标在类上,表示这个类就是自适应实现(如 AdaptiveExtensionFactory、AdaptiveCompiler);标在方法上,ExtensionLoader 会用 AdaptiveClassCodeGenerator 生成 接口名$Adaptive 类,方法体从 URL 参数取扩展名再 getExtension(name) 转发。Dubbo 里 Protocol、ProxyFactory、Cluster、LoadBalance、RegistryFactory 都是方法级 @Adaptive。
    6. @Activate 解决“哪些扩展默认生效”:Filter/Listener 这类扩展不需要调用方按名选,而是按 group(provider/consumer)、value(URL 参数开关)、order(顺序)、before/after 自动装配。getActivateExtension(url, key, group) 会过滤 + 排序,ProtocolFilterWrapper 就是靠它把 Filter 链织到 Invoker 上。
    7. IoC 与 AOP 是 Dubbo SPI 的两个增强:IoC 通过 ExtensionFactory(2.x)/ExtensionInjector(3.x)在 injectExtension 时给 setter 注入其他扩展或 Spring Bean;AOP 通过 Wrapper 类(构造函数只有一个参数,类型是 SPI 接口)实现,getExtension 返回的是被所有 Wrapper 包过的实例——ProtocolFilterWrapper、ProtocolListenerWrapper、QosProtocolWrapper 都是这么织进去的。
    8. 排障要按“文件 → 注解 → 名字 → 类加载器”顺序:SPI 文件路径/文件名错 → 接口没标 @SPI → 实现没实现接口 → getExtension("xxx") 名字拼错 → 容器里 TCCL 不对。报错通常是 IllegalStateException: No such extension 或 IllegalArgumentException: ... is not an extension,不会在编译期暴露。
  • 图/流程:

text
ExtensionLoader 获取扩展:
  ExtensionLoader.getExtensionLoader(Protocol.class)
    → EXTENSION_LOADERS 命中 → 返回
    → 未命中 → new ExtensionLoader(type)
        → objectFactory = AdaptiveExtensionFactory
        → cachedDefaultName = @SPI 的 value

  getExtension("dubbo")
    → getExtensionClasses()
        → loadDirectory(META-INF/dubbo/internal/)
        → loadDirectory(META-INF/dubbo/)
        → loadDirectory(META-INF/services/)
          → loadClass:
              @Adaptive 在类上 → cachedAdaptiveClass
              只有一个接口参数的构造器 → cachedWrapperClasses
              否则 → cachedClasses[name] = clazz
              有 @Activate → cachedActivateClasses
    → createExtension("dubbo")
        → clazz.newInstance()
        → injectExtension(instance)        // setter 注入其他扩展
        → 用 cachedWrapperClasses 逐层包装
        → instance instanceof Lifecycle → initialize()
    → EXTENSION_INSTANCES 缓存
text
@Adaptive 方法级:动态生成
  接口 Protocol:
    @Adaptive
    Exporter export(Invoker<?> invoker);

  生成 Protocol$Adaptive:
    public Exporter export(Invoker arg0) {
        URL url = arg0.getUrl();
        String extName = url.getProtocol();      // 参数 key 来自 @Adaptive(value)
        Protocol extension = ExtensionLoader
            .getExtensionLoader(Protocol.class)
            .getExtension(extName);
        return extension.export(arg0);
    }
  调用方只依赖 Protocol,具体实现由 URL 决定
text
@Activate 激活:
  ProtocolFilterWrapper.buildInvokerChain(invoker, key, group)
    → ExtensionLoader.getActivateExtension(url, key, group)
        → 取 cachedActivateClasses
        → 过滤 group(provider/consumer)
        → 过滤 value(URL 参数开关)
        → 按 order / before / after 排序
        → 依次 getExtension(name)
    → new FilterChain 包在 Invoker 外层
text
Wrapper(AOP):
  Protocol real = DubboProtocol
    → new ProtocolFilterWrapper(real)
      → new ProtocolListenerWrapper(...)
        → new QosProtocolWrapper(...)
  getExtension 返回最外层,调用逐层透传
  • 版本/源码锚点:

    • 2.7.x:org.apache.dubbo.common.extension.ExtensionLoader、ExtensionFactory、AdaptiveExtensionFactory、SpiExtensionFactory、SpringExtensionFactory、AdaptiveClassCodeGenerator、ActivateComparator、ProtocolFilterWrapper、ProtocolListenerWrapper、QosProtocolWrapper。
    • 3.x:ExtensionDirector/ScopeModel 管理不同作用域的 loader;ExtensionInjector(SpiExtensionInjector、SpringExtensionInjector)取代 2.x 的 ExtensionFactory;ExtensionLoader 的加载/缓存/自适应语义不变。
    • 注解:@SPI、@Adaptive、@Activate、@DisableInject;@Adaptive 的 value 是 URL 参数名数组,按顺序取第一个非空。
    • 常见扩展接口:Protocol(@Adaptive)、ProxyFactory(@SPI("javassist"))、Cluster(@SPI(FailoverCluster.NAME))、LoadBalance(@SPI(RandomLoadBalance.NAME))、RegistryFactory、Serialization、Dispatcher、ThreadPool、Compiler、Filter。
    • SPI 文件:META-INF/dubbo/internal/、META-INF/dubbo/、META-INF/services/。
  • JDK SPI vs Dubbo SPI:

维度JDK SPIDubbo SPI
文件位置META-INF/services/<接口>META-INF/dubbo*/<接口> + 兼容 services
文件内容一行一个实现类name=实现类
加载方式ServiceLoader 全量迭代按 name 按需加载
扩展名无有,可按配置选
默认实现无@SPI("xxx")
依赖注入无ExtensionFactory/ExtensionInjector
包装增强无Wrapper 类
自动激活无@Activate + order
运行时选择不支持@Adaptive 按 URL 选
缓存每次新 ServiceLoader全局缓存单例
  • 三个注解:
注解位置作用典型例子
@SPI接口标记扩展接口,声明默认名@SPI("javassist") ProxyFactory
@Adaptive类该类就是自适应实现AdaptiveExtensionFactory、AdaptiveCompiler
@Adaptive方法生成 $Adaptive,按 URL 参数选实现Protocol.export/refer、Cluster.join
@Activate类按 group/value/order 自动激活ConsumerContextFilter、ExceptionFilter、AccessLogFilter
@DisableInjectsetter跳过注入避免误注入
  • @Activate 属性:
属性含义示例
groupprovider/consumer/allgroup = {PROVIDER, CONSUMER}
valueURL 参数开关名,空数组表示总是激活value = "accesslog"
order顺序,越小越靠前order = -10000
before排在指定扩展名之前before = "monitor"
after排在指定扩展名之后after = "context"
  • 常见扩展点:
接口默认实现选择方式
ProtocoldubboURL protocol
ProxyFactoryjavassistURL proxy
ClusterfailoverURL cluster
LoadBalancerandomURL loadbalance
RegistryFactory按地址协议URL protocol(zookeeper/nacos)
Serializationhessian2URL serialization
DispatcherallURL dispatcher
ThreadPoolfixedURL threadpool
Filter多个,@Activategroup + value + order
CompilerjavassistAdaptiveCompiler
  • 失效场景与定位:
现象根因处理
No such extension xxxSPI 文件没写/名字拼错/目录不对检查文件与 name=
is not an extension接口没标 @SPI补注解
自定义 Filter 不生效没加 @Activate 或 group 不匹配补注解、确认 provider/consumer
Wrapper 没生效构造函数不是“单参数且为 SPI 接口”调整构造器
自适应类创建失败没有 @Adaptive 方法/无法从参数取 URL检查方法签名与注解
@Adaptive 取不到扩展名URL 参数 key 写错/参数为 null对齐 @Adaptive(value) 与 URL
注入为 nullsetter 不是 public/参数类型不是扩展改 setter 或 @DisableInject
容器内加载失败TCCL 不是应用类加载器指定 classloader/排查隔离
同名扩展被覆盖多个 jar 写了同名统一命名、排除冲突 jar
单测互相污染ExtensionLoader 静态缓存隔离用例/重置缓存
  • 深挖点(面试官常追的 6 个):

    1. 为什么要自己实现 SPI:Dubbo 的核心诉求是“同一个接口,按配置/URL 选不同实现”,JDK SPI 只能全量加载且没有名字;同时 Dubbo 需要给扩展注入 Spring Bean(SpringExtensionFactory)、需要 Wrapper 做 AOP(Filter、Listener)、需要 @Activate 给 Filter 排序。这四点 JDK SPI 都不支持,所以有了 ExtensionLoader。
    2. ExtensionLoader 的加载与缓存:getExtensionLoader 先查静态 EXTENSION_LOADERS;getExtension(name) 先 getExtensionClasses() 扫描三个目录,loadClass 时按“类上有 @Adaptive → 自适应类;构造器单参数是接口 → Wrapper;否则按 name 缓存”分类;实例化后 injectExtension 注入 setter,再用 Wrapper 逐层包,最后按 Lifecycle 初始化;实例放 EXTENSION_INSTANCES,同名扩展全局单例。
    3. @Adaptive 的两种形态:类级 @Adaptive 是手写的自适应实现(AdaptiveExtensionFactory 在运行时决定用 SPI 还是 Spring 的工厂);方法级 @Adaptive 由 AdaptiveClassCodeGenerator 生成源码,再交给 Compiler(默认 Javassist)编译。生成逻辑是:从方法参数里找 URL(直接是 URL,或有 getUrl() 的 Invoker),用 @Adaptive(value) 的 key 取扩展名,getExtension 后转发;找不到 URL 或扩展名就抛异常。
    4. @Activate 与 Filter 顺序:getActivateExtension(url, key, group) 先从 cachedActivateClasses 取候选,按 group 过滤(provider/consumer),按 value 判断 URL 参数开关,再用 ActivateComparator 按 order、before、after 排序。ProtocolFilterWrapper 用它构建 Filter 链,所以自定义 Filter 只要 @Activate(group=PROVIDER, order=...) 就自动生效;value="accesslog" 这类表示“只有配了 accesslog=true 才启用”。
    5. IoC 和 AOP 怎么实现:IoC 是 injectExtension 遍历 setter,用 ExtensionFactory(3.x ExtensionInjector)按参数类型和属性名找扩展或 Spring Bean 注入;AOP 是 Wrapper:类有一个“参数类型为 SPI 接口”的构造器就被识别为 Wrapper,getExtension 时 new Wrapper(instance) 层层包裹。Wrapper 不能按名字获取,只参与包装;多个 Wrapper 的嵌套顺序取决于集合迭代,不要依赖具体顺序。
    6. 自定义扩展怎么落地:实现接口 → 在 META-INF/dubbo/<接口全限定名> 写 myext=com.foo.MyImpl → 接口有 @SPI 且方法有 @Adaptive(或调用方显式 getExtension("myext"))→ 配置里写 protocol=myext/cluster=myext 等。Filter 还要加 @Activate。排障先确认文件在不在、名字对不对、TCCL 能不能读到。
  • 追问链:

    1. Dubbo SPI 和 JDK SPI 区别? → 按名加载、按需实例化、IoC、AOP、激活排序。
    2. SPI 文件放哪? → META-INF/dubbo/internal/、META-INF/dubbo/、META-INF/services/。
    3. 文件格式? → name=实现类全限定名。
    4. JDK SPI 文件格式? → 一行一个类名。
    5. 为什么 JDK SPI 不够? → 全量加载、无名字、无注入、无包装。
    6. ExtensionLoader 怎么拿? → getExtensionLoader(接口.class),静态缓存。
    7. 扩展实例什么时候创建? → getExtension(name) 时,按需。
    8. 扩展是单例吗? → 是,全局缓存。
    9. @SPI 作用? → 标记扩展接口 + 默认实现名。
    10. 默认扩展怎么取? → getDefaultExtension()。
    11. getSupportedExtensions 会实例化吗? → 不会,只返回名字。
    12. @Adaptive 标在类上? → 该类就是自适应实现。
    13. 标在方法上? → 动态生成 $Adaptive 类。
    14. 生成类怎么选实现? → 从 URL 参数取扩展名。
    15. URL 从哪来? → 方法参数里的 URL 或 Invoker.getUrl()。
    16. 取不到 URL 会怎样? → 抛异常。
    17. @Adaptive 的 value 是什么? → URL 参数 key 数组。
    18. 不写 value 呢? → 按接口名推导参数 key。
    19. 生成代码靠什么编译? → Compiler SPI,默认 Javassist。
    20. Protocol 是自适应扩展吗? → 是,export/refer 方法级 @Adaptive。
    21. AdaptiveExtensionFactory 做什么? → 类级自适应,运行时选 SPI/Spring 工厂。
    22. @Activate 作用? → 自动激活并排序。
    23. @Activate 的 group? → provider/consumer/all。
    24. @Activate 的 value? → URL 参数开关。
    25. @Activate 的 order? → 越小越靠前。
    26. before/after 呢? → 相对其他扩展排序。
    27. Filter 怎么自动生效? → @Activate + SPI 文件 + ProtocolFilterWrapper。
    28. Filter 链顺序谁定? → ActivateComparator。
    29. Wrapper 是什么? → 单参数构造器、参数为 SPI 接口的包装类。
    30. Wrapper 能按名取吗? → 不能,只参与包装。
    31. Wrapper 有什么用? → AOP,如 Filter/Listener/Qos。
    32. IoC 怎么注入? → injectExtension + ExtensionFactory/ExtensionInjector。
    33. 能注入 Spring Bean 吗? → 能,SpringExtensionFactory/SpringExtensionInjector。
    34. 注入失败会怎样? → 属性为 null,通常不报错。
    35. @DisableInject 干什么? → 跳过注入。
    36. 扩展实现 Lifecycle 会怎样? → 创建后调 initialize()。
    37. 扩展缓存会串测试吗? → 会,静态缓存需要隔离。
    38. 类加载器问题? → 用 TCCL/指定 loader,容器里常见。
    39. 同名扩展冲突? → 按加载顺序,需排除冲突 jar。
    40. 怎么自定义 Protocol? → 实现 + SPI 文件 + 配 protocol=xxx。
    41. 怎么自定义 Cluster? → 实现 + SPI + 配 cluster=xxx。
    42. 怎么自定义 LoadBalance? → 实现 + SPI + 配 loadbalance=xxx。
    43. 怎么自定义序列化? → 实现 Serialization + SPI + 配 serialization=xxx。
    44. 怎么自定义线程池? → 实现 ThreadPool + SPI + 配 threadpool=xxx。
    45. @Adaptive 能用在构造器吗? → 不能,只支持类和方法。
    46. Dubbo 3 有什么变化? → ExtensionDirector/ScopeModel、ExtensionInjector。
    47. ScopeModel 解决什么? → 多应用/多模块隔离,扩展按作用域管理。
    48. 和 Spring 的 SPI 区别? → Spring 是 spring.factories 接口→列表,无命名/自适应/激活。
    49. 怎么排查扩展不生效? → 文件 → 注解 → 名字 → group → TCCL。
    50. 面试怎么总结? → JDK SPI 短板 → ExtensionLoader 加载缓存 → 三注解 → IoC/AOP → 排障。
  • 生产案例/取舍(示例,替换成你的项目):

    • 自定义 Filter 加了 @Activate(group = PROVIDER) 但一直不生效,SPI 文件名写成接口简单名;改成全限定名恢复。
    • 自定义 Cluster 想按配置切换,但接口漏了 @SPI;启动报 is not an extension。
    • @Adaptive("myProtocol") 与 URL 参数 protocol 不一致,取不到扩展;对齐 key。
    • 自定义 Protocol 的 Wrapper 构造器写成两个参数,未被识别为 Wrapper;改成单参数。
    • 两个内部 jar 都提供同名 Filter,行为不稳定;统一命名并排除旧 jar。
    • 单元测试里扩展实例被缓存,第二个用例拿到脏状态;隔离或重置。
    • 容器化后 SPI 文件读不到,TCCL 指向框架 loader;显式指定类加载器。
    • AccessLogFilter 没配 accesslog=true 不生效;确认 @Activate(value=...) 语义。
    • 用 @Activate(order) 调 Filter 顺序,结果与自定义 before/after 冲突;统一用 order。
    • ExtensionInjector 注入的 Spring Bean 在启动早期为 null;延后到首次调用或改用 ObjectProvider。
    • 取舍:按名加载换灵活性,代价是运行期才发现配置错误;动态生成自适应类换零侵入,代价是首次调用编译开销与调试难度;Wrapper 换 AOP,代价是调用栈变深;@Activate 换自动装配,代价是顺序隐式、排查困难。
  • 易错点:

    • 认为 Dubbo SPI 就是 JDK SPI 换了个目录。
    • 认为 SPI 文件里一行一个类名。
    • 认为 ServiceLoader 只加载不实例化(迭代时实例化)。
    • 认为 ExtensionLoader 每次 getExtension 都 new。
    • 认为扩展实例是 prototype。
    • 认为 @SPI 只是标记,没有默认值语义。
    • 认为 @Adaptive 只能标在方法上。
    • 认为 @Adaptive 类级和方法级效果一样。
    • 认为自适应类一定靠反射调用。
    • 认为 $Adaptive 类需要手写。
    • 认为 @Adaptive 从配置中心取名字。
    • 认为 @Activate 对所有扩展都生效。
    • 认为 @Activate 的 value 是扩展名。
    • 认为 @Activate 的 order 越大越靠前。
    • 认为 Wrapper 可以按名字 getExtension。
    • 认为 Wrapper 需要实现固定接口。
    • 认为 IoC 只注入 Dubbo 扩展、不注入 Spring Bean。
    • 认为 @DisableInject 是禁用扩展。
    • 认为扩展加载失败会在编译期报错。
    • 认为 No such extension 一定是文件缺失。
    • 认为 SPI 文件可以放在任意目录。
    • 认为 META-INF/services 会被忽略。
    • 认为同名扩展后者覆盖前者。
    • 认为 Filter 不加 @Activate 也能自动生效。
    • 认为 ExtensionLoader 线程不安全。
    • 认为 Dubbo 3 的扩展机制完全重写。
    • 认为 ScopeModel 只影响配置。
    • 认为自定义扩展不需要改配置就能用。
  • 30 秒口述稿:

Dubbo SPI 解决的是 JDK SPI 只能全量加载、没有名字、不能注入的问题。ExtensionLoader 按 META-INF/dubbo*/接口名 里的 name=实现类 加载,getExtension(name) 按需实例化并全局缓存。@SPI 标接口和默认名;@Adaptive 标在类上是手写自适应实现,标在方法上会生成 接口$Adaptive,从 URL 参数取扩展名再转发,所以 protocol=dubbo 就能决定用哪个 Protocol;@Activate 让 Filter 这类扩展按 group、value、order 自动激活排序。IoC 靠 ExtensionFactory/ExtensionInjector 注入,AOP 靠单参数构造器的 Wrapper 层层包装。

  • 3 分钟展开顺序:结论(按名 + 按需 + IoC + AOP)→ JDK SPI 的三个短板 → SPI 文件位置与格式 → ExtensionLoader 加载/缓存流程 → @SPI 与默认扩展 → @Adaptive 两种形态与代码生成 → @Activate 与 Filter 链 → Wrapper 与注入 → 自定义扩展落地步骤 → 常见故障与排查。