full-stack-skills Java 组件（SDK / 工具库）封装规范
权威参照：
openclaw-java-sdk/pom.xml
完整模板：assets/pom-template.xml
与 spring-boot-starter-patterns 的区别：无 parent、不依赖 Spring、面向纯 Java 组件
Capability Boundaries
✅ Strong Suits
- 无 parent 独立 POM — 插件/依赖版本全部自管（这是 properties 必须声明完整插件版本的原因）
- maven.compiler.release — 比 source/target 更安全（--release 语义防误用高版本 JDK API）
- 元数据三段 — licenses/scm/developers（Central 发布必需）
- 多 JDK 分支 — feature/{line} 一份源码多 JDK 线，分支间仅 pom 差异
- 组件间同线依赖 — feature/1.0.x 只依赖其他组件的 1.0.x 线
❌ Out of Scope
- Spring Boot starter（整合组件到 SB）→ 用
spring-boot-starter-patterns - Spring 生态强依赖的库 → 应做成 starter
LLM 最常犯的错误
| # | 错误 | 正确做法 |
|---|---|---|
| 1 | 给独立组件加 spring-boot-starter-parent | 无 parent；插件版本在 properties 第三段自管 |
| 2 | java.version 写 8 |
写 1.8（maven-compiler-plugin 3.15.0 + JDK8 组合下 --release 8 有问题；1.8 全版本兼容） |
| 3 | 用 source/target 而非 release | maven.compiler.release=${java.version}（API 安全） |
| 4 | 漏 licenses/scm/developers | Central 发布必需；每段配中文注释 |
| 5 | 跨线依赖内部组件 | 同线原则：feature/1.0.x → 依赖 1.0.x 线 |
| 6 | 分支间源码漂移 | src/测试/README 逐字节一致；仅 pom 差异 |
| 7 | 本地用 JDK 26 编译 release 8 | export JAVA_HOME=$(/usr/libexec/java_home -v 21) |
| 8 | XML 注释里写 --xxx |
XML 注释内禁止双连字符（not well-formed） |
| 9 | 以为 Maven 4 下必须改 model | M4 兼容 4.0.0 零改动；session scope 等新特性才升级 4.1.0（仅 M4 可构建）；可移除 flatten（原生 consumer POM） |
| 10 | Jackson 依赖在 dependencyManagement 里写无 version 的条目 | 无 version 的 dm 条目会遮蔽 BOM import，导致 dependencies.dependency.version is missing；必须整体删除 dm 条目（不能只删 version 行），让 BOM 生效 |
| 11 | Jackson 每个模块单独写 version | 用 BOM 统一管理：properties 定义 jackson-bom.version，dependencyManagement 中 import com.fasterxml.jackson:jackson-bom:${jackson-bom.version}（2.x）或 import tools.jackson:jackson-bom:${jackson-bom.version}（3.x）；dependencies 中不写 version |
| 12 | License URL 用 http:// |
Apache License URL 必须用 https://www.apache.org/licenses/LICENSE-2.0.txt（http 会被 Central 拒绝） |
| 13 | pom.xml 缩进不一致 | 统一 4 空格缩进，XML 标签对齐，properties 三段式分组 |
核心速查
元素顺序（铁律）
坐标（无 parent！）→ name/url/description/version/packaging
→ licenses → scm → developers （Central 必需）
→ properties（三段式）→ dependencyManagement → dependencies
→ distributionManagement → build → profiles
properties 三段式
① 基础: java.version / maven.compiler.release / maven.version / encoding
② <!-- Dependency versions --> : 外部依赖 + 内部组件线版本
③ <!-- Maven Plugin versions --> : 完整插件版本（无 parent 全自管）
Jackson BOM 版本管理
组件依赖 Jackson 时，必须用 BOM 统一管理，禁止每个模块单独写 version：
properties: jackson-bom.version = {版本}
dependencyManagement:
<dependency>
<groupId>com.fasterxml.jackson</groupId> ← 2.x
<artifactId>jackson-bom</artifactId>
<version>${jackson-bom.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
dependencies: jackson-databind / jackson-dataformat-xml 等（不写 version）
| 分支 | jackson-bom.version | groupId |
|---|---|---|
| 1.0.x | 2.18.9 | com.fasterxml.jackson |
| 2.0.x | 2.22.1 | com.fasterxml.jackson |
| 3.0.x | 3.2.1 | tools.jackson |
⚠ 铁律：dependencyManagement 中禁止放无 version 的 Jackson 条目——会遮蔽 BOM import，导致 dependencies.dependency.version is missing。必须整体删除 dm 条目。
与 starter 的关键差异
| 维度 | 组件（本 skill） | starter |
|---|---|---|
| parent | 无 | spring-boot-starter-parent |
| 编译 | release | source/target |
| 依赖 | 可依赖内部组件线 | 依赖组件 + SB 四件套 |
| 三件套 | Client门面+Config+能力域分包 | AutoConfiguration+Properties+Template |
| 发布顺序 | 底层先发 → starter 后发 | 依赖组件已发布 |
分支模型速查
| feature/{line} | JDK | java.version | Jackson BOM |
|---|---|---|---|
| 1.0.x | 8 | 1.8 | 2.18.9 (com.fasterxml.jackson) |
| 2.0.x | 17 | 17 | 2.22.1 (com.fasterxml.jackson) |
| 3.0.x ~ 3.5.x | 21 | 21 | 3.2.1 (tools.jackson) |
版本：{line}.x.{yyyyMMdd} ↔ -SNAPSHOT；同步法：git checkout <src> -- src/ README.md（不含 pom）。
新建/核对清单（8 步）
复制 assets/pom-template.xml → 替换占位符 → 按分支填 version/java.version（无 parent，lombok 显式版本）→ 核对三段式 → 源码三件套（Client/Config/能力域）→ 测试 → mvn clean verify → 多分支创建。完整演练见 examples/create-component.md。
References（按需加载）
| 文件 | 何时读 |
|---|---|
| references/pom-structure.md | 写/改 pom 时：无 parent 结构详解、三段式全量、build 插件配置表、依赖四组 |
| references/branch-release.md | 分支/发版时：多 JDK 分支同步法、同线依赖、tag 发布 5 步、滚动更新 |
| references/maven4.md | 用 Maven 4 构建时：M3/M4 差异、运行 JDK 17+、maven.version 基线、consumer POM（原生替代 flatten）、wrapper 迁移 |
| examples/create-component.md | 从零封装组件的 8 步演练 |
| examples/maven4-migration.md | 迁 Maven 4 时：自管插件对照、移除 flatten（consumer POM 原生替代）、三分支验证、4.1.0 session scope 升级判断 |
| assets/pom-template.xml | Maven 3 / model 4.0.0 模板（M3/M4 双轨，XML 校验通过） |
| assets/pom-template-maven4.xml | Maven 4 / model 4.1.0 模板（enforcer [4.0.0,)、session scope 示例、无 flatten） |
质量门禁
- JaCoCo：BUNDLE LINE ≥ 0.90，haltOnFailure=true
- 测试：JUnit 5（junit-jupiter）+ AssertJ
- Javadoc：英语；类级 summary + @author/@since；方法级 @param/@return