← 课程目录 🚀 从零到一
📐 学习维度 阶段4 · 第14章 Spring Boot 🚀 从零到一 📚 课程目录 🏠 首页 🛤️ 学习路径

14.2 手写一个 starter:simple-log 复盘

审校 2026-09-25 · 素材来源:simple-log-starter 项目复盘、L课SpringBoot体系
📑 本篇章节导航 (共9节,点击直达)
starter 的三块积木动手:四个文件写完用 ApplicationContextRunner 做条件装配测试验证与使用配置绑定:让参数可调踩坑清单踩坑清单面试怎么问一句话总结

用过 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 的三块积木

拆任何成熟 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,日志级别、文件滚动才有管理可言;示例图省事,工程里要按标准来。

用 ApplicationContextRunner 做条件装配测试

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 文件挂号——三块积木搭完,你也能发布「引依赖即生效」的功能。