1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | layered-architecture-rrezartprebreza-spring-boot-skills |
| 作者/维护者 | rrezartprebreza（个人开发者） |
| 来源链接 | https://github.com/rrezartprebreza/spring-boot-skills/tree/main/skills/spring-boot-4/layered-architecture |
| 许可证 | MIT（GitHub API 获取） |
| GitHub Stars | 198（整个 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 应用 Controller → Service → Repository 三层架构的编码规范，把每层该做什么、不该做什么整理成对照代码示例。核心内容：
- 分层职责边界：Controller 只处理 HTTP 解析与响应，每个接口只调一次 Service 方法，不直接注入 Repository，不把
@Entity直接作为响应体返回；Service 层承载全部业务逻辑与编排，@Transactional只放在这一层，构造器注入而非字段注入，每个聚合根对应一个 Service（而非把多个聚合塞进一个大类）；Repository 层只做数据访问，不含业务逻辑 - DTO 与 Mapper 规范：请求 DTO 与响应 DTO 分离，用 Java record 定义不可变 DTO，映射逻辑抽到独立 Mapper 类或静态工厂方法，不散落在 Controller 或 Service 里
- Configuration 层隔离：
@Configuration类单独归入config/包，只负责基础设施 Bean（RestClient、JsonMapper、SecurityFilterChain 等），不依赖 Service/Controller - 横切关注点：统一用
@Slf4j日志、单一@RestControllerAdvice处理异常、@EnableJpaAuditing做审计字段 - 8 类 “agent 常见错误” 对照清单：字段注入而非构造器注入、把
@Transactional错放在 Controller、Controller 直接返回实体列表、把多个聚合合并成一个大 Service、映射逻辑写进 Controller、Configuration 类依赖 Service Bean、Spring Boot 4 下 Jackson 3 的ObjectMapper应改用JsonMapper（@JsonComponent也改名为@JacksonComponent）、忘记 Framework 7 内置的@Retryable/@EnableResilientMethods而误加 spring-retry 依赖
全部内容为纯 Markdown 文档配 Java 代码示例，无外部脚本或可执行文件。
3. 适用场景
所属分类：工程效率与代码质量——内容是关于“怎么写代码”的架构分层与命名规范，不涉及外部系统集成，也不是 agent 自身配置类内容。
三层架构是绝大多数 Spring Boot 应用的默认起点，无论团队最终是否叠加 DDD、六边形架构等更进阶的方法论，都绕不开这一层——适用面比“是否采用某种特定架构方法论”更广。尤其适合让 agent 从零生成 CRUD 接口、或新成员刚接手项目的场景：能提前拦下“业务逻辑写进 Controller”“实体类直接序列化返回”“字段注入替代构造器注入”这类 agent 生成代码时容易犯、但代码评审阶段才会被发现的问题。
4. 跨 Agent 兼容性
- Claude Code：原生支持——仓库明确提供
.claude/skills/安装路径与徽章标注兼容 - Codex：原生支持——仓库同时提供
.codex/skills/安装路径与徽章标注兼容 - OpenClaw：未验证——SKILL.md 遵循标准 YAML front matter + Markdown 正文格式，理论上可迁移，但仓库文档未点名支持
- Hermes Agent：未验证——同上，未见任何提及
5. 推荐理由
Controller-Service-Repository 分层是几乎所有 Spring Boot 应用的默认架构起点，但 AI agent 生成代码时最容易在这一层踩坑——把校验逻辑写进 Controller、用字段注入、把 JPA 实体直接当响应体返回。这份技能把每层职责边界与 8 类 agent 常见错误整理成可直接对照的清单，还专门覆盖了 Spring Boot 4 / Framework 7 的新变化（Jackson 3 序列化器改名、内置韧性注解取代 spring-retry），对既要写对分层代码、又要跟上框架升级的团队都实用。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 5 | 该子目录本身尚无独立第三方评测或引用；所属合集仓库由单一开发者维护，198 星与 35 复刻数字属整体仓库，不可归给单个子技能；第三方技能市场 skills.sh 显示该子技能被独立安装 58 次，是本仓库 19 个 Spring Boot 4 子技能中安装数最高的一个，但仍属起步阶段的小体量数字 |
| 可用性 | 9 | 复制单个文件夹即可安装，无需配置或付费依赖；仓库最近一次修订为 2026-07-30；正文含完整可直接复制的 Java 代码示例，覆盖 Controller / Service / Repository / DTO / Mapper / Configuration 各层 |
| 安全性 | 9 | 纯 Markdown 文档配 Java 示例，技能自身不执行任何命令、不联网、不要求任何凭据；许可证明确（MIT）；第三方平台 skills.sh 显示 Socket 与 Snyk 两项独立安全审计均为 Pass；内容未见任何可疑指令或误导性说明 |
综合评分：7.7
7. 跟同类 Skills 相比的优势
| 项目 | 定位 | 与本技能的差异 |
|---|---|---|
| piomin/claude-ai-spring-boot 的 spring-boot 技能（1266 星） | 单个 SKILL.md 覆盖 REST、JPA、Security、Testing、Actuator 部署全流程的通用型企业级 Spring Boot 技能 | 定位为“全能型”单一技能，分层架构只是其中一小节而非独立深入内容；仓库最近一次更新在 2026-04-29，三个多月未再更新；本技能专注分层架构本身，逐层列出边界规则与 agent 常见错误对照代码，颗粒度更细，且随 Spring Boot 4 当前版本同步维护 |
| hexagonal-architecture（同仓库另一子技能） | 端口与适配器模式，让领域层完全独立于框架依赖 | 面向已决定采用六边形架构、愿意接受额外抽象层的团队；本技能面向默认的三层架构，学习成本更低，是大多数 Spring Boot 项目的起点而非进阶选择 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。
9. 其他补充
仓库同时维护 Spring Boot 3 分支下的等价版本（skills/spring-boot-3/layered-architecture），分层职责边界与 Mapper/DTO 规范不变，Boot 4 专属的 Jackson 3 命名变化与 Framework 7 内置韧性注解在 Boot 3 分支不适用。
10. 安装使用方式
Claude Code：
mkdir -p "$PROJECT_DIR/.claude/skills"
cp -r skills/spring-boot-4/layered-architecture "$PROJECT_DIR/.claude/skills/"Codex：
mkdir -p "$PROJECT_DIR/.codex/skills"
cp -r skills/spring-boot-4/layered-architecture "$PROJECT_DIR/.codex/skills/"也可用第三方技能市场 skills.sh 提供的命令单独拉取：
npx skills add https://github.com/rrezartprebreza/spring-boot-skills --skill layered-architecture安装后无需重启 agent，下次涉及 Controller、Service、Repository 或 DTO/Mapper 相关代码的对话会自动触发该技能。
11. 注意事项
- 内容以 Spring Data JPA 为默认持久层假设，若项目使用 MyBatis 等其他持久化方案，Repository 层的具体规则需自行调整
- Spring Boot 4 迁移相关的 gotcha 清单覆盖的是仓库 2026-07-30 最近一次更新时已知的变化，后续小版本若继续调整相关 API 需自行核实
- 仓库由单一个人开发者维护，无官方或厂商背书，长期维护延续性依赖作者个人投入