Starters

受众：开发者 摘要：Starter 使用方式：按需引入 / 模块边界 / 抽象风格 / 命名规范。

Starter 是框架能力的主要交付方式。业务应用通过引入 starter 获得自动配置、配置属性、Facade、Manager、Resolver 和 Provider 能力。

推荐使用方式

应用启动模块按需要显式引入具体 starter：

<dependency>
    <groupId>com.springopen</groupId>
    <artifactId>spring-open-starter-webmvc</artifactId>
</dependency>
<dependency>
    <groupId>com.springopen</groupId>
    <artifactId>spring-open-starter-cache</artifactId>
</dependency>

框架不再提供 all-in-one spring-open-starter 兜底模块。应用、业务模块和外部项目都应按需声明实际使用的 spring-open-starter-*，这样新增或删除能力时依赖边界更清楚，也不会被全量聚合掩盖缺失依赖。

模块边界

模块	作用
spring-open-starter-toolkit	纯 Java 工具，不依赖 Spring
spring-open-starter-common	Result、异常、分页、TraceId、常量和通用契约
spring-open-starter-execution	钩子 / 管道 / 责任链共享执行上下文、类型安全 key 和中止状态
spring-open-starter-hook	方法级同步钩子，包住业务方法做日志、审计、鉴权、幂等和轻量风控扩展
spring-open-starter-pipeline	管道编排，按顺序执行稳定业务步骤，支持 next/skip/stop、trace 和补偿
spring-open-starter-chain	条件决策责任链，Handler 显式 proceed 才继续传递
spring-open-starter-feature-flag	Pennant-like 功能开关、灰度 rollout、variant 和属性 gate
spring-open-starter-json-api	可选 JSON:API Resource Document、relationship、link、meta 和 error object
spring-open-starter-plugin	插件元数据发现、本地安装 contract、状态矩阵和生命周期治理入口
spring-open-starter-media	媒体处理 Provider、转码 / 截图 / 录制回调归一化和 Core File 绑定描述
spring-open-starter-schema	动态字段定义、声明式校验规则和跨端渲染元数据底座
spring-open-starter-lifecycle	模块 register() / boot() 生命周期、服务绑定、标签聚合和配置 schema 声明
spring-open-starter-wechat	微信公众号、小程序和微信开放平台的 WxJava SDK 适配与多账号配置
spring-open-starter-*	可复用能力、自动配置、Facade / Manager / Resolver / Provider
spring-open-module-*	业务或后台模块
spring-open-application	启动装配，不写业务逻辑

抽象风格

可替换能力统一采用 Provider 扩展模型，详见 Provider 扩展模型。

配置命名尽量参考 Laravel 的优雅结构，但实现必须符合 Spring Boot 配置属性和自动配置规范。

自动配置

Starter 自动配置由 lifecycle Provider 统一声明。普通 starter 不再手写 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports，而是在本模块 ServiceProvider.configure(AutoConfigurationRegistry registry) 中导入自动配置类：

@Override
public void configure(AutoConfigurationRegistry registry) {
    registry.imports(SmsAutoConfiguration.class);
}

自动配置类仍使用 Spring Boot 标准 @AutoConfiguration，并优先通过 before = XxxAutoConfiguration.class、after = XxxAutoConfiguration.class 引用已知类。

避免写死字符串类名。只有引用可选模块且当前模块不能编译依赖目标类时，才允许使用 beforeName 或 afterName，并应在注释或文档中说明原因。

配置前缀

自定义 starter 统一使用：

spring.open.<module>

高频配置前缀、配置 key、路由和 provider 名称应提供常量，避免生产 Java 代码到处手写字符串。

YAML、.env 和正式文档保留真实字面量，方便开发者复制。

包名规范

所有 starter 源码包名默认使用：

com.springopen.starter.<starter>

单词类 starter 直接使用能力名，例如 sms、web3、storage 分别对应 com.springopen.starter.sms、com.springopen.starter.web3、com.springopen.starter.storage。连字符 starter 名转成点分段，例如 content-safety 使用 com.springopen.starter.content.safety，feature-flag 使用 com.springopen.starter.feature.flag，json-api 使用 com.springopen.starter.json.api，rate-limit 使用 com.springopen.starter.rate.limit，data-redis 使用 com.springopen.starter.data.redis。

Web MVC starter 按同一命名规则使用 com.springopen.starter.webmvc.*，对应 Maven 模块和 artifactId spring-open-starter-webmvc，不保留旧 Web starter 包兼容入口。

Provider 扩展点放在当前 starter 包下，例如 com.springopen.starter.sms.provider.SmsProvider、com.springopen.starter.storage.provider.StorageProvider。业务模块只依赖 Facade / Manager / Provider SPI，不直接 import 第三方 SDK。

数据库配置

涉及第三方服务商或运行时切换的 starter，应优先支持数据库配置覆盖本地配置。

典型场景：

• Mail SMTP 账号。
• SMS 服务商密钥。
• Storage 对象存储配置。
• Payment 商户号、证书路径和密钥。
• Translate 第三方服务密钥。
• Notification Webhook。

数据库配置优先，本地 application.yml 和 .env 兜底。

新增 Starter Checklist

新增 starter 时至少补齐：

• pom.xml 依赖边界。
• *Properties 配置类。
• Facade / Manager / Resolver / Provider 契约。
• 默认轻量实现，例如 log、memory、mock。
• @AutoConfiguration 自动配置类。
• ServiceProvider：默认用 @AutoService(ServiceProvider.class) 注册，在 configure(...) 声明自动配置类；需要服务绑定、配置 schema 或模块贡献项时，再在 register(...) / boot(...) 补充生命周期逻辑。
• 配置绑定测试和自动配置测试。
• 正式 docs/ 使用文档。
• .ai 进度和决策记录。

如果引入第三方依赖，先评估官方 SDK 和成熟生态库。不要把第三方 API 泄露到业务模块。