Appearance
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的原因。分层要点:
- 先说 JDK SPI 的三个短板:只能全量加载(
ServiceLoader迭代即实例化)、没有扩展名(无法按配置选实现)、没有依赖注入和包装(实现类之间无法组合)。Dubbo 要在运行时按 URL 选Protocol/Cluster/LoadBalance,还要给 Filter 排序、给扩展注入 Spring Bean,所以自己实现了一套。 - 加载入口是
ExtensionLoader:静态缓存EXTENSION_LOADERS(接口 → loader)、EXTENSION_INSTANCES(实现类 → 单例);每个 loader 缓存cachedClasses(name → Class)、cachedNames(Class → name)、cachedAdaptiveClass、cachedWrapperClasses、cachedActivateClasses。同一个扩展名全局只实例化一次。 - SPI 文件有三个位置:
META-INF/dubbo/internal/<接口全限定名>(Dubbo 内置)、META-INF/dubbo/<接口全限定名>(用户扩展)、META-INF/services/<接口全限定名>(兼容 JDK SPI)。内容格式是name=com.foo.BarImpl,不是 JDK 的一行一个类名。 @SPI声明“这是扩展接口 + 默认实现名”:如@SPI("javassist")表示默认javassist;getDefaultExtension()走默认名,getExtension(name)走指定名,getSupportedExtensions()只返回名字不实例化。@Adaptive解决“运行时才知道用哪个实现”:标在类上,表示这个类就是自适应实现(如AdaptiveExtensionFactory、AdaptiveCompiler);标在方法上,ExtensionLoader会用AdaptiveClassCodeGenerator生成接口名$Adaptive类,方法体从URL参数取扩展名再getExtension(name)转发。Dubbo 里Protocol、ProxyFactory、Cluster、LoadBalance、RegistryFactory都是方法级@Adaptive。@Activate解决“哪些扩展默认生效”:Filter/Listener 这类扩展不需要调用方按名选,而是按group(provider/consumer)、value(URL 参数开关)、order(顺序)、before/after自动装配。getActivateExtension(url, key, group)会过滤 + 排序,ProtocolFilterWrapper就是靠它把 Filter 链织到 Invoker 上。- IoC 与 AOP 是 Dubbo SPI 的两个增强:IoC 通过
ExtensionFactory(2.x)/ExtensionInjector(3.x)在injectExtension时给 setter 注入其他扩展或 Spring Bean;AOP 通过 Wrapper 类(构造函数只有一个参数,类型是 SPI 接口)实现,getExtension返回的是被所有 Wrapper 包过的实例——ProtocolFilterWrapper、ProtocolListenerWrapper、QosProtocolWrapper都是这么织进去的。 - 排障要按“文件 → 注解 → 名字 → 类加载器”顺序:SPI 文件路径/文件名错 → 接口没标
@SPI→ 实现没实现接口 →getExtension("xxx")名字拼错 → 容器里 TCCL 不对。报错通常是IllegalStateException: No such extension或IllegalArgumentException: ... is not an extension,不会在编译期暴露。
- 先说 JDK SPI 的三个短板:只能全量加载(
图/流程:
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/。
- 2.7.x:
JDK SPI vs Dubbo SPI:
| 维度 | JDK SPI | Dubbo 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 |
@DisableInject | setter | 跳过注入 | 避免误注入 |
@Activate属性:
| 属性 | 含义 | 示例 |
|---|---|---|
group | provider/consumer/all | group = {PROVIDER, CONSUMER} |
value | URL 参数开关名,空数组表示总是激活 | value = "accesslog" |
order | 顺序,越小越靠前 | order = -10000 |
before | 排在指定扩展名之前 | before = "monitor" |
after | 排在指定扩展名之后 | after = "context" |
- 常见扩展点:
| 接口 | 默认实现 | 选择方式 |
|---|---|---|
Protocol | dubbo | URL protocol |
ProxyFactory | javassist | URL proxy |
Cluster | failover | URL cluster |
LoadBalance | random | URL loadbalance |
RegistryFactory | 按地址协议 | URL protocol(zookeeper/nacos) |
Serialization | hessian2 | URL serialization |
Dispatcher | all | URL dispatcher |
ThreadPool | fixed | URL threadpool |
Filter | 多个,@Activate | group + value + order |
Compiler | javassist | AdaptiveCompiler |
- 失效场景与定位:
| 现象 | 根因 | 处理 |
|---|---|---|
No such extension xxx | SPI 文件没写/名字拼错/目录不对 | 检查文件与 name= |
is not an extension | 接口没标 @SPI | 补注解 |
| 自定义 Filter 不生效 | 没加 @Activate 或 group 不匹配 | 补注解、确认 provider/consumer |
| Wrapper 没生效 | 构造函数不是“单参数且为 SPI 接口” | 调整构造器 |
| 自适应类创建失败 | 没有 @Adaptive 方法/无法从参数取 URL | 检查方法签名与注解 |
@Adaptive 取不到扩展名 | URL 参数 key 写错/参数为 null | 对齐 @Adaptive(value) 与 URL |
| 注入为 null | setter 不是 public/参数类型不是扩展 | 改 setter 或 @DisableInject |
| 容器内加载失败 | TCCL 不是应用类加载器 | 指定 classloader/排查隔离 |
| 同名扩展被覆盖 | 多个 jar 写了同名 | 统一命名、排除冲突 jar |
| 单测互相污染 | ExtensionLoader 静态缓存 | 隔离用例/重置缓存 |
深挖点(面试官常追的 6 个):
- 为什么要自己实现 SPI:Dubbo 的核心诉求是“同一个接口,按配置/URL 选不同实现”,JDK SPI 只能全量加载且没有名字;同时 Dubbo 需要给扩展注入 Spring Bean(
SpringExtensionFactory)、需要 Wrapper 做 AOP(Filter、Listener)、需要@Activate给 Filter 排序。这四点 JDK SPI 都不支持,所以有了ExtensionLoader。 ExtensionLoader的加载与缓存:getExtensionLoader先查静态EXTENSION_LOADERS;getExtension(name)先getExtensionClasses()扫描三个目录,loadClass时按“类上有@Adaptive→ 自适应类;构造器单参数是接口 → Wrapper;否则按 name 缓存”分类;实例化后injectExtension注入 setter,再用 Wrapper 逐层包,最后按Lifecycle初始化;实例放EXTENSION_INSTANCES,同名扩展全局单例。@Adaptive的两种形态:类级@Adaptive是手写的自适应实现(AdaptiveExtensionFactory在运行时决定用 SPI 还是 Spring 的工厂);方法级@Adaptive由AdaptiveClassCodeGenerator生成源码,再交给Compiler(默认 Javassist)编译。生成逻辑是:从方法参数里找URL(直接是 URL,或有getUrl()的 Invoker),用@Adaptive(value)的 key 取扩展名,getExtension后转发;找不到 URL 或扩展名就抛异常。@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才启用”。- IoC 和 AOP 怎么实现:IoC 是
injectExtension遍历 setter,用ExtensionFactory(3.xExtensionInjector)按参数类型和属性名找扩展或 Spring Bean 注入;AOP 是 Wrapper:类有一个“参数类型为 SPI 接口”的构造器就被识别为 Wrapper,getExtension时new Wrapper(instance)层层包裹。Wrapper 不能按名字获取,只参与包装;多个 Wrapper 的嵌套顺序取决于集合迭代,不要依赖具体顺序。 - 自定义扩展怎么落地:实现接口 → 在
META-INF/dubbo/<接口全限定名>写myext=com.foo.MyImpl→ 接口有@SPI且方法有@Adaptive(或调用方显式getExtension("myext"))→ 配置里写protocol=myext/cluster=myext等。Filter 还要加@Activate。排障先确认文件在不在、名字对不对、TCCL 能不能读到。
- 为什么要自己实现 SPI:Dubbo 的核心诉求是“同一个接口,按配置/URL 选不同实现”,JDK SPI 只能全量加载且没有名字;同时 Dubbo 需要给扩展注入 Spring Bean(
追问链:
- Dubbo SPI 和 JDK SPI 区别? → 按名加载、按需实例化、IoC、AOP、激活排序。
- SPI 文件放哪? →
META-INF/dubbo/internal/、META-INF/dubbo/、META-INF/services/。 - 文件格式? →
name=实现类全限定名。 - JDK SPI 文件格式? → 一行一个类名。
- 为什么 JDK SPI 不够? → 全量加载、无名字、无注入、无包装。
ExtensionLoader怎么拿? →getExtensionLoader(接口.class),静态缓存。- 扩展实例什么时候创建? →
getExtension(name)时,按需。 - 扩展是单例吗? → 是,全局缓存。
@SPI作用? → 标记扩展接口 + 默认实现名。- 默认扩展怎么取? →
getDefaultExtension()。 getSupportedExtensions会实例化吗? → 不会,只返回名字。@Adaptive标在类上? → 该类就是自适应实现。- 标在方法上? → 动态生成
$Adaptive类。 - 生成类怎么选实现? → 从 URL 参数取扩展名。
- URL 从哪来? → 方法参数里的
URL或Invoker.getUrl()。 - 取不到 URL 会怎样? → 抛异常。
@Adaptive的 value 是什么? → URL 参数 key 数组。- 不写 value 呢? → 按接口名推导参数 key。
- 生成代码靠什么编译? →
CompilerSPI,默认 Javassist。 Protocol是自适应扩展吗? → 是,export/refer方法级@Adaptive。AdaptiveExtensionFactory做什么? → 类级自适应,运行时选 SPI/Spring 工厂。@Activate作用? → 自动激活并排序。@Activate的 group? → provider/consumer/all。@Activate的 value? → URL 参数开关。@Activate的 order? → 越小越靠前。- before/after 呢? → 相对其他扩展排序。
- Filter 怎么自动生效? →
@Activate+ SPI 文件 +ProtocolFilterWrapper。 - Filter 链顺序谁定? →
ActivateComparator。 - Wrapper 是什么? → 单参数构造器、参数为 SPI 接口的包装类。
- Wrapper 能按名取吗? → 不能,只参与包装。
- Wrapper 有什么用? → AOP,如 Filter/Listener/Qos。
- IoC 怎么注入? →
injectExtension+ExtensionFactory/ExtensionInjector。 - 能注入 Spring Bean 吗? → 能,
SpringExtensionFactory/SpringExtensionInjector。 - 注入失败会怎样? → 属性为 null,通常不报错。
@DisableInject干什么? → 跳过注入。- 扩展实现
Lifecycle会怎样? → 创建后调initialize()。 - 扩展缓存会串测试吗? → 会,静态缓存需要隔离。
- 类加载器问题? → 用 TCCL/指定 loader,容器里常见。
- 同名扩展冲突? → 按加载顺序,需排除冲突 jar。
- 怎么自定义
Protocol? → 实现 + SPI 文件 + 配protocol=xxx。 - 怎么自定义
Cluster? → 实现 + SPI + 配cluster=xxx。 - 怎么自定义
LoadBalance? → 实现 + SPI + 配loadbalance=xxx。 - 怎么自定义序列化? → 实现
Serialization+ SPI + 配serialization=xxx。 - 怎么自定义线程池? → 实现
ThreadPool+ SPI + 配threadpool=xxx。 @Adaptive能用在构造器吗? → 不能,只支持类和方法。- Dubbo 3 有什么变化? →
ExtensionDirector/ScopeModel、ExtensionInjector。 ScopeModel解决什么? → 多应用/多模块隔离,扩展按作用域管理。- 和 Spring 的 SPI 区别? → Spring 是
spring.factories接口→列表,无命名/自适应/激活。 - 怎么排查扩展不生效? → 文件 → 注解 → 名字 → group → TCCL。
- 面试怎么总结? → 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 与注入 → 自定义扩展落地步骤 → 常见故障与排查。