1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | hexagonal-architecture-rrezartprebreza-spring-boot-skills |
| 作者/维护者 | rrezartprebreza（个人开发者） |
| 来源链接 | https://github.com/rrezartprebreza/spring-boot-skills/tree/main/skills/spring-boot-4/hexagonal-architecture |
| 许可证 | MIT（数据来源：GitHub API） |
| GitHub Stars | 199（整个 spring-boot-skills 合集仓库；该数字属整个合集，不代表本技能自身热度，数据来源：GitHub API） |
| Forks | 35（同上，合集整体，GitHub API 获取） |
| 最新版本 | 无独立版本号，仓库不使用 GitHub Release 标签；仓库整体最近一次提交为 2026-07-30（GitHub API 获取） |
| 安装方式 | 复制该子目录到 agent 的 skills 目录，或用第三方技能市场 npx skills add 单独拉取（见第 10 章） |
2. 功能介绍与亮点
这是一份 Spring Boot 应用采用六边形架构（Ports & Adapters，端口与适配器模式）时的编码规范，核心内容：
- 三层包结构：
domain/（纯 Java，零框架依赖，含实体、值对象、领域服务）、application/（编排用例，可以用 Spring 注解）、infrastructure/（承载全部框架/数据库/HTTP 细节，含持久化适配器、REST 控制器、外部客户端） - 驱动端口与被驱动端口：
port/in定义应用对外提供的用例接口，port/out定义应用依赖的仓储/外部系统接口，两者严格分离 - 领域层零依赖示例：给出不含任何 JPA/Spring 注解的纯 Java 实体与值对象写法，配合适配器如何在基础设施层把领域对象与 JPA 实体互相转换
- 7 类 “agent 常见错误” 对照清单：领域类误引入
jakarta.persistence、用例直接注入JpaRepository而非领域端口、把@Transactional错放在领域服务、混淆驱动/被驱动端口方向、领域模型退化成只有 getter/setter 的贫血对象、测试里用已在 Boot 4 移除的@MockBean而非@MockitoBean、误用改名后的spring-boot-starter-aspectj依赖
全部内容为纯 Markdown 文档配 Java 代码示例（用例与适配器的好坏对照、JPA 适配器与实体模板），无外部脚本或可执行文件。
3. 适用场景
所属分类：工程效率与代码质量——内容是关于“怎么写代码”的架构分层规范，不涉及外部系统集成，也不是 agent 自身配置类内容。
适合团队已决定或正在评估采用六边形架构、希望领域逻辑完全独立于 Spring/JPA 框架细节的场景：为遗留系统做架构重构、多团队协作时需要清晰的端口边界防止基础设施细节渗透进业务逻辑、或希望未来更换持久化方案（如从 JPA 换成其他存储）时业务代码不受影响。目标用户是已具备一定架构经验、愿意为更高的可测试性和框架无关性接受额外抽象层的中高级开发者。
4. 跨 Agent 兼容性
- Claude Code：原生支持 ✅——仓库徽章明确标注兼容，README 提供
.claude/skills/安装路径 - Codex：原生支持 ✅——仓库徽章明确标注兼容，README 提供
.codex/skills/安装路径 - OpenClaw：未验证——SKILL.md 遵循标准 YAML front matter + Markdown 正文格式，理论上可迁移，但仓库文档未点名支持
- Hermes Agent：未验证——同上，未见任何提及
5. 推荐理由
六边形架构要求业务逻辑完全独立于框架细节，但 AI agent 生成代码时最容易图省事，在领域类里直接引入 JPA 注解、或让用例直接依赖 JpaRepository 而不是领域端口接口——这些问题不会导致编译报错，只会在真要替换基础设施时才暴露代价。这份技能把端口方向、分层边界与 7 类 agent 常见越界错误整理成可直接对照的代码示例，让已经选定六边形架构的团队能把这份纪律直接交给 agent 执行。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 5 | 该子目录本身尚无独立第三方评测或引用；所属合集仓库由单一开发者维护，199 星与 35 复刻数字属整体仓库，不可归给单个子技能；第三方技能市场 skills.sh 显示该子技能被独立安装 49 次，在本仓库 19 个 Spring Boot 4 子技能中排名靠前，但仍属起步阶段的小体量数字 |
| 可用性 | 9 | 复制单个文件夹即可安装，无需配置或付费依赖；仓库最近一次提交为 2026-07-30，该子技能内容本身最近一次修订约一个月前；正文含完整可直接复制的领域层、端口、用例、适配器代码示例 |
| 安全性 | 9 | 纯 Markdown 文档配 Java 示例，技能自身不执行任何命令、不联网、不要求任何凭据；许可证明确（MIT）；内容未见任何可疑指令或误导性说明 |
综合评分：7.7
安全检查清单逐项结果：① Shell 命令/权限范围——无，纯文本内容不涉及代码执行；② 联网外发——无；③ API key/凭据——不需要；④ 可疑指令——通读 SKILL.md 及全部代码示例未发现任何提示注入或隐蔽指令迹象；⑤ 作者信誉——个人开发者，无造假迹象；⑥ License——MIT，明确；⑦ 最近维护——约一个月前仍有提交，属活跃维护。
7. 跟同类 Skills 相比的优势
| 对比对象 | 定位 | 与本技能的差异 |
|---|---|---|
| domain-driven-design-wondelai-skills | 通用、语言/框架无关的 DDD 方法论技能，覆盖限界上下文、通用语言、聚合设计诊断打分 | 面向“如何做业务建模决策”的战略层，不绑定具体技术栈；本技能面向已经决定用六边形架构的 Spring Boot 项目，给出的是可直接落地的包结构与 Java 代码示例，是战术实现层而非方法论层 |
| layered-architecture-rrezartprebreza-spring-boot-skills（同仓库另一子技能） | Controller-Service-Repository 三层架构，是大多数 Spring Boot 项目的默认起点 | 学习成本更低，不要求额外抽象层；本技能面向愿意接受端口/适配器额外抽象、追求领域层完全框架无关的进阶团队，两者服务的是不同架构选择阶段的团队 |
| piomin/claude-ai-spring-boot（1266 星） | 单个 SKILL.md 覆盖 REST、JPA、Security、Testing、Actuator 部署全流程的通用型技能 | 定位为“全能型”单一技能，不专门覆盖六边形架构的端口/适配器分层规则；仓库最近一次更新在 2026-04-29，三个多月未再更新 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。
9. 其他补充
仓库同时维护 Spring Boot 3 分支下的等价版本（skills/spring-boot-3/hexagonal-architecture），端口/适配器分层规则与领域层零依赖原则不变，Boot 4 专属的 gotcha（如 @MockitoBean 替代已移除的 @MockBean、spring-boot-starter-aspectj 改名）在 Boot 3 分支不适用。
10. 安装使用方式
Claude Code：
mkdir -p "$PROJECT_DIR/.claude/skills"
cp -r skills/spring-boot-4/hexagonal-architecture "$PROJECT_DIR/.claude/skills/"Codex：
mkdir -p "$PROJECT_DIR/.codex/skills"
cp -r skills/spring-boot-4/hexagonal-architecture "$PROJECT_DIR/.codex/skills/"也可用第三方技能市场 skills.sh 提供的命令单独拉取：
npx skills add https://github.com/rrezartprebreza/spring-boot-skills --skill hexagonal-architecture安装后无需重启 agent，下次涉及领域层、端口、用例或适配器相关代码的对话会自动触发该技能。
11. 注意事项
- 内容以 Spring Data JPA 为默认持久层适配器示例，若项目使用其他持久化方案，
infrastructure/persistence层的具体适配器代码需自行调整 - 六边形架构比默认的三层架构多一层抽象成本，适合已明确评估过收益的团队，而非所有 Spring Boot 项目的起点选择
- 仓库由单一个人开发者维护，无官方或厂商背书，长期维护延续性依赖作者个人投入