如何自定义一个Spring Boot Starter

如何自定义一个 Spring Boot Starter从零封装一个自己的自动配置本文基于 Spring Boot 2.7 / 3.x核心原理通用一、从一个真实场景说起最近咱们团队在做内部工具链建设好几个项目都要集成统一的日志追踪功能——每个请求进来自动在 MDC 里塞一个traceId然后打印到日志里。我一开始的做法很原始每个项目 copy 一份TraceFilterTraceInterceptor再 copy 一份配置类。 copy 到第三个项目的时候我忍不住了“这玩意儿能不能像spring-boot-starter-web一样加个依赖就自动生效”能。这就是Spring Boot Starter要干的事。说白了Starter 就是 Spring Boot 的**即插即用插件机制**。今天咱们就从一个具体需求出发手把手封装一个自己的 Starter。二、Starter 到底是什么先搞清楚原理2.1 一句话解释Starter 本质上是一个普通的 Maven/Gradle 模块核心就做两件事引入你需要的依赖比如你的工具类、第三方 SDK自动配置好这些组件通过Configuration 条件注解用户只需要在pom.xml里加一行dependencygroupIdcom.example/groupIdartifactIdmy-trace-spring-boot-starter/artifactIdversion1.0.0/version/dependency然后啥也不用干功能就自动生效了。这就是“约定优于配置”的体现。2.2 自动配置的底层机制Spring Boot 启动时会扫描META-INF/spring.factoriesBoot 2.7 之前或META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.importsBoot 2.7文件里面列的类会被自动加载为配置类。┌─────────────────┐ │ 应用启动 │ │ SpringBootApp │ └────────┬────────┘ │ ▼ ┌─────────────────────────────┐ │ 读取 META-INF/spring/*.imports │ │ 找到所有 AutoConfiguration │ └────────┬────────────────────┘ │ ▼ ┌─────────────────────────────┐ │ 条件判断ConditionalOnXxx │ │ 满足条件才生效 │ └────────┬────────────────────┘ │ ▼ ┌─────────────────────────────┐ │ 读取 application.yml 配置 │ │ EnableConfigurationProperties│ └────────┬────────────────────┘ │ ▼ ┌─────────────────────────────┐ │ 注册 Bean 到 Spring 容器 │ │ 功能生效 │ └─────────────────────────────┘你看整个流程就是发现配置 → 条件筛选 → 读取配置 → 注册 Bean。咱们自定义 Starter就是在这些环节里填空。三、实战封装一个 TraceId Starter咱们要做一个my-trace-spring-boot-starter功能很简单自动给每个 HTTP 请求生成traceId把traceId放到 MDC 里日志就能打印出来支持通过application.yml配置是否开启、以及 traceId 的请求头名称3.1 项目结构my-trace-spring-boot-starter/ ├── pom.xml └── src/ └── main/ ├── java/ │ └── com/example/trace/ │ ├── MyTraceAutoConfiguration.java # 自动配置类核心 │ ├── TraceProperties.java # 配置属性类 │ ├── TraceFilter.java # 实际功能过滤器 │ └── TraceContext.java # TraceId 上下文工具 └── resources/ └── META-INF/ └── spring/ └── org.springframework.boot.autoconfigure.AutoConfiguration.imports3.2 第一步创建 Maven 模块引入关键依赖pom.xml里最重要的是spring-boot-autoconfigure和spring-boot-configuration-processor?xml version1.0 encodingUTF-8?projectmodelVersion4.0.0/modelVersion!-- 注意Starter 本身不需要 parent 是 spring-boot-starter-parent --!-- 但通常我们会定义 spring-boot.version 统一管理 --groupIdcom.example/groupIdartifactIdmy-trace-spring-boot-starter/artifactIdversion1.0.0-SNAPSHOT/versionpackagingjar/packagingpropertiesjava.version17/java.versionspring-boot.version3.2.0/spring-boot.version/propertiesdependencies!-- 核心自动配置支持 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-autoconfigure/artifactIdversion${spring-boot.version}/version/dependency!-- 可选配置属性提示写 yml 时有自动补全 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-configuration-processor/artifactIdversion${spring-boot.version}/versionoptionaltrue/optional/dependency!-- 功能依赖我们需要 Servlet 的 Filter --dependencygroupIdjakarta.servlet/groupIdartifactIdjakarta.servlet-api/artifactIdversion6.0.0/versionscopeprovided/scope!-- 由使用方提供 --/dependency!-- 日志MDC 需要 slf4j --dependencygroupIdorg.slf4j/groupIdartifactIdslf4j-api/artifactIdversion2.0.9/versionscopeprovided/scope/dependency/dependencies/project关键点spring-boot-autoconfigure是 Starter 的灵魂没有它就没有自动配置能力spring-boot-configuration-processor是贴心小助手编译时生成配置元数据写application.yml时有 IDE 提示Servlet 和日志依赖标记为provided因为使用方项目里肯定有3.3 第二步定义配置属性类用户可能想自定义 traceId 的请求头名称或者临时关闭这个功能。咱们用ConfigurationProperties来接收这些配置packagecom.example.trace;importorg.springframework.boot.context.properties.ConfigurationProperties;ConfigurationProperties(prefixmy.trace)publicclassTraceProperties{// 是否开启默认 trueprivatebooleanenabledtrue;// traceId 在 HTTP Header 中的名称privateStringheaderNameX-Trace-Id;// traceId 在日志 MDC 中的 keyprivateStringmdcKeytraceId;// getter / setter 省略...publicbooleanisEnabled(){returnenabled;}publicvoidsetEnabled(booleanenabled){this.enabledenabled;}publicStringgetHeaderName(){returnheaderName;}publicvoidsetHeaderName(StringheaderName){this.headerNameheaderName;}publicStringgetMdcKey(){returnmdcKey;}publicvoidsetMdcKey(StringmdcKey){this.mdcKeymdcKey;}}这样用户在application.yml里就能这样配my:trace:enabled:trueheader-name:X-Request-Idmdc-key:requestId3.4 第三步写实际功能代码TraceContext —— 生成和管理 traceIdpackagecom.example.trace;importorg.slf4j.MDC;importjava.util.UUID;publicclassTraceContext{// 生成一个简化的 traceId去掉 UUID 里的横杠取前 16 位publicstaticStringgenerateTraceId(){returnUUID.randomUUID().toString().replace(-,).substring(0,16);}// 放入 MDCpublicstaticvoidput(Stringkey,StringtraceId){MDC.put(key,traceId);}// 清理 MDCpublicstaticvoidclear(Stringkey){MDC.remove(key);}// 获取当前 traceIdpublicstaticStringget(Stringkey){returnMDC.get(key);}}TraceFilter —— 拦截请求处理 traceIdpackagecom.example.trace;importjakarta.servlet.*;importjakarta.servlet.http.HttpServletRequest;importjava.io.IOException;publicclassTraceFilterimplementsFilter{privatefinalTracePropertiesproperties;publicTraceFilter(TracePropertiesproperties){this.propertiesproperties;}OverridepublicvoiddoFilter(ServletRequestrequest,ServletResponseresponse,FilterChainchain)throwsIOException,ServletException{HttpServletRequesthttpRequest(HttpServletRequest)request;// 1. 优先从请求头里取上游服务传过来的StringtraceIdhttpRequest.getHeader(properties.getHeaderName());// 2. 没有就生成一个if(traceIdnull||traceId.isEmpty()){traceIdTraceContext.generateTraceId();}try{// 3. 放入 MDC日志就能打印了TraceContext.put(properties.getMdcKey(),traceId);// 4. 继续处理请求chain.doFilter(request,response);}finally{// 5. 请求结束清理 MDC防止线程复用时污染TraceContext.clear(properties.getMdcKey());}}}注意finally里的清理操作这是踩过坑的教训。Web 容器用线程池复用线程如果不清理 MDC下一个请求可能拿到上一个请求的 traceId那就乱套了。3.5 第四步编写自动配置类核心中的核心packagecom.example.trace;importorg.springframework.boot.autoconfigure.AutoConfiguration;importorg.springframework.boot.autoconfigure.condition.ConditionalOnProperty;importorg.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;importorg.springframework.boot.context.properties.EnableConfigurationProperties;importorg.springframework.boot.web.servlet.FilterRegistrationBean;importorg.springframework.context.annotation.Bean;AutoConfigurationConditionalOnWebApplication(typeConditionalOnWebApplication.Type.SERVLET)EnableConfigurationProperties(TraceProperties.class)ConditionalOnProperty(prefixmy.trace,nameenabled,havingValuetrue,matchIfMissingtrue)publicclassMyTraceAutoConfiguration{BeanpublicTraceFiltertraceFilter(TracePropertiesproperties){returnnewTraceFilter(properties);}BeanpublicFilterRegistrationBeanTraceFiltertraceFilterRegistration(TraceFiltertraceFilter){FilterRegistrationBeanTraceFilterregistrationnewFilterRegistrationBean();registration.setFilter(traceFilter);registration.addUrlPatterns(/*);registration.setOrder(Ordered.HIGHEST_PRECEDENCE);// 最早执行registration.setName(traceFilter);returnregistration;}}来咱们逐个拆解这些注解注解作用AutoConfiguration标记这是一个自动配置类Spring Boot 2.7 推荐替代ConfigurationConditionalOnWebApplication只在 Web 应用Servlet 环境下生效非 Web 项目不加载EnableConfigurationProperties让TraceProperties生效能读取application.ymlConditionalOnProperty根据配置决定是否生效。matchIfMissing true表示没配默认开启为什么要用FilterRegistrationBean而不是直接Bean返回 Filter因为直接Bean返回 FilterSpring Boot 会自动注册但你控制不了顺序和 URL 匹配。用FilterRegistrationBean可以更精细地控制setOrder()控制过滤器顺序addUrlPatterns()控制拦截路径setName()给过滤器起个名字3.6 第五步注册自动配置在src/main/resources/META-INF/spring/下创建文件文件名一字不能差org.springframework.boot.autoconfigure.AutoConfiguration.imports内容com.example.trace.MyTraceAutoConfiguration就这么简单一行类全限定名。Spring Boot 启动时会读取这个文件把里面的类都当成自动配置类去处理。历史包袱Spring Boot 2.7 之前用的是META-INF/spring.factories格式是org.springframework.boot.autoconfigure.EnableAutoConfiguration\ xxx。2.7 之后推荐用新的imports文件更轻量。如果你要兼容老版本两个都写上也没问题。四、验证在项目中使用4.1 安装到本地 Maven 仓库cdmy-trace-spring-boot-starter mvn cleaninstall4.2 在业务项目里引入dependencygroupIdcom.example/groupIdartifactIdmy-trace-spring-boot-starter/artifactIdversion1.0.0-SNAPSHOT/version/dependency4.3 配置日志格式打印 traceId在logback-spring.xml里appendernameCONSOLEclassch.qos.logback.core.ConsoleAppenderencoder!-- %X{traceId} 就是 MDC 里的值 --pattern%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %X{traceId} %logger{36} - %msg%n/pattern/encoder/appender4.4 启动项目看效果发一个请求curlhttp://localhost:8080/hello日志输出2024-01-15 10:23:45 [http-nio-8080-exec-1] INFO a3f7b2c8d9e1f5a2 com.example.demo.HelloController - 收到请求看到a3f7b2c8d9e1f5a2这个 traceId 了吗自动生成的如果你带请求头curl-HX-Trace-Id: my-custom-idhttp://localhost:8080/hello日志里就会打印my-custom-id实现了全链路追踪的基础能力。五、进阶让你的 Starter 更专业5.1 添加配置提示元数据在src/main/resources/META-INF/下创建additional-spring-configuration-metadata.json{properties:[{name:my.trace.enabled,type:java.lang.Boolean,description:是否开启 TraceId 自动追踪,defaultValue:true},{name:my.trace.header-name,type:java.lang.String,description:HTTP 请求头中 traceId 的字段名,defaultValue:X-Trace-Id}]}这样用户在 IDEA 里写application.yml时会有自动补全和提示my:trace:enabled:true# ← 有提示是否开启 TraceId 自动追踪5.2 条件注解大全按需取用Spring Boot 提供了一堆条件注解让你的 Starter 更智能// 类路径里有某个类时才生效ConditionalOnClass(namecom.fasterxml.jackson.databind.ObjectMapper)// 类路径里**没有**某个类时才生效ConditionalOnMissingClass(org.apache.commons.logging.Log)// 容器里有某个 Bean 时才生效ConditionalOnBean(namedataSource)// 容器里**没有**某个 Bean 时才生效避免重复注册ConditionalOnMissingBean(TraceFilter.class)// 配置了某个属性时才生效ConditionalOnProperty(prefixmy.trace,nameenabled,havingValuetrue)// 只在特定 Spring Profile 下生效ConditionalOnProfile(dev)最佳实践注册功能 Bean 时用ConditionalOnMissingBean让用户可以自定义覆盖BeanConditionalOnMissingBean// 用户自己定义了 TraceFilter 就用用户的publicTraceFiltertraceFilter(TracePropertiesproperties){returnnewTraceFilter(properties);}5.3 多环境适配Spring Boot 2.x vs 3.xSpring Boot 3.x 用的是jakarta.servlet包名而 2.x 用的是javax.servlet。如果你的 Starter 要兼容两个版本可以用条件注解// Jakarta 版本Boot 3.xAutoConfigurationConditionalOnClass(jakarta.servlet.Filter.class)publicclassJakartaTraceAutoConfiguration{...}// Javax 版本Boot 2.xAutoConfigurationConditionalOnClass(javax.servlet.Filter.class)publicclassJavaxTraceAutoConfiguration{...}或者更简单的做法分两个分支维护主版本用 Jakarta。六、常见坑点总结坑原因解决方案Starter 引入后没生效AutoConfiguration.imports文件路径/名称写错严格检查路径META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports配置类没读取到 yml没加EnableConfigurationProperties加上Bean 重复注册业务项目里也定义了同名 Bean用ConditionalOnMissingBean非 Web 项目报错Filter 依赖 Servlet 环境用ConditionalOnWebApplication线程池里 traceId 错乱MDC 没清理在finally里调用MDC.clear()配置提示不生效spring-boot-configuration-processor没加或没重新编译加依赖 mvn compile七、一句话总结自定义 Starter 就三步写功能 → 加条件 → 注册配置。核心思路是把重复的配置和初始化封装起来让使用方一行依赖开箱即用。说白了Starter 就是 Spring Boot 版的懒人包。你封装得越完善团队其他兄弟用起来越爽。你在项目里封装过 Starter 吗遇到过什么奇葩的坑欢迎在评论区交流