197 lines
6.8 KiB
Markdown
197 lines
6.8 KiB
Markdown
# 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/) |