做Java开发几年的人多多少少都见过META-INF/services这个目录。第一次碰到它的时候里面就躺着一个文件名很长、内容却是普通文本的配置文件没有任何注释打开一看就一两行全限定类名看起来挺神秘。其实背后就是JDK原生提供的一套服务发现机制SPI全称Service Provider Interface服务提供者接口。SPI解决的是一个非常基础又棘手的问题接口在框架这边定义实现却分散在各方厂商或者业务模块里框架在编译期完全不知道具体有哪些实现但又希望在运行期让实现被自动发现、自动加载。JDBC驱动的加载、日志门面的桥接、各种开源框架的扩展点底层都是它。这篇文章我会把SPI的来龙去脉、内部原理、手写步骤和真实踩坑经历一次性讲清楚不管你是刚接触Java还是已经写过几年业务代码读完都能在项目里用起来。1. SPI机制到底是什么1.1 从一个最朴素的需求说起假设你在做一个搜索模块要支持不同的数据源。最开始最直接的做法就是在代码里写一堆if判断数据来自文件就走FileSearch来自数据库就走DatabaseSearch。每加一个数据源就要改一次主逻辑测试一轮发版一轮时间一长主流程全被分支塞满代码越来越难维护。有人会说用工厂模式不就完了工厂模式确实把创建逻辑收口到了单独的一个类里但工厂内部依然要把所有实现类的创建代码写死。真正的问题不在创建方式而在于搜索模块本身想把“到底有哪些搜索实现”这件事完全交出去让外部按需扩展。SPI就是为了应对这种需求出现的。这里可以打个生活化的比方。SPI就像是插座标准接口就是那个统一规格的插座面板实现方就是各种品牌的电器。插座厂商不需要在盖房子的时候就知道以后会插什么电器你只要按同一个标准去设计什么电器插进来都能用。SPI做的就是把这个“标准插座”用配置文件定义出来让所有符合规则的实现都能在运行期被插上。1.2 SPI中的三个角色一个标准的SPI机制通常有固定的三个角色理解了这三个角色后面所有细节都顺了服务接口由框架或者JDK定义用来描述一种能力。比如java.sql.Driver就是JDK定义好的服务接口任何数据库驱动都要实现它。服务提供者真正干活的类实现服务接口由第三方厂商或者业务方提供。比如某个数据库驱动包里一定有某个类实现了java.sql.Driver。服务加载器JDK提供的ServiceLoader类负责扫描配置文件、加载实现类并实例化。这是SPI机制的入口。三者配合起来的约定非常简单提供方在jar包的META-INF/services目录下创建一个文件文件名必须是服务接口的全限定名文件内容是实现类的全限定名每行一个。加载方通过ServiceLoader.load(接口.class)就能自动把这些实现全部找出来。整个机制的巧妙之处就在于它把“谁被加载”的控制权从代码里解耦出来放到一个纯文本文件里。1.3 SPI和API的本质区别很多人会把SPI和API搞混虽然都是接口但设计方向完全不同。API是系统对外提供的能力调用方去调它是“我给你提供服务”SPI是系统预留的扩展点由外部来填充实现是“我接受你的服务”。一个是别人用你的代码一个是你的代码用别人的插件方向刚好反过来。这直接导致了两者在绑定方式上的巨大差异。API在编译期就是确定的你依赖了某个库调它的接口编译时就能发现接口不存在而SPI在编译期根本不知道实现类长什么样只有运行期扫描到配置文件才会把类加载进来。用一张表对比一下维度APISPI服务方向我调你的代码你调我的实现绑定方式编译期显式依赖运行期按配置发现设计目的为调用者提供能力为实现者预留扩展位错误发现时机编译期就能发现运行期加载才发现典型例子JDBC里的Connection、StatementJDBC里的Driver实现理解这个区别之后再看任何框架代码你就能更清楚地判断这个接口是给外部调用者用的还是留给扩展点用的。方向对了SPI的很多设计细节也就顺理成章了。2. 从JDBC驱动加载看SPI的典型应用2.1 老版本的硬编码时代如果你写过早期JDBC代码一定对第一行不陌生Class.forName(某个数据库驱动类的全限定名)。当年很多教材的解释是“注册驱动”这行代码不写后面DriverManager.getConnection()就报错说不认识这个驱动。至于为什么刚开始根本没人讲清楚。原理其实不复杂。DriverManager内部维护了一个Driver列表但问题是它怎么知道这个列表里该有哪些驱动在SPI机制普及之前只能靠驱动类自己主动报到。你执行Class.forName类的静态代码块就会运行驱动在静态代码块里调用DriverManager.registerDriver()把自己注册进去。这一步不做DriverManager就是个空壳连接请求自然全部失败。这个方案的问题很明显。使用驱动的用户必须提前知道驱动类的完整包路径写死在代码里想换一个数据库这一行就必须改整个项目要重新编译。驱动之间有强绑定谈不上任何解耦。这还不是最难受的如果驱动类名写错了程序启动时不报错到真正获取连接那一步才炸排查起问题来很考验耐心。2.2 为什么要改成SPI后来JDBC引入了SPI机制驱动加载彻底变了个样子。数据库驱动的jar包里多了一个文件META-INF/services/java.sql.Driver文件内容就是驱动实现类的全限定名。用户在代码里不再需要手动Class.forName只要把驱动jar包放入classpathDriverManager在初始化的时候通过ServiceLoader扫描到那个文件驱动就自动注册好了。这个改进把驱动加载的主动权从用户手里转移到了机制本身。用户不需要关心驱动类叫什么名字也不用管它放在哪个包只要依赖里有这个jar一切自动完成。驱动厂商想改内部实现类名对用户完全透明不会影响任何代码。从框架设计的角度看这其实是JDK在给自己留扩展空间。JDBC是规范数据库驱动是实现规范方永远不可能预知市场上会出现哪些驱动又不能让用户手动维护一份全量驱动列表最好的方式就是让驱动实现方按约定自动上报。SPI这种“反向控制”的思路正好解决了这种多方参与的动态扩展问题。2.3 一个迷你流程串一下JDBC驱动通过SPI加载的过程剥开来看其实只有五步DriverManager的静态初始化代码运行。内部调用ServiceLoader.load(Driver.class)开始扫描classpath下的所有jar包。每个jar包里如果存在META-INF/services/java.sql.Driver文件就按行读取实现类名。反射加载实现类并创建实例实例创建时类的静态代码块执行DriverManager.registerDriver()完成注册。用户调用getConnection(url)时DriverManager遍历已注册的所有Driver按URL前缀匹配让匹配上的驱动去建立连接。第5步也很关键。当classpath里同时存在多个数据库驱动时DriverManager不知道该用谁只能逐个去尝试谁认识这个jdbc:xxxx://格式的URL谁就接手。这也是为什么多个驱动共存不乱套的原因靠的是URL前缀的区分度。早期代码里那行Class.forName其实在新机制下已经显得多余写上去最多是让驱动再重复注册一次DriverManager有保护机制不会产生影响。很多老程序员习惯了写一行保留也无伤大雅。3. SPI机制的核心原理拆解3.1 ServiceLoader的工作流程ServiceLoader是整个JDK SPI机制的核心。不看源码可能觉得它很玄其实它的工作流程简单得让人意外给定一个服务接口扫描classpath下所有META-INF/services/接口全限定名文件把文件里每一行当作实现类的全限定名然后做三件事加载类、实例化、存起来。比如你写ServiceLoader.load(Search.class)它实际做的事情是拿到当前线程的上下文类加载器作为默认加载器。前往所有类加载路径下寻找META-INF/services/com.example.spi.Search这个文件。解析文件内容得到一个实现类名的列表。提供迭代器让调用方遍历这些实现类的实例。这里有一个几乎所有教程都会提到的关键点为什么ServiceLoader要用线程上下文类加载器而不是自己的类加载器原因和Java的双亲委派机制有关。ServiceLoader本身由JVM核心类加载器加载而SPI的实现类通常躺在应用的classpath里。按照双亲委派的逻辑核心类加载器能看到的类很有限直接用它去加载应用里的实现类大概率抛ClassNotFoundException。线程上下文类加载器打破了这种限制让框架层可以拿到应用层的类加载能力。这个设计是整个SPI能用起来的地基。3.2 源码级别的三步走直接看ServiceLoader源码会发现内部实现比自己想象的朴素。整个加载过程可以浓缩成三步reload()清空上次缓存的Provider创建一个LazyIterator。hasNext()LazyIterator从配置文件中找到下一个实现类全限定名找到了就往下走找不到就结束。next()根据类名用Class.forName()加载类然后调用newInstance()创建实例放进缓存。重点在那个LazyIterator上。ServiceLoader在加载的时候并不会一口气把所有实现类全部实例化而是在你调用迭代器的hasNext()和next()时才真正触发加载。这样做的价值很明显一个大型项目里可能有几十个驱动实现但实际运行的也许只有两三个全量加载既浪费内存又拖慢启动速度。懒加载模式让消耗按需发生这也是框架设计里常见的取舍。从JDK 9开始内部实现更复杂了一点增加了模块系统相关的处理但核心三步并没有变解析配置、加载类、实例化。理解这个底层逻辑排查问题的时候就不会慌因为它能出问题的地方就那么几处。3.3 实例缓存和顺序问题ServiceLoader有一个容易被忽略的行为同一个ServiceLoader实例同一个实现类只实例化一次后续迭代返回的都是同一个对象。这个细节决定了你不能把有状态的东西随意塞进SPI实现里因为多个调用方拿到的可能是共享实例。另一个问题是迭代顺序。配置文件里写了几个实现类迭代时基本就是按文件中的行顺序返回。但Java规范并没有明确保证顺序依赖配置文件行序做逻辑判断是很危险的做法。我见过有人利用配置文件顺序做“主从切换”结果某个打包工具重排了文件内容线上行为直接变了。正确的做法是给实现类增加优先级信息加载后自己排序而不是指望配置文件顺序稳定。3.4 与类加载器机制的关系再补充一点双亲委派和线程上下文类加载器这两个概念很多面试题喜欢和SPI放到一起考。简单总结一句话SPI打破了类加载方向的限制。双亲委派是自下而上委托加载SPI服务加载是让上层框架去扫描和加载下层的实现类两者天然冲突于是JDK提供了线程上下文类加载器作为桥梁。理解了这个冲突你就知道了为什么线程上下文类加载器在Web容器、插件化系统中出现频率那么高。4. 手写一个SPI Demo从接口到实现4.1 准备一个Maven项目结构光说不练永远是纸上谈兵SPI这东西10分钟就能跑通。先准备一个简单的Maven项目目录结构如下spi-demo/ ├── src/main/java/ │ ├── com/example/spi/Search.java │ ├── com/example/spi/FileSearch.java │ ├── com/example/spi/DatabaseSearch.java │ └── com/example/Main.java └── src/main/resources/ └── META-INF/services/ └── com.example.spi.Search这里有一个新手最容易踩的坑META-INF/services目录必须放在src/main/resources下打包时才会被识别为资源目录并进入jar包。如果手一抖建在了src/main/java下源码目录里的文件虽然编译期能看到打包后却直接消失运行期怎么都找不到。这个坑我当年踩过一次排查了整整半天。4.2 定义接口和实现类先定义一个Search接口它是整个机制的服务接口package com.example.spi; public interface Search { String search(String keyword); }然后写两个实现类分别代表不同的搜索来源package com.example.spi; public class FileSearch implements Search { Override public String search(String keyword) { return FileSearch: keyword; } }package com.example.spi; public class DatabaseSearch implements Search { Override public String search(String keyword) { return DatabaseSearch: keyword; } }实现类有一个非常容易忽略的硬性要求必须提供公开的无参构造方法。ServiceLoader通过反射创建实例它没有办法帮你处理构造参数。如果你在里面只写了一个有参构造运行期会直接抛InstantiationException。很多框架里实现类需要依赖注入也不是靠SPI直接完成的往往是SPI先创建对象再通过额外的字段注入或者setter方法补充依赖这一点在写自己的框架时要特别注意。4.3 配置文件写法与关键坑在src/main/resources/META-INF/services/下创建文件文件名必须是接口的全限定名也就是com.example.spi.Search注意不是实现类的名字。文件内容如下com.example.spi.FileSearch com.example.spi.DatabaseSearch这个文件的要求看起来简单实际坑不少。首先是名字花了十分钟确认接口名和文件名完全一致是很多初学者的必修课。其次是内容每行一个实现类全限定名行与行之间不要有多余的空格文件末尾允许有换行但不要用带BOM的UTF-8编码保存BOM会导致第一行类名解析失败。#开头的行会被当作注释忽略可以利用这个特性在配置文件里写点说明。还有一个容易忽略的点不要引入Windows记事本那种自动转码的编辑器设置。纯文本文件看着没问题一旦带有不可见字符坑起来非常隐蔽。4.4 加载和运行加载代码非常简单一个ServiceLoader就能搞定package com.example; import com.example.spi.Search; import java.util.ServiceLoader; public class Main { public static void main(String[] args) { ServiceLoaderSearch loader ServiceLoader.load(Search.class); for (Search search : loader) { System.out.println(search.search(test)); } } }运行这段代码输出结果取决于配置文件里的顺序。当前配置是先FileSearch后DatabaseSearch输出就是这样FileSearch: test DatabaseSearch: test如果你把配置文件顺序对调输出顺序也会跟着变。只保留一行配置系统就只会加载那一个实现整个机制完全由配置驱动。这也是SPI最吸引人的地方新增实现不用改主代码往classpath里塞一个jar包配置好文件实现就会自动出现。4.5 更进一步带优先级的自定义方案原生ServiceLoader不提供按名字或者按优先级选择实现的能力它只给你一个全量迭代器选择逻辑要你自己写。实际项目里我常用的做法是定义一个Order注解放在实现类上package com.example.spi; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; Retention(RetentionPolicy.RUNTIME) Target(ElementType.TYPE) public interface Order { int value() default 0; }加载完所有实现后通过反射读取注解值按升序排好再使用。这套逻辑虽然要用反射但胜在简单可控不引入额外依赖。真实的框架里比如Dubbo的扩展机制往往会提供更完善的选择方法后面我会专门讲。5. 主流框架中的SPI变形与生态5.1 JDK SPI不够用的地方在哪JDK自带SPI很轻量但真把它用到框架里会发现几个明显的短板。第一全量加载。你想要哪个实现也得把所有实现全遍历一遍框架没有提供选择器。第二失败不隔离。遍历过程中一个实现类构造抛异常迭代直接中断后续实现全受影响。第三不支持参数。比如你要给实现传构造参数原生机制做不到。第四没有名字概念。配置里只有全限定名无法通过一个短名字定向获取某个实现。这些短板直接催生了一大批增强版的SPI实现最典型的就是Dubbo的扩展机制和Spring Boot的自动装配机制。理解JDK SPI之后再去看它们你会发现核心套路一模一样只是做了不少增强。5.2 Dubbo的ExtensionLoader做了什么不一样的事Dubbo里也有一套SPI入口叫ExtensionLoader。它的配置文件名依然是接口全限定名但文件内容格式从纯类名列表变成了keyvalue形式比如filecom.example.spi.FileSearch databasecom.example.spi.DatabaseSearchExtensionLoader.getExtension(database)能直接按key精准获取实现。这种方式解决了JDK SPI“想用一个必须遍历所有”的尴尬。它还支持Adaptive注解做自适应扩展也支持扩展实现之间的依赖注入能力比原生SPI丰富太多。它的实现原理本质还是META-INF/services目录加类扫描只是在类加载和实例管理上做了更多细节控制。对于一个要支持大量扩展点的框架来说这种精确控制很有必要。Dubbo的协议、序列化、负载均衡策略全靠这种机制支撑没有这种可控的选择能力框架根本做不到按需装配。5.3 Spring Boot的自动配置加载Spring Boot 2.7之前自动配置类的加载入口是META-INF/spring.factories文件里面是keyvalue的Map结构其中一个key是org.springframework.boot.autoconfigure.EnableAutoConfiguration。2.7开始Spring Boot推荐使用META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports格式变成每行一个自动配置类全限定名反而跟JDK SPI更像了。这套机制的底层是SpringFactoriesLoader同样是在classpath下扫描固定路径的配置文件按类名加载并注册到Spring容器。区别在于Spring引入了条件注解ConditionalOnClass、ConditionalOnMissingBean这些条件能让加载过程更有谱满足条件才装配避免冲突。JDK SPI是“全量加载自己判断”Spring是“条件匹配按需装配”设计取向上差异明显。5.4 一个通用规律把JDK SPI、Dubbo SPI、Spring Boot自动配置放在一起看底层逻辑高度一致接口定义能力配置文件描述实现加载器在运行期扫描并实例化。区别只是配置格式、加载时机、实例管理策略不同。掌握了JDK SPI等于拿到了理解这种扩展机制的基础钥匙后面不管遇到什么新框架先找它的配置文件路径和加载器入口基本就能摸清七成原理。6. 实操中的常见问题与避坑经验6.1 配置文件存在却没生效这是SPI问题里最高频的一个。代码看着一点问题没有配置也写了运行起来实现就是加载不出来。排查的时候我习惯先问三个问题文件名是不是接口的全限定名写错成实现类名是新手最容易犯的错。文件有没有真正进到jar包里打开最终的jar包看META-INF/services目录下有没有这个文件没有就去检查构建配置。是不是存在多个同名配置文件多模块项目里依赖树里可能有多个jar都带同一个服务配置文件这时候要确认扫描到的到底是哪一个。排查手段其实就一句话解压jar看文件名看文件内容。SPI的机制很透明配置文件一旦正确结果几乎是确定的。怕就怕在构建工具把resources目录漏掉了或者使用IDE的时候自动拷贝了过期版本的文件。6.2 实现类加载失败很常见但容易忽略如果运行时报ClassNotFoundException或者NoClassDefFoundError问题大概率不在SPI配置而在实现类本身的依赖。实现类里引用了一个第三方库但这个库没有被classpath覆盖类加载就会失败。这种情况在插件化开发里特别常见因为插件jar和应用主classpath不总是一致。另外还要检查实现类的可见性。实现类必须是public的构造方法也必须是public无参的否则反射创建实例一样会失败。这些错误往往在启动阶段不明显等到迭代器遍历到对应实现时才爆出来加上日志输出位置离实际触发点比较远排查起来要耐心。6.3 多线程场景下的载入器实例管理ServiceLoader内部不是线程安全的。多个线程同时共享同一个ServiceLoader实例并各自遍历时迭代器状态可能会错乱表现就是偶发性的少拿一个实现或者多拿一个实现。我不建议在静态字段里存一个全局共享的ServiceLoader然后到处用更好的做法是每次需要时重新load一个实例或者至少给遍历操作加上同步控制。从性能角度说ServiceLoader的加载过程有搜索文件名的过程频繁创建会有系统开销但使用锁的成本在低并发场景下也未必更低。我一般习惯在启动阶段一次性加载并封装成一个不可变列表后续只读使用既避免线程安全问题又把性能开销控制在启动阶段。6.4 多个实现的排序与选择真的别偷懒JDK SPI原生没有排序保证也不提供选择机制。Spring Boot的自动配置可以用条件注解控制装配Dubbo的ExtensionLoader可以用key精确定位但这些能力都不属于JDK SPI。如果你只是把一个接口的所有实现全部加载并依次处理那顺序就无所谓如果业务里有“主实现”“备实现”的概念一定要自己实现优先级策略。我之前看到一个项目把META-INF/services文件里的行顺序当作主备顺序上线一直没问题直到某个同事重构打包脚本后行为开始随机。这种隐式约定本质上是在赌构建工具的行为风险太大。老老实实加一个Order注解加载后排序问题才能从根上解决。6.5 什么时候该用SPI我的判断标准写了不少实战内容最后聊聊这个机制在真实项目里该怎么用。要不要引入SPI我的判断标准很简单看扩展方和实现方是不是同一个团队、同一个代码仓。如果你是做框架、中间件、SDK需要允许使用方在外部扩展自己的实现SPI几乎是必然选择。比如你定义一个消息发送接口让不同业务方各自实现并接入SPI省掉了很多协调成本。如果你的库发布出去要被别人集成预留SPI扩展点更是基本素养。反过来如果是项目内部的不同模块之间SPI能给但也能不给。内部模块之间的解耦有接口加依赖注入就能解决再有控制反转容器的帮忙硬套SPI反而会让项目复杂化。特别是你只有一个实现时引入SPI配置文件纯属多余。我个人的体会是SPI就像一把工具贵在拿捏分寸。框架里一定要用业务代码里能少用就少用。否则维护成本从代码转移到了配置文件排查问题多了一个环节并不划算。最后再分享一个小技巧。排查SPI问题时我最常用的一招是在启动参数里加上-Djava.system.class.loader...或者直接在主程序启动时打印当前类路径然后把涉及SPI的jar包用解压工具逐个打开看配置文件是否真的存在。SPI这种机制几乎没有黑魔法配置文件在类在构造方法在它就能跑起来。顺着这个思路排查绝大多数问题五分钟之内都能定位。这套机制简单归简单但它背后的“接口与实现解耦”思想才是真正值得反复琢磨的东西。