用过 PageHelper、MyBatis-Plus 的都有体感:引一个依赖,功能就长出来了。starter 的秘密在 14.1 已经揭穿——预制配置类加条件装配。这一篇把流程倒过来走一遍:亲手写一个 simple-log-spring-boot-starter,自动给所有 Controller 方法打印入参出参耗时。
开工前先补一条行业规约:命名。官方 starter 一律 spring-boot-starter-xxx(如 spring-boot-starter-data-redis),第三方必须 xxx-spring-boot-starter(如 pagehelper-spring-boot-starter)。这不是美学,是辨识度——看名字前缀就知道这层装配是官方兜底还是社区贡献,排依赖冲突时能少走弯路。我们做自己的功能,规规矩矩叫 simple-log-spring-boot-starter。
拆任何成熟 starter,都是同样三样:
1. 自动配置类:带 @AutoConfiguration 的类,里面写 @Bean 方法
2. 条件装配:@ConditionalOnClass/@OnMissingBean 决定「要不要生效、要不要让位」
3. 注册文件:META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports,一行写上配置类全限定名
第三块最容易被漏——没有它,配置类写得再好也是孤岛,Boot 根本不知道它的存在。三块的分工用一句话锚定:配置类是货、条件是海关、注册文件是报关单,缺任何一样货都进不了容器这门。
先来功能本体,一个简单的切面(13.3 的知识直接上场):
@Aspect
public class SimpleLogAspect {
@Around("@within(org.springframework.web.bind.annotation.RestController)")
public Object around(ProceedingJoinPoint pjp) throws Throwable {
long start = System.currentTimeMillis();
try {
return pjp.proceed(); // 放行真实方法
} finally {
long cost = System.currentTimeMillis() - start;
System.out.println("[simple-log] " + pjp.getSignature()
+ " 耗时 " + cost + "ms"); // 出入参打印同理可加
}
}
}
再来自动配置类,把切面变成 Bean,用条件守住边界:
@AutoConfiguration
@ConditionalOnClass(SimpleLogAspect.class) // 类路径有切面才装配
@ConditionalOnProperty(name = "simple.log.enabled",
havingValue = "true",
matchIfMissing = true) // 不配置默认开启
public class SimpleLogAutoConfiguration {
@Bean
@ConditionalOnMissingBean // 用户自定义了就让位
public SimpleLogAspect simpleLogAspect() {
return new SimpleLogAspect();
}
}
最后注册文件,路径和内容各一行不能错:
文件: META-INF/spring/org.springframework.boot.autoconfigure
.AutoConfiguration.imports
内容: com.demo.simplelog.SimpleLogAutoConfiguration
工程拆两个模块更专业:simple-log-core(不依赖 Boot,纯功能)+ simple-log-spring-boot-starter(依赖 core 和 Boot 自动装配,只有配置类和注册文件)。官方 starter 全是这结构——功能与装配分离,core 还能被非 Boot 项目复用。拆分还有一层好处:core 不引 Boot 依赖,意味着它的演进不受 Boot 版本节奏绑架;装配层薄到只有几个类,Boot 大版本升级(14.4 的 3.x 迁移)时改起来成本极小。
切面本体还藏着两个可深挖的点。其一,@within(RestController) 只拦标注 RestController 的类——想连老式 @Controller 也覆盖,可换成 @within(org.springframework.stereotype.Controller) 或 execution 表达式按包切,粒度自选。其二,日志输出别用 System.out——生产该走 SLF4J 门面拿到正规 Logger,日志级别、文件滚动才有管理可言;示例图省事,工程里要按标准来。
starter 的测试有个专属武器:ApplicationContextRunner(Boot 提供的轻量上下文测试器,不开服务器就能验证条件装配结果)。它比「起个真实应用肉眼验证」快得多,还能直接断言 Bean 有无:
private final ApplicationContextRunner runner = new ApplicationContextRunner()
.withConfiguration(AutoConfigurations.of(SimpleLogAutoConfiguration.class));
@Test
void defaultOn() {
runner.run(ctx -> assertThat(ctx)
.hasSingleBean(SimpleLogAspect.class)); // 默认装配
}
@Test
void disabledByProperty() {
runner.withPropertyValues("simple.log.enabled=false")
.run(ctx -> assertThat(ctx)
.doesNotHaveBean(SimpleLogAspect.class)); // 关掉让位
}
条件装配的每一种组合,都能这样写成毫秒级的单测——官方 starter 的测试套件全是这个套路。手工验证留给最后一步:真实项目引依赖、调接口、看日志,确认端到端无断点。
使用方引依赖、启动,随便调一个接口,控制台就有耗时日志。三个验证动作别省:改 simple.log.enabled=false 重启,日志消失(条件装配生效);自己注册一个 SimpleLogAspect Bean,日志格式变掉(MissingBean 让位生效);删掉注册文件,什么都没发生(证明 imports 是唯一入口)。三步验证对应三块积木,哪块坏了立刻现形。
硬编码的切面不够体面,参数该开放成配置。上 @ConfigurationProperties(把配置前缀绑定到字段的对象绑定注解):
@ConfigurationProperties(prefix = "simple.log")
public class SimpleLogProperties {
private boolean enabled = true;
private boolean printArgs = true; // 是否打印入参
private int slowMs = 500; // 超过此耗时打慢日志
// 省略 getter/setter
}
配置类上追加 @EnableConfigurationProperties(SimpleLogProperties.class),切面里注入它,用户就能 simple.log.slowMs=1000 按需调。这一手把 starter 从「能用」带到「好用」——绝大多数官方 starter 的可配置项,就是这么长出来的。
再补最后一块拼图:配置元数据。在 META-INF 下放一个 additional-spring-configuration-metadata.json,声明每个配置项的类型、默认值和说明——用户在 yaml 里敲 simple.log. 时,IDE 会弹出补全和文档提示,体验直逼官方 starter。没有这份文件功能照样跑,但「好不好用」往往就差这些最后一公里:
{
"properties": [{
"name": "simple.log.slow-ms",
"type": "java.lang.Integer",
"defaultValue": 500,
"description": "超过此耗时输出慢调用日志(毫秒)"
}]
}
至此一个能拿出手的 starter 凑齐了五样东西:功能本体、自动配置、条件守门、注册挂号、配置绑定加提示。发布到公司私服(Maven deploy),团队就能像用 PageHelper 一样用它——把重复劳动沉淀成「引依赖即生效」的组件,正是 starter 模式对工程效率最大的贡献。
最后聊一个判断题:什么时候值得把功能抽成 starter?两个信号同时出现才动手:一是多处复用——同样一段装配代码在三个以上项目里复制粘贴,改一处漏两处的痛已经真实发生;二是装配稳定——功能接口收敛、配置项不再每周新增,抽出去的边界画得清。只为单一项目服务的「内部工具」,抽 starter 是过度设计:多一个模块的发布、版本对齐成本,换来零复用收益。组件化的节奏应该是「第三次复制时抽」,不是「预感会复用就抽」——这条判断在 13.4 的事件、16.x 的网关插件上同样适用。
starter = 14.1 自动装配原理的使用者视角:配置类造 Bean、条件注解守门、imports 文件挂号——三块积木搭完,你也能发布「引依赖即生效」的功能。