用途
该技能用于创建新的 Spring Boot 4 项目，或在实现之前定义项目结构。当用户需要架构决策、Spring Boot 4 特性选择，或需要使用 assets/ 中捆绑的模板时，该技能能提供帮助。
关键规则
- 在评估项目复杂度之前，绝不直接进入实现。
- 默认采用适合该领域的最简单架构。
- 以 Spring Boot 4 为目标。新项目默认使用 Java 25（当前 LTS）。Boot 4 的官方基线是 Java 17——当用户要求时，可接受 Java 21（上一个 LTS）或 Java 17。Java 26 是最新的特性版本（GA 2026-03-17），但属于非 LTS；仅当项目跟踪非 LTS Java 时才选择它。
- 在选择更高复杂度的架构或可选框架特性之前，先阅读参考文件。
- 复用 assets/ 中的模板，而不是从头重写相同的脚手架。
工作流程
第 1 步：评估项目形态
首先收集项目约束：
- 领域复杂度：简单 CRUD、中等工作流，还是丰富的领域规则。
- 团队规模：1-3 人、3-10 人，还是 10 人以上。
- 预期生命周期：数月、1-2 年，还是 5 年以上。
- 类型安全需求：基础校验，还是强值对象建模。
- 限界上下文：单一领域还是多个功能区域。
- 持久化与基础设施需求：数据库选择、迁移工具、本地开发环境搭建。
第 2 步：选择架构
使用以下矩阵作为默认决策辅助。如果选择不明显，请先阅读 references/architecture-guide.md 再继续。
| 模式 | 适用场景 | 复杂度 |
|---|---|---|
| layered | CRUD 服务、原型、MVP | 低 |
| package-by-module | 3-5 个不同功能且中等增长 | 低-中 |
| modular-monolith | 模块边界重要且 Spring Modulith 合理 | 中 |
| tomato | 丰富领域建模、值对象、更强类型安全 | 中-高 |
| ddd-hexagonal | 复杂领域、CQRS、强基础设施隔离 | 高 |
tomato 是一种值对象密集的模块化单体：JPA 实体嵌入 VO，校验位于 VO 构造函数中，Spring 转换器在请求边界绑定 VO。完整定义见 references/architecture-guide.md。
第 3 步：定义初始 Boot 4 设置
使用 Spring Initializr 并记录基线：
- 项目：Maven 或 Gradle
- 语言：Java
- Spring Boot：4.1.x
- Java：25（推荐——当前 LTS）。Boot 4 最低为 Java 17；上一个 LTS 用 21，更严格兼容用 17。Java 26（GA 2026-03-17）是最新特性版本，但为非 LTS。
大多数项目的基线依赖：
- Spring Web MVC
- Validation
- 如需持久化则使用 Spring Data JPA
- Flyway 或 Liquibase
- 数据库驱动
- Spring Boot Actuator
- 用于集成测试的 Testcontainers
基于架构或特性的可选依赖：
- 用于模块化单体或 tomato 设计的 Spring Modulith
- 用于更强架构约束的 ArchUnit
- 仅当用例需要时，才添加其他 Spring Boot 4 特性
选择前阅读 references/spring-boot-4-features.md：
- RestTestClient
- HTTP Service Clients
- API 版本控制
- JSpecify 空安全
- 弹性特性
第 4 步：应用匹配的 assets
使用 assets/ 中捆绑的模板，仅在包名和模块名确定后替换占位符。
占位符约定
每个模板都使用 {{TOKEN}} 占位符。应用前需解析所有占位符——在替换每个占位符之前，模板无法编译。assets/ 中使用的完整集合：
| 占位符 | 替换为 | 示例 |
|---|---|---|
| {{PACKAGE}} | 基础 Java 包 | com.acme.shop |
| {{MODULE}} | 功能/模块名（小写） | orders |
| {{NAME}} | 领域类型名（PascalCase） | Order, ProductSKU |
| {{TYPE}} | 值对象内包装的标量类型 | String, Long, BigDecimal |
| {{FIELD}} | 记录字段名（camelCase） | code, amount |
| {{TABLE_NAME}} | 数据库表名（用于 JPA @Table） | orders |
| {{TABLE}} | 与 {{TABLE_NAME}} 含义相同——仅保留在 flyway-migration.sql 中的旧变体 | orders |
| {{PROJECT_NAME}} | 项目 artifactId / docker 前缀（仅用于 docker-compose.yml） | shop-api |
| {{name}} | HTTP 服务组标识符——不是 {{NAME}} 的小写变体。仅出现在注释掉的 @ImportHttpServices(group = "...") 示例中。 | orders |
如果模板使用了此处未列出的占位符，请将其视为拼写错误，并在应用前确认预期值。
核心项目模板：
- assets/controller.java
- assets/repository.java
- assets/base-entity.java
- assets/rich-entity.java
- assets/value-object.java
- assets/spring-converter.java
- assets/service-cqrs.java
- assets/exception-handler.java
- assets/flyway-migration.sql
- assets/docker-compose.yml
Boot 4 与模块化模板：
- assets/http-service-client.java
- assets/api-versioning-config.java
- assets/resttestclient-test.java
- assets/package-info-jspecify.java
- assets/modularity-test.java
- assets/resilience-service.java
- assets/pom-additions.xml
- assets/testcontainers-test.java
第 5 步：填充架构特定部分
阅读 references/architecture-guide.md 了解包结构，并应用匹配的模板：
- layered：保持模块简单，避免过早的 DDD 抽象
- package-by-module：按功能分组，保持共享代码最少
- modular-monolith：添加 Modulith 验证和显式模块 API
- tomato：在能保护重要不变量的地方添加值对象和丰富领域实体
- ddd-hexagonal：明确分离 application、domain 和 infrastructure
第 6 步：在需要时移交专门关注点
- 当用户需要更深入的查询、投影、仓库或关系决策时，使用 spring-data-jpa。
- 对现有应用程序的升级而非新项目设置，使用 springboot-migration。
参考加载指南
- 包结构、反模式和升级路径：references/architecture-guide.md
- Spring Boot 4 特性特定指导：references/spring-boot-4-features.md
输出格式
当用户要求计划或脚手架建议时，返回：
Recommended architecture
- Pattern:
- Why:
Initial setup
- Build tool:
- Java version:
- Spring Boot version:
- Core dependencies:
Assets to apply
assets/...
Next implementation steps
- ...
- ...
- ...
何时不使用此技能
- 迁移现有 Boot 项目
- 在没有更广泛项目创建工作时进行深度仓库和查询调优
- 不需要捆绑模板的通用 Spring Boot 特性问答