← 课程目录 🚀 从零到一
📐 学习维度 阶段7 · 第28章 开源项目源码精读 🚀 从零到一 📚 课程目录 🏠 首页 🛤️ 学习路径

28.2.3 Dubbo SPI:插座哲学与 @Adaptive、Wrapper

审校 2026-09-26 · 素材来源:zcode会话#1《Dubbo+Zookeeper 学习Demo与教程》
📑 本篇章节导航 (共8节,点击直达)
场景:换序列化器为什么不用改代码和 JDK SPI 的区别:JDK 是开灯点亮整栋楼@Adaptive:编译期不知道用哪个,运行期看参数Wrapper:自动套上的洋葱皮Filter:业务最常写的扩展什么时候轮到你写扩展踩坑清单面试怎么问

Dubbo 源码里到处是 PROTOCOL.export(...)、getExtension("dubbo") 这样的调用。看不懂 SPI,Dubbo 源码一页都读不下去。这篇讲清三件事:SPI 是什么、@Adaptive 和 Wrapper 各干什么、什么时候轮到你写扩展。

前置阅读:16.7 用过 Dubbo 的扩展能力。这篇读 SPI 源码,看插座哲学怎么落地。

场景:换序列化器为什么不用改代码

prefer.serialization=hessian2,fastjson2——配置一改,报文编码就换了。Dubbo 自己没写 if-else 判断用哪个序列化器,它只是留了个插座,谁来插由配置决定。

SPI(Service Provider Interface,按名字动态加载实现类的扩展机制)一句话:写类 → 登记 → 用外号取。


① 写实现类:class TimingProtocolWrapper implements Protocol {...}
② 登记:META-INF/dubbo/org.apache.dubbo.rpc.Protocol 文件里加一行
   timing=org.demo.TimingProtocolWrapper
③ 取用:getExtensionLoader(Protocol.class).getExtension("timing")

和 JDK SPI 的区别:JDK 是开灯点亮整栋楼

JDK 原生 SPI(ServiceLoader)一次把配置文件里的实现全部实例化——你只要一个,它点亮整栋楼。Dubbo SPI 按名字按需加载一个,还支持依赖注入和自适应。

能力JDK SPIDubbo SPI
按名取实现不支持支持
懒加载否是
IoC 注入无扩展点之间互相注入

IoC 注入展开一句:扩展点实例化后,Dubbo 扫它的 setter 方法,参数类型是别的扩展点就递归取来注入——扩展点之间能组装成网,不只是并列的列表。Cluster 里注入 LoadBalance、LoadBalance 里再注入,就是这么织起来的。

@Adaptive:编译期不知道用哪个,运行期看参数

@Adaptive(自适应扩展,运行期根据参数动态选实现的机制)解决的问题:Protocol 有 dubbo、injvm、registry 好几个实现,代码里写死哪个都不对——要等调用时看 URL 里的 protocol= 参数才知道。

Dubbo 的做法是运行时生成一个代理类(名字形如 Protocol$Adaptive),它的方法体就干一件事:从参数里取协议名,再去 getExtension 查真正的实现。所以 PROTOCOL.export(invoker) 这行代码里的 PROTOCOL,永远是个「看菜下饭」的代理。

把代理的方法体展开看(伪代码,每次调用都现查 URL):


public class LoadBalance$Adaptive implements LoadBalance {
    public <T> Invoker<T> select(List<Invoker<T>> invs,
            URL url, Invocation inv) {
        String name = url.getMethodParameter(
            inv.getMethodName(), "loadbalance", "random");
        return getExtensionLoader(LoadBalance.class)
            .getExtension(name).select(invs, url, inv);
    }
}

你写 @DubboReference(loadbalance = "first"),运行期就是这个代理在替你查表转发。验证方法也简单:断点打进自定义负载均衡器的 select,调用栈里那帧 LoadBalance$Adaptive 查无源码——它是 JIT 出来的。

注解位置的冷知识:@Adaptive 标方法上才是 JIT 动态生成;标类上是手写实现类直接顶上、不再生成(官方 AdaptiveExtensionFactory 就是类上标注)。两者互斥,类上有标注时方法上的不生效。

URL 参数从哪塞进去

自适应选路读的是 URL 参数,参数有四个来源:引用注解的 parameters、方法注解、全局 yml 的 dubbo.consumer.parameters、服务端注册 URL。最常用的是第一种:


@DubboReference(version = "1.0.0",
    parameters = {"rateLimiter.type", "tokenBucket"})
private UserService userService;   // 运行期据此选令牌桶实现

Wrapper:自动套上的洋葱皮

Wrapper(包装类,构造器入参是同接口的扩展点包装机制)的规则:实现类的构造器参数恰好是本接口类型,就被认为是 Wrapper,加载时自动把别的实现包起来。

机制比想象中粗暴:ExtensionLoader 加载任何扩展时都扫一遍 SPI 注册表,发现某个类「长得像插座」,就把它当装饰器套上去——不管你要的是哪个插头,套的都是同一圈 Wrapper。


// 1. 写包装类:构造器参数是 Protocol 本身
public class TimingProtocolWrapper implements Protocol {
    private final Protocol inner;  // 被包着的真身
    public TimingProtocolWrapper(Protocol inner) { this.inner = inner; }
    public <T> Exporter<T> export(Invoker<T> invoker) {
        long t = System.currentTimeMillis();
        return inner.export(invoker);          // 前后加计时
        // log 耗时...
    }
}
// 2. SPI 文件登记一行(无名字要求,但要登记)
// 3. 此后 getExtension("dubbo") 返回的不是裸 DubboProtocol,
//    而是 TimingProtocolWrapper(ProtocolFilterWrapper(...(DubboProtocol)))

onion 效果由 SPI 文件里的声明顺序决定,层层嵌套。Dubbo 内置的 Filter 链、序列化检查、QoS 都是这么套上去的——这也是为什么你看 DubboProtocol 源码找不到 Filter 逻辑:它在洋葱的外层,不在核里。

Filter:业务最常写的扩展

Filter(过滤器,拦截每次 RPC 调用的扩展点)像安检传送带:请求进出各过一遍。链路追踪埋 traceId、鉴权、加解密、耗时打点,全在 Filter 里做。


@Activate(group = {CommonConstants.CONSUMER})  // 消费端自动激活
public class TraceIdFilter implements Filter {
    public Result invoke(Invoker<?> invoker, Invocation inv)
            throws RpcException {
        String traceId = MDC.get("traceId");
        if (traceId != null) {
            inv.setAttachment("trace-id", traceId);  // 塞进附件随请求走
        }
        return invoker.invoke(inv);                  // 放行
    }
}

登记进 org.apache.dubbo.rpc.Filter 文件即生效。第三方组件就是这么接入 Dubbo 的:Sentinel 插 Filter 做限流、Seata 靠附件透传 xid、SkyWalking 用 Agent 字节码增强。Dubbo 不造生态,只开插槽。

什么时候轮到你写扩展

分两个视角看,大多数人只在「使用者」那一栏:

情形@AdaptiveWrapper
日常业务开发只用不写(配置切行为)只用不写(享受 Filter 链)
自研治理组件定义扩展点让配置可切时写给官方组件无侵入加横切逻辑时写

常用扩展点对照:每次调用埋点/鉴权/加解密写 Filter;换负载均衡写 LoadBalance;同城优先这类自定义选址写 Router;换注册中心写 RegistryFactory。

分工一句话:@Adaptive 解决「选哪个插头」,Wrapper 解决「插头外面包几层皮」——选择权和增强权分离,这是 Dubbo SPI 比 JDK SPI 强出来的两块肌肉。

还有一层容易忽略的价值:SPI 是依赖倒置的工程化形态。框架定义接口(高层策略),扩展方提供实现(低层细节),框架源码不 import 任何具体实现。对比「本地写两个类再 if-else」:if-else 要改框架代码才能加分支,SPI 只要丢个 jar 加一行登记——对修改关闭,对扩展开放在这里不是口号。

踩坑清单

面试怎么问

「Dubbo SPI 和 JDK SPI 区别?」——答:JDK 一次性全量实例化,Dubbo 按名懒加载、支持 IoC;@Adaptive 在运行期按 URL 参数选实现;Wrapper 构造器注入同接口实现、按声明顺序层层包裹,Filter 链就是这么挂上去的。

追问「Filter 怎么被装上的」——不是手工 new 的:ProtocolFilterWrapper 在 refer/export 时调 buildInvokerChain,按 SPI 注册表里 @Activate 的声明顺序把 Filter 织成链。所以给 Dubbo 加横切能力从来不用改框架源码,登记一行就是。

追问「为什么框架源码里找不到 Filter 逻辑」——因为 Filter 链是 ProtocolFilterWrapper 在 refer/export 时用 SPI 装配的洋葱皮,不在 DubboProtocol 核心里。看懂这一层,才算摸到 Dubbo 源码的门。

一句话总结:SPI 是插座,@Adaptive 是看菜下饭的选插座器,Wrapper 是自动套上的洋葱皮。