Spring Boot 自定义 Starter 为什么不生效：AutoConfiguration.imports 的注册边界与可验证启动结果

项目里把审计能力封装成 Starter 后，最容易遇到的现象是：Maven 依赖树里明明有这个 JAR，启动应用却找不到默认的 AuditClock。这时先别急着改扫描包。Spring Boot 的自动配置至少有三道边界：Starter JAR 是否带上发现入口、自动配置类是否通过条件、业务应用是否已经提供了同类型 Bean。把三层拆开，问题通常很快能落到一个文件或一个条件上。

为什么 Starter 已打包却没有自动配置

先建立两个判断：依赖存在不等于自动配置已被发现，自动配置被发现也不等于条件已经匹配。在“应用边界”里，业务应用只声明 audit-spring-boot-starter；在“自动配置边界”里，Starter JAR 还必须携带 AutoConfiguration.imports，并指向可加载的 AuditAutoConfiguration。

一个常见的静态关系可以这样看：业务应用依赖 Starter JAR，Starter JAR提供 AutoConfiguration.imports，该资源登记 AuditAutoConfiguration，随后才由 @ConditionalOnClass 与 @ConditionalOnMissingBean共同决定装配。少了资源文件，后面的条件写得再漂亮也不会被调用。

把自动配置注册到正确的 imports 文件

建议把能力拆成两个模块：audit-autoconfigure放条件、配置类和默认 Bean，audit-spring-boot-starter只负责组合依赖。自动配置类可以保持很小：

package com.acme.audit.autoconfigure;

@AutoConfiguration
@ConditionalOnClass(AuditClock.class)
@ConditionalOnMissingBean(AuditClock.class)
public class AuditAutoConfiguration {
    @Bean
    AuditClock auditClock() {
        return new SystemAuditClock();
    }
}

发布资源必须位于 audit-autoconfigure/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports，文件内容按类名逐行登记：

com.acme.audit.autoconfigure.AuditAutoConfiguration

这里的“依赖边界”是 starter 组合依赖，“发现边界”是 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports，“装配边界”则由 AuditAutoConfiguration和AuditClock构成。第三方模块名称也不要以 spring-boot 开头，避免与官方命名空间混淆。

用条件与启动日志确认 Bean 真的生效

第一项验证不需要猜：对最终发布的 JAR 执行解压检查，确认存在 META-INF/spring/ 目录和准确的 imports 文件，再检查文件里的全限定类名与自动配置类包名完全一致。尤其留意 Maven 资源过滤、Gradle sourceSet 或打包插件是否把该文件排除。

第二项验证看条件报告。启动应用时加入 --debug，观察 AuditAutoConfiguration 的匹配结果：若缺少 AuditClock 所在依赖，@ConditionalOnClass 会使条件不匹配；若业务应用已经声明自己的 AuditClock，@ConditionalOnMissingBean 应让默认 Bean 退让。这个结果比只看“找不到 Bean”更能说明是哪一层没有通过。

把选择约束放进 Starter 的架构边界

发布前可以用一张小清单收口：autoconfigure 模块只承载自动配置与条件；starter 模块保持轻量并引入核心 spring-boot-starter；自有配置键使用自己的命名空间，不要挤进 spring、server 或 management；每个配置属性补充 Javadoc 和元数据。

最后做一次覆盖验证：在没有业务实现的应用里，AuditClock应由默认配置提供；在声明自定义实现的应用里，默认配置应退让。两种结果都符合预期，才说明 Starter 的可发现性、条件和覆盖策略形成了闭环。

常见问题：自定义 Starter 的几个误区

为什么有了 @Configuration 还要写 AutoConfiguration.imports？

普通配置类不会因为放进一个第三方 JAR 就自动成为 Spring Boot 自动配置入口，imports 文件负责把自动配置类登记给 Boot。

imports 文件可以写配置类的简单类名吗？

不可以。应写可加载的全限定类名，并保持每行一个类名，避免包名变化后只在运行时才暴露问题。

@ConditionalOnMissingBean 会不会让默认能力失效？

它的目的正是尊重业务实现。没有同类型 Bean 时提供默认值，业务方已经声明实现时则退让；需要用条件报告确认具体匹配结果。