作者苏渡苇项目地址https://github.com/iweidujiang/spring-insight感谢 Star 一、加完依赖谁帮你 new 的那些 Bean写 Spring Boot 的人都干过这种事dependencygroupIdio.github.iweidujiang/groupIdartifactIdspring-insight-agent-starter/artifactIdversion0.1.0-SNAPSHOT/version/dependency然后application.yml里丢两行spring:application:name:my-serviceinsight:server-url:http://localhost:9966启动应用日志里冒出一句[AgentStarter] Spring Insight Agent 已启用……你自己的启动类上没写EnableSpringInsight也没扫io.github.iweidujiang这个包。那些拦截器、上报器、配置类是怎么进容器的很多人会下意识猜大概 Spring 把第三方 jar 里的类全扫了一遍吧不是。要真这么干classpath 上每个库的Configuration都会往你应用里塞 Bean那才叫灾难。真正的机关就藏在 Starter 里一个不怎么起眼的文本文件。二、并非靠“组件扫描”而是“自动装配”Spring 默认只扫你启动类所在包及其子包。你的服务是com.example.order.OrderApplicationInsight 的类在io.github.iweidujiang.springinsight……。两边包名八竿子打不着SpringBootApplication扫不到它们这是故意的。所以加个 Starter 就能用靠的不是扫描靠的是自动装配清单Starter 自己报名——「启动的时候请把我这个配置类加载进去」。Spring Boot 3 认的清单文件名有点长但路径是固定的META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.importsSpring Insight 的业务侧 Starter 里这个文件现在就两行io.github.iweidujiang.springinsight.agent.starter.InsightAgentAutoConfiguration io.github.iweidujiang.springinsight.feign.InsightFeignTracingAutoConfiguration没有 XML没有魔法注解扫描全世界。就是全限定类名一行一个。你可以把它想成饭店后厨的「今日出餐表」不是把仓库里所有菜都端上桌只做表上写了的那几道。三、Boot 启动时到底读了什么流程其实很土土到你用jar tf就能验证你的应用启动 → Spring Boot 把依赖 jar 翻一遍 → 找到所有 AutoConfiguration.imports → 按里面的类名把配置类注册进容器 → 每个配置类上的 ConditionalXxx 再决定这次要不要真的生效几点容易混1. 这不是老的spring.factoriesBoot 2.7 之前自动配置写在META-INF/spring.factories键是org.springframework.boot.autoconfigure.EnableAutoConfiguration。Boot 3 把自动配置清单拆成了上面那个.imports文件。Insight 的insight-agent里还有一个spring.factories但那是给EnvironmentPostProcessor用的跟「报名 AutoConfiguration」不是一回事。2. 清单要放在 Starter 里别放在纯库里insight-agent是采集核心谁依赖它谁都能用它的类但报名自动装配的是spring-insight-agent-starter。这是 Starter 的老规矩库本身尽量「老实」不要因为被人间接依赖就自己往容器里塞东西。业务方显式加 Starter才表示「我同意你自动起来」。3. 报了名不等于一定干活清单只解决「配置类进不进容器」。进了之后还要过ConditionalOnProperty、ConditionalOnClass这些关。关过不了配置类就躺着不捣乱。四、对照 Spring Insight 的入口类第一行对应的类长这样AutoConfigurationEnableConfigurationProperties(InsightProperties.class)ConditionalOnProperty(prefixspring.insight,nameenabled,havingValuetrue,matchIfMissingtrue)Import(InsightAgentAutoConfigurationImportSelector.class)publicclassInsightAgentAutoConfiguration{publicInsightAgentAutoConfiguration(){log.info([AgentStarter] Spring Insight Agent 已启用……);}}四个注解各管一件事注解人话AutoConfiguration告诉 Boot我是自动配置按自动配置的规则排序、加载EnableConfigurationProperties把spring.insight.*绑到InsightPropertiesConditionalOnProperty开关。enabledtrue才干没配也当 truematchIfMissing trueImport(...)真正的拦截器、上报器不堆在这一个类里交给选择器按 Web 栈再导入最后那个Import是下一篇的主角。本篇内容主要是自动装配自动装配的门是.imports文件推开的门后面装什么是这个配置类接着干的。构造方法里打那行 info 日志也是有用的土办法——Starter 这种「看不见的依赖」最怕静悄悄失败。启动后搜[AgentStarter]比猜「到底装上没有」省事。五、为什么还要第二行Feign 那个配置.imports里第二行是InsightFeignTracingAutoConfiguration。它上面挂了AutoConfigurationConditionalOnWebApplication(typeSERVLET)ConditionalOnClass(Client.class)// feign.ClientpublicclassInsightFeignTracingAutoConfiguration{...}翻译成人话你这个服务没有OpenFeign →feign.Client不在 classpath → 这个配置直接跳过零影响你是普通 MVC 服务有Feign → 才去给 Feign Client 套一层方便后面画拓扑Starter 的pom里feign-core是optional。自动装配清单里把 Feign 单独挂一行就是为了有就用没有就当这段代码不存在。别把所有能力塞进一个巨型Configuration。条件越细别人项目越不容易被你拖进坑里。六、怎么确认它真的生效了以及怎么关掉看日志。启动后搜[AgentStarter] Spring Insight Agent 已启用没有这行先查三件事依赖是不是agent-starter、是不是 Boot 3.imports这套、jar 里到底有没有那个META-INF/spring/...imports文件。看开关。不想要了不必删依赖配一行就行spring:insight:enabled:falsematchIfMissing true的意思是你懒得配默认开你明确说 false就关。这比再搞一个「必须写EnableXxx才启动」对使用者更友好。看它不会替你做的事。自动装配只保证「Bean 进容器」。数据往哪报、服务叫什么还是配置说了算没配spring.insight.server-urlHTTP 上报 Sink 根本不会建出来没起insight-server报了也没人收拓扑边还依赖 Feign 那层包装有 Feign 才会走第二行配置「加依赖就生效」≠「加依赖就万事大吉」。生效的是装配不是整个监测系统自己长出来。七、自己做 Starter如果哪天你也有需要做个 Starter无需一上来就写 ImportSelector、别一上来就研究 AutoConfiguration 排序。做好如下三步即可单独一个xxx-spring-boot-starter模块不要让业务直接依赖你的核心 jar 然后指望它自动起来在 Starter 里放META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports一行一个配置类配置类上用ConditionalOnProperty/ConditionalOnClass把「没有的能力」挡在门外再留一个默认开、能关掉的开关Insight 现在就是这个形状。八、小结你以为的实际是扫描了第三方包只扫你自己的启动类包某个注解偷偷全局生效.imports文件点名加载配置类加了 Starter 就等于功能全开还要过Conditional*还要配server-url必须写EnableXxx有 Starter 时注解是可选项Spring Boot 的「约定大于配置」落到 Starter 上就一句大白话你把全限定类名写进那个文件Boot 启动时会来读。下一篇会接着讲门后面的Import为什么 Gateway 上不能把 MVC 的HandlerInterceptor硬塞进去以及DeferredImportSelector在 Insight 里具体干了啥。 最后欢迎围观 Spring Insight如果你对「轻量监测 / Spring Boot Starter / 链路埋点」感兴趣欢迎看看这个还在打磨的小项目GitHubhttps://github.com/iweidujiang/spring-insight当前形态很朴素业务服务加spring-insight-agent-starter旁边单独跑insight-server看拓扑和链路。能力有限代码也还糙适合当练手和对照。你的 Star 是对我最大的鼓励。