如何自定义一个 Spring Boot Starter？

在微服务与多系统并存的架构中，重复建设是最常见的隐性成本。以登录认证为例，几乎每个业务系统都需要登录接口、令牌签发、令牌刷新、密码校验与登录态解析。如果每个系统都复制一套实现，短期看省事，长期看会带来规则不一致、安全策略难以统一、升级维护成本高等问题。自定义 Spring Boot Starter 正是解决这类问题的标准手段。

一、Starter 的本质与价值

Starter 本质上是一个”快速启动器”：它把某一类功能所需的一组依赖和默认配置聚合在一起，业务方只需引入一个依赖坐标，即可获得开箱即用的能力，而不必逐个引入大量分散依赖、逐个编写配置类。

判断一段逻辑是否值得沉淀为 Starter，可以参考三个标准：

• 流程固定：主流程在各业务系统中高度一致，例如登录的”校验凭证—签发令牌—返回登录态”。
• 变化点明确：差异集中在少数几个可枚举的环节，例如用户来源、密码规则、前置校验、审计处理。
• 复用面广：有三个以上系统需要相同能力，复制成本已经超过抽象成本。

登录场景恰好满足这三点。主流程固定，但各系统的用户表结构不同、密码比较规则不同、前后置逻辑不同、令牌续期策略也可能不同。因此正确的做法是：把固定流程沉淀到 Starter 中，把变化点开放为扩展接口。

需要强调的是，Starter 不等于”把所有代码都搬进来”。它的价值在于划定一条清晰的边界，边界之内由组件保证一致性与安全性，边界之外由业务方按需实现。

二、工程分层结构

参考 Spring Boot 官方对 Starter 的组织方式，建议拆分为四个模块，各司其职：

1. auth-login-core

存放认证领域的核心内容：领域模型（如登录请求、令牌响应、用户身份载体）、登录主流程编排、业务扩展接口定义。该模块应尽量保持轻量，不依赖 Web 容器与自动配置机制，便于被独立测试与复用。

典型内容包括：

• 实体与 DTO：登录参数、令牌结果、登录上下文；
• 主流程接口：如登录服务、令牌服务；
• 扩展点接口：如用户查询、密码匹配、前置校验、审计回调。

2. auth-login-spring-boot-autoconfigure

存放自动配置与真正开箱即用的实现：配置属性类、条件装配、过滤器、令牌服务实现、默认扩展点实现等。该模块依赖 core，并通过条件注解决定 Bean 是否装配，保证在业务方未提供自定义实现时使用合理的默认行为。

3. auth-login-spring-boot-starter

这是给业务方引入的依赖入口，本身几乎不写业务代码，只负责聚合依赖。业务项目只需引入：

<dependency>
  <groupId>com.example.auth</groupId>
  <artifactId>auth-login-spring-boot-starter</artifactId>
  <version>${project.version}</version>
</dependency>

这种”空壳聚合”的设计是有意为之：依赖坐标稳定，内部模块可自由演进，业务方无需感知实现拆分。

4. auth-login-demo

用于演示业务项目如何接入 Starter、如何实现 core 中定义的扩展接口。它同时承担”可运行文档”的角色，是验证 Starter 易用性的第一道关卡。建议在 demo 中覆盖默认实现与自定义实现两种路径，确保两条链路都可用。

三、明确职责边界

边界划分是 Starter 设计中最关键也最容易被忽视的一环。边界模糊会导致组件侵入业务，或业务逻辑反向渗入组件。

Starter 负责的部分：

• 登录、刷新等标准端点的请求处理与参数校验；
• 访问令牌与刷新令牌的生成、解析、过期判定；
• 登录主流程的编排与异常语义统一；
• 自动配置、条件装配与过滤器注册；
• 默认扩展点实现，保证”零配置可跑通”。

业务系统负责的部分：

• 根据用户名查询本系统用户；
• 密码规则特殊时自行实现密码匹配器；
• 可选前置校验，如验证码校验、租户校验；
• 可选登录成功与失败后的审计处理；
• 令牌续期策略的个性化调整。

这条边界的判断原则是：与具体业务数据模型相关的，交给业务方；与认证流程语义相关的，留在 Starter。

四、扩展点设计

扩展点是 Starter 的灵魂。设计时应遵循”接口小而聚焦、默认实现可用、允许覆盖”的原则。

public interface UserLoader {
    LoginUser load(String username);
}
public interface PasswordMatcher {
    boolean matches(String rawPassword, String encodedPassword);
}
public interface LoginPreChecker {
    void check(LoginRequest request);
}
public interface LoginAuditListener {
    void onSuccess(LoginUser user);
    void onFailure(String username, String reason);
}

对应的自动配置使用条件注解，确保业务方提供自定义 Bean 时优先使用：

@AutoConfiguration
@EnableConfigurationProperties(AuthProperties.class)
public class AuthAutoConfiguration {
    @Bean
    @ConditionalOnMissingBean
    public PasswordMatcher passwordMatcher() {
        return new DefaultPasswordMatcher();
    }
    @Bean
    @ConditionalOnMissingBean
    public LoginService loginService(UserLoader userLoader,
                                     PasswordMatcher passwordMatcher,
                                     List<LoginPreChecker> preCheckers,
                                     List<LoginAuditListener> auditListeners,
                                     TokenService tokenService) {
        return new DefaultLoginService(userLoader, passwordMatcher,
                preCheckers, auditListeners, tokenService);
    }
}

使用集合注入扩展点是实用技巧：业务方可以注册零个或多个前置校验器，组件按顺序执行，无需修改配置。

五、配置属性与默认值

通过配置属性暴露可调参数，同时给出安全合理的默认值：

@ConfigurationProperties(prefix = "auth.login")
public class AuthProperties {
    private String loginPath = "/auth/login";
    private String refreshPath = "/auth/refresh";
    private Duration accessTokenTtl = Duration.ofMinutes(30);
    private Duration refreshTokenTtl = Duration.ofDays(7);
    private String tokenHeader = "Authorization";
    // getters / setters
}

默认值应偏向安全侧：令牌有效期不宜过长，刷新令牌应可撤销，密钥必须由业务方显式配置而非内置硬编码。对于密钥这类敏感项，建议启动时校验其存在性，缺失则快速失败，避免带病上线。

六、自动配置的注册与顺序

自动配置类需要在约定的元数据文件中注册，供框架在启动时发现。同时应注意装配顺序与条件约束：过滤器注册应晚于基础 Web 能力就绪，令牌服务应在配置属性绑定之后创建。对于可选依赖，使用类条件注解避免类缺失导致的启动失败。

七、实践建议

1. 先用后抽：先在 demo 中把接入流程跑通，再反向验证接口设计是否合理。
2. 默认可用：保证零配置即可启动并完成一次完整登录，降低接入门槛。
3. 异常语义统一：为认证失败定义稳定的错误码与消息结构，避免各系统自行解释。
4. 版本兼容：Starter 的接口一旦发布应保持向后兼容，新增能力优先通过新增接口或默认方法实现。
5. 可观测性：在关键节点输出结构化日志，便于问题定位，但不得记录明文密码与完整令牌。

结语

自定义 Starter 的核心不是写多少代码，而是划清边界、定好扩展点、给出可靠默认值。把登录这类固定流程沉淀为组件，把用户来源、密码规则、前置校验、审计处理开放为接口，既能保证多系统间认证策略的一致性，又能保留每个系统必要的灵活性。这套抽象方法同样适用于权限校验、消息通知、文件处理等通用能力的封装。