Back to Details

spring-boot-starter-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spring Boot Starter 开发规范

Spring Boot Starter 开发规范

权威模板：
openclaw-spring-boot-starter/pom.xml
（2.7.x，commit b091ee4）
组织扩展：文末 §6；完整模板：assets/pom-template.xml
权威模板：
openclaw-spring-boot-starter/pom.xml
（2.7.x，commit b091ee4）
组织扩展：见文末 §6；完整模板：assets/pom-template.xml

Capability Boundaries

能力边界

✅ Strong Suits

✅ 擅长场景

  1. POM 结构铁律 — 元素顺序 + properties 三段式 + 元数据三段 + 完整 build/profiles
  2. 十分支矩阵 — 一份源码适配 Spring Boot 2.3~4.1 十条线
  3. 发布工作流 — tag → Central → SNAPSHOT 滚动 → parent 版本核对
  4. 质量门禁 — JaCoCo BUNDLE LINE ≥ 90% haltOnFailure
  5. JDK 兼容规则 — java.version=8 禁 1.8、JDK 21 全线编译
  1. POM 结构铁律 — 元素顺序 + properties 三段式 + 三段元数据 + 完整 build/profiles
  2. 十分支矩阵 — 使用一份源码适配 Spring Boot 2.3~4.1 十条版本线
  3. 发布工作流 — tag → Central → SNAPSHOT 滚动 → parent 版本核对
  4. 质量门禁 — JaCoCo BUNDLE LINE ≥ 90% haltOnFailure
  5. JDK 兼容规则 — java.version=8 禁止写 1.8，所有版本线均使用 JDK 21 编译

❌ Out of Scope

❌ 不在范围内

  • 纯 Java 组件/SDK（无 Spring 依赖）→ 用 
    java-component-patterns
  • 组件自身的业务逻辑实现 → 仅约束工程结构
  • 纯 Java 组件/SDK（无 Spring 依赖）→ 使用 
    java-component-patterns
  • 组件自身的业务逻辑实现 → 仅约束工程结构

LLM 最常犯的错误

LLM 最常犯的错误

#错误正确做法
1properties 平铺不分类不排序三段式：基础→Third-Party→Maven Plugin，段内自然排序
2删除 licenses/scm/developers保留并标准化（Central 发布必需），每段配中文注释
3
java.version
写 
1.8
写 
8
（compiler 3.15.0 对 
--release 1.8
报错）
4surefire argLine 丢 
${argLine}
必须 
${argLine} -Xmx1024m -Dfile.encoding=UTF-8
（JaCoCo 注入点）
5把 okhttp/commons-io 当默认依赖只有被集成组件是业务依赖；SB 四件套+被集成组件+lombok(按需)+test
6项目无 lombok 却保留 annotationProcessorPaths无 lombok → 连同 compiler 注解路径块一起删
7jacoco check 不设 haltOnFailure
<haltOnFailure>true
+ BUNDLE LINE ≥ 0.90
8用 JDK 26 编译 target 8
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
9以为 Maven 4 下必须改 modelM4 兼容 model 4.0.0（零改动）；新特性（session scope 等）才需升级 4.1.0（仅 M4 可构建，详见 references/maven4.md）
#错误正确做法
1properties 平铺且未分类、未排序三段式：基础→Third-Party→Maven Plugin，段内自然排序
2删除 licenses/scm/developers保留并标准化（Central 发布必需），每段配置中文注释
3
java.version
写成 
1.8
写成 
8
（compiler 3.15.0 对 
--release 1.8
报错）
4surefire argLine 丢失 
${argLine}
必须使用 
${argLine} -Xmx1024m -Dfile.encoding=UTF-8
（JaCoCo 注入点）
5将 okhttp/commons-io 作为默认依赖只有被集成组件属于业务依赖；应包含 SB 四件套+被集成组件+lombok（按需）+test
6项目未使用 lombok 却保留 annotationProcessorPaths未使用 lombok → 同时删除 compiler 注解路径配置块
7jacoco check 未设置 haltOnFailure
<haltOnFailure>true
+ BUNDLE LINE ≥ 0.90
8使用 JDK 26 编译 target 8
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
9认为 Maven 4 下必须修改 modelM4 兼容 model 4.0.0（零改动）；仅在使用新特性（如 session scope）时才需升级至 4.1.0（仅 M4 可构建，详见 references/maven4.md）

核心速查

核心速查

元素顺序（铁律）

元素顺序（铁律）

parent → 坐标 → name/description/url
→ licenses → scm → developers      （Central 必需元数据）
→ properties（三段式） → dependencyManagement → dependencies
→ distributionManagement → build（pluginManagement+plugins）→ profiles
parent → 坐标 → name/description/url
→ licenses → scm → developers      （Central 必需元数据）
→ properties（三段式） → dependencyManagement → dependencies
→ distributionManagement → build（pluginManagement+plugins）→ profiles

properties 三段式

properties 三段式

① 基础（自然排序）: java.version / maven.compiler.source+target / 两 encoding
② <!-- Third-Party Dependencies --> : 被集成组件版本
③ <!-- Maven Plugin Dependencies --> : 完整 22 插件版本
① 基础（自然排序）: java.version / maven.compiler.source+target / 两 encoding
② <!-- Third-Party Dependencies --> : 被集成组件版本
③ <!-- Maven Plugin Dependencies --> : 完整 22 插件版本

十分支矩阵（2.1 完整表见 references/version-matrix.md）

十分支矩阵（2.1 完整表见 references/version-matrix.md）

分支SB parentJDK
2.3.x2.3.12.RELEASE8
2.7.x2.7.188
3.0.x~3.5.x3.0.13/3.1.12/3.2.12/3.3.13/3.4.13/3.5.1617
4.0.x / 4.1.x4.0.7 / 4.1.021
版本格式：
{line}.x.{yyyyMMdd}-SNAPSHOT
↔ tag 
{line}.x.{yyyyMMdd}
；月度滚动 20260630→20260730。
分支SB parentJDK
2.3.x2.3.12.RELEASE8
2.7.x2.7.188
3.0.x~3.5.x3.0.13/3.1.12/3.2.12/3.3.13/3.4.13/3.5.1617
4.0.x / 4.1.x4.0.7 / 4.1.021
版本格式：
{line}.x.{yyyyMMdd}-SNAPSHOT
↔ tag 
{line}.x.{yyyyMMdd}
；月度滚动 20260630→20260730。

源码/测试三件套

源码/测试三件套

  • 源码：
    XxxAutoConfiguration
    + 
    XxxProperties
    (@ConfigurationProperties) + 
    XxxTemplate
  • 测试：
    XxxAutoConfigurationTest
    (ApplicationContextRunner) + 
    XxxPropertiesTest
    + 模板测试
  • 源码：
    XxxAutoConfiguration
    + 
    XxxProperties
    (@ConfigurationProperties) + 
    XxxTemplate
  • 测试：
    XxxAutoConfigurationTest
    (ApplicationContextRunner) + 
    XxxPropertiesTest
    + 模板测试

新建/核对清单（8 步）

新建/核对清单（8 步）

复制 assets/pom-template.xml → 替换占位符 → 按分支矩阵填 parent/java.version → 核对 properties 三段式 → 源码三件套 → 测试三件套 → 
mvn clean verify
通过 → 十分支创建。完整演练与逐项勾选清单见 examples/create-new-starter.md。
复制 assets/pom-template.xml → 替换占位符 → 按分支矩阵填写 parent/java.version → 核对 properties 三段式 → 源码三件套 → 测试三件套 → 
mvn clean verify
通过 → 创建十分支。完整演练与逐项核对清单见 examples/create-new-starter.md。

References（按需加载）

参考资料（按需加载）

文件何时读
references/pom-structure.md写/改 pom 时：元素顺序详解、三段式全量示例、build 11 插件配置表、profiles 完整结构
references/version-matrix.md分支/发版时：十分支全表、tag 发布 4 步、SNAPSHOT 滚动映射、SB parent 核对、JDK 兼容规则表
references/maven4.md用 Maven 4 构建时：M3/M4 差异、运行 JDK 17+、maven.version 基线与 enforcer 区间、consumer POM、wrapper 迁移、CI 双轨
examples/create-new-starter.md从零新建 starter 的 8 步完整演练（含验收标准）
examples/maven4-migration.md迁 Maven 4 时：双轨 enforcer、wrapper 切换、M4+JDK21 验证 release 8、consumer POM 检查、CI 双轨、按需升 model 4.1.0
assets/pom-template.xmlMaven 3 / model 4.0.0 模板（M3/M4 双轨，XML 校验通过）
assets/pom-template-maven4.xmlMaven 4 / model 4.1.0 模板（enforcer [4.0.0,)、session scope 示例；仅 M4 可构建）
文件何时阅读
references/pom-structure.md编写/修改 POM 时：元素顺序详解、三段式完整示例、build 11 插件配置表、profiles 完整结构
references/version-matrix.md分支/发版时：十分支完整表、tag 发布 4 步、SNAPSHOT 滚动映射、SB parent 核对、JDK 兼容规则表
references/maven4.md使用 Maven 4 构建时：M3/M4 差异、运行 JDK 17+、maven.version 基线与 enforcer 区间、consumer POM、wrapper 迁移、CI 双轨
examples/create-new-starter.md从零新建 starter 的 8 步完整演练（包含验收标准）
examples/maven4-migration.md迁移至 Maven 4 时：双轨 enforcer、wrapper 切换、M4+JDK21 验证 release 8、consumer POM 检查、CI 双轨、按需升级至 model 4.1.0
assets/pom-template.xmlMaven 3 / model 4.0.0 模板（M3/M4 双轨，通过 XML 校验）
assets/pom-template-maven4.xmlMaven 4 / model 4.1.0 模板（enforcer [4.0.0,)、session scope 示例；仅 M4 可构建）

何时用本 skill vs java-component-patterns

何时使用本 skill，何时使用 java-component-patterns

要发布的东西是什么?
├── xxx-spring-boot-starter（整合某组件到 Spring Boot）→ 本 skill
└── 独立 Java 库/SDK（无 Spring 依赖，无 parent）→ java-component-patterns
依赖顺序: 组件先发正式版 → starter 再发
要发布的东西是什么?
├── xxx-spring-boot-starter（整合某组件到 Spring Boot）→ 本 skill
└── 独立 Java 库/SDK（无 Spring 依赖，无 parent）→ java-component-patterns
依赖顺序: 组件先发正式版 → starter 再发

easy4j 组织扩展

easy4j 组织扩展

  • groupId 
    io.github.easy4j
    ；仓库 packages.aliyun.com（release 
    2624322-release-6F6h6R
    / snapshot 
    2624322-snapshot-3EoOv3
    ）
  • 内部 SDK 线 1:1 映射：starter 2.3.x←SDK feature/1.0.x … starter 4.1.x←feature/4.1.x
  • @author：
    <a href="https://github.com/loong10k">Loong Wan</a>
    ；英语 Javadoc
  • 范式参照：okhttp3（测试）/ openclaw（注释与 POM 权威）/ hermes（简洁测试）
  • groupId 
    io.github.easy4j
    ；仓库 packages.aliyun.com（release 
    2624322-release-6F6h6R
    / snapshot 
    2624322-snapshot-3EoOv3
    ）
  • 内部 SDK 线 1:1 映射：starter 2.3.x←SDK feature/1.0.x … starter 4.1.x←feature/4.1.x
  • @author：
    <a href="https://github.com/loong10k">Loong Wan</a>
    ；使用英语 Javadoc
  • 范式参考：okhttp3（测试）/ openclaw（注释与 POM 权威模板）/ hermes（简洁测试）