# Spring Boot 架构技能集

`Spring Boot` `架构模式` `Claude Code` `代码生成` `DDD`

# Spring Boot 技能市场

帮助你构建真正适合需求的 Spring Boot 应用架构的 Claude Code 技能集。

## 为什么存在

项目起初简单，往往越来越混乱。这些技能帮助你根据当前阶段选择合适的架构——并在复杂度增加时提供清晰的演进路径。

> **从简单开始。只在复杂度真正需要时才引入复杂度。**

基于 [spring-boot-application-architecture-patterns](https://github.com/sivaprasadreddy/spring-boot-application-architecture-patterns) 中的模式构建。

## 架构模式（渐进式）

| 模式 | 复杂度 | 适用场景 |
|------|--------|----------|
| **分层架构** | ⭐ 低 | 简单 CRUD、原型、MVP |
| **按模块分包** | ⭐⭐ 低-中 | 3-5 个独立功能、中型应用 |
| **模块化单体** | ⭐⭐ 中 | 需要模块边界、Spring Modulith |
| **Tomato** | ⭐⭐⭐ 中-高 | 丰富领域、值对象、类型安全 |
| **DDD+六边形** | ⭐⭐⭐⭐ 高 | 复杂领域、CQRS、基础设施解耦 |

## 安装

> **使用 Codex？** 请参阅 [CODEX-COMPATIBILITY.md](./CODEX-COMPATIBILITY.md) 获取详细的 Codex 安装和使用说明。

### Claude Code（插件市场）

```bash
/plugin marketplace add a-pavithraa/springboot-skills-marketplace
/plugin enable a-pavithraa/springboot-skills-marketplace
/plugin install springboot-architecture@springboot-skills-marketplace
```

### Claude Code（手动安装）

```bash
# 克隆或下载本仓库
git clone https://github.com/a-pavithraa/springboot-skills-marketplace.git

# 将技能复制到 Claude Code 技能目录
cp -r springboot-skills-marketplace/plugins/springboot-architecture/skills/* ~/.claude/skills/
```

### Codex（手动安装）

```bash
# 克隆或下载本仓库
git clone https://github.com/a-pavithraa/springboot-skills-marketplace.git

# 将技能复制到 Codex 技能目录
mkdir -p ~/.codex/skills
cp -r springboot-skills-marketplace/plugins/springboot-architecture/skills/* ~/.codex/skills/
```

## 使用方法

### Claude Code

技能在相关场景下会被自动发现和加载。Claude 会根据你的请求自动调用：

```
你："我需要创建一个新的 Spring Boot 微服务"
Claude：[自动加载 creating-springboot-projects 技能]
```

也可以显式请求某个技能：
```
你："使用 spring-data-jpa 技能优化这个 Repository"
```

### Codex

技能需要使用 `$skill-name` 语法手动调用：

```
using $creating-springboot-projects create a new order service
using $spring-data-jpa optimize this repository code
using $springboot-migration upgrade to Spring Boot 4
using $code-reviewer review this service implementation
```

如需引用详细参考章节，请包含路径：
```
using $spring-data-jpa and ~/.codex/skills/spring-data-jpa/references/dto-projections.md implement efficient queries
```

## 可用技能

### creating-springboot-projects

通过几个问题了解你的项目，然后从一开始就构建正确的架构。

你将获得：评估驱动的脚手架生成、Spring Initializr 配置，以及值对象、富实体、CQRS 模式、转换器等模板——根据所选架构按需提供。

**快速评估涵盖：**
- 领域复杂度（CRUD vs. 业务规则）
- 团队规模和项目生命周期
- 类型安全需求
- 限界上下文

### spring-data-jpa

帮助你写出六个月后也不会拖慢系统的 JPA 代码。

涵盖查询模式、DTO 投影、自定义 Repository、CQRS 查询服务，以及最终会坑到所有人的性能反模式（为每个实体建 Repository、方法名查询地狱、盲目调用 `save()`）。

### springboot-migration

逐步迁移到 Spring Boot 4 + Java 25（支持 Spring Modulith 2 和 Testcontainers 2）。

先扫描你的项目，再分阶段引导完成依赖 → 代码 → 配置的迁移。包含重试/韧性模式以及每个升级目标的参考文档。

### code-reviewer

对你的 Boot 4 / Java 25 项目进行架构适配性和性能问题的全面检查。

涵盖五种架构模式（何时使用、何时避免），以及事件、CQRS、Modulith 边界的检查清单。能发现 N+1 查询、缺失缓存、虚拟线程锁定等性能陷阱。

当你需要第二意见，或需要判断是否到了演进架构的时候，使用此技能。

## 使用示例

**"我需要一个基本 CRUD 的产品 REST API。"**
→ 询问你的领域、团队和时间线，建议分层架构，生成脚手架。

**"我需要一个包含支付和库存规则的订单服务。"**
→ 评估复杂度，推荐 Tomato 架构，生成值对象、富实体、CQRS 服务。

**"我的产品搜索很慢。"**
→ 分析查询，发现 N+1 问题，重构为 DTO 投影。

**"我们需要从 Boot 3 迁移到 Boot 4。"**
→ 运行迁移扫描器，规划分阶段升级（依赖 → 代码 → 配置），逐步应用并验证。

**"能帮我们审查 Boot 4 服务是否有问题吗？"**
→ 检查架构模式适配性，排查性能问题（N+1、缺失缓存、虚拟线程锁定、实体泄漏）。

## 模板与资源

**架构模板**（`creating-springboot-projects/assets/`）
值对象、富实体、CQRS 服务、转换器、REST 控制器、Flyway 迁移、Testcontainers、ProblemDetail 处理器。

**JPA 模板**（`spring-data-jpa/assets/`）
查询 Repository、DTO 投影、自定义 Repository、CQRS 查询服务、关联关系模式。

**审查参考**（`java25-springboot4-reviewer/references/`）
架构模式、决策矩阵、性能检查清单。

**参考指南**（`spring-data-jpa/references/`）
查询模式、投影、自定义 Repository、关联关系处理、性能调优。

## 测试技能

想验证技能是否按预期工作？请查看 `tests/` 目录中的基线场景。

**快速开始：**
```bash
# 5 分钟内运行一个场景
cd tests
cat QUICKSTART.md
```

**完整测试套件：**
- 8 个基线场景，测试每个技能的核心行为
- RED-GREEN-REFACTOR 方法论
- 合理化追踪
- 完整测试指南见 `tests/README.md`

基于 [terraform-skill 测试方法](https://github.com/antonbabenko/terraform-skill/blob/master/tests/baseline-scenarios.md)。

## 前置条件

- Claude Code CLI
- Java 25
- Maven 或 Gradle
- 熟悉 Spring Boot 4.0+

## 演进路径

从简单开始，按需演进：

```text
分层架构 → 按模块分包 → 模块化单体 → Tomato → DDD+六边形
```

## 致谢

- 架构模式：[Siva Prasad Reddy](https://github.com/sivaprasadreddy)
- Spring Boot 4 特性：[spring-boot-4-features](https://github.com/sivaprasadreddy/spring-boot-4-features)
- 模块化单体参考：[spring-modular-monolith](https://github.com/sivaprasadreddy/spring-modular-monolith)
- 市场灵感来源：[sivalabs-marketplace](https://github.com/sivaprasadreddy/sivalabs-marketplace)
- JPA/Hibernate 最佳实践：[Vlad Mihalcea](https://vladmihalcea.com/blog/)