spring-boot-project-creator

Spring Boot 项目创建器

概述

使用 Spring Initializr API 从头生成配置齐全的 Spring Boot 项目。该技能会引导用户选择项目参数、架构风格（DDD 或 Layered）、数据存储，并为本地开发设置 Docker Compose。最终生成的项目可直接构建，具有标准化的结构、依赖管理和配置。

使用场景

• 使用标准结构快速创建 Spring Boot 3.x 或 4.x 项目。
• 初始化包含 JPA、SpringDoc OpenAPI 和 Docker Compose 的后端微服务。
• 搭建采用 DDD（领域驱动设计）或 Layered（Controller/Service/Repository/Model）架构的项目。
• 通过 Docker Compose 设置本地开发基础设施，使用 PostgreSQL、Redis 和/或 MongoDB。
• 触发短语：“create spring boot project”、“new spring boot app”、“bootstrap java project”、“scaffold spring boot microservice”、“initialize spring boot backend”、“generate spring boot project”。

前置条件

开始之前，请确保已安装以下工具：

• Java Development Kit (JDK)：17+ 版本（Spring Boot 3.x/4.x 推荐使用 Java 21）
• Apache Maven：构建工具（Spring Initializr 默认生成 Maven 项目）
• Docker 和 Docker Compose：用于运行本地基础设施服务
• curl 和 unzip：用于从 Spring Initializr 下载并解压项目

操作说明

按照以下步骤创建新的 Spring Boot 项目。

1. 收集项目配置

使用 AskUserQuestion 询问用户以下项目参数，并提供合理的默认值：

参数	默认值	选项
Group ID	com.example	任意有效的 Java 包名
Artifact ID	demo	kebab-case 标识符
Package Name	与 Group ID 相同	有效的 Java 包名
Spring Boot Version	3.4.5	3.4.x、4.0.x（查看 start.spring.io 获取最新版本）
Java Version	21	17、21
Architecture	由用户选择	DDD 或 Layered
Docker Services	由用户选择	PostgreSQL、Redis、MongoDB（可多选）
Build Tool	maven	maven、gradle

2. 使用 Spring Initializr 生成项目

使用 curl 从 start.spring.io 下载项目脚手架。

基础依赖（始终包含）：

• web — Spring Web MVC
• validation — Jakarta Bean Validation
• data-jpa — Spring Data JPA
• testcontainers — Testcontainers 支持

条件依赖（根据 Docker Services 选择添加）：

• 选择 PostgreSQL → 添加 postgresql
• 选择 Redis → 添加 data-redis
• 选择 MongoDB → 添加 data-mongodb

# Example for Spring Boot 3.4.5 with PostgreSQL only
curl -s https://start.spring.io/starter.zip \
  -d type=maven-project \
  -d language=java \
  -d bootVersion=3.4.5 \
  -d groupId=com.example \
  -d artifactId=demo \
  -d packageName=com.example \
  -d javaVersion=21 \
  -d packaging=jar \
  -d dependencies=web,data-jpa,postgresql,validation,testcontainers \
  -o starter.zip

unzip -o starter.zip -d ./demo
rm starter.zip
cd demo

3. 添加其他依赖

编辑 pom.xml，添加 SpringDoc OpenAPI 和用于架构测试的 ArchUnit。

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.15</version>
</dependency>


<dependency>
    <groupId>com.tngtech.archunit</groupId>
    <artifactId>archunit-junit5</artifactId>
    <version>1.4.1</version>
    <scope>test</scope>
</dependency>

4. 创建架构结构

根据用户的选择，在 src/main/java/<packagePath>/ 下创建包结构。

选项 A：Layered 架构

src/main/java/com/example/
├── controller/        # REST controllers (@RestController)
├── service/           # Business logic (@Service)
├── repository/        # Data access (@Repository, Spring Data interfaces)
├── model/             # JPA entities (@Entity)
│   └── dto/           # Request/Response DTOs (Java records)
├── config/            # Configuration classes (@Configuration)
└── exception/         # Custom exceptions and @ControllerAdvice

为每一层创建占位类：

• config/OpenApiConfig.java — SpringDoc OpenAPI 配置 Bean
• exception/GlobalExceptionHandler.java — 带有标准错误处理的 @RestControllerAdvice
• model/dto/ErrorResponse.java — 标准错误响应 record

选项 B：DDD（领域驱动设计）架构

src/main/java/com/example/
├── domain/                 # Core domain (framework-free)
│   ├── model/              # Entities, Value Objects, Aggregates
│   ├── repository/         # Repository interfaces (ports)
│   └── exception/          # Domain exceptions
├── application/            # Use cases / Application services
│   ├── service/            # @Service orchestration
│   └── dto/                # Input/Output DTOs (records)
├── infrastructure/         # External adapters
│   ├── persistence/        # JPA entities, Spring Data repos
│   └── config/             # Spring @Configuration
└── presentation/           # REST API layer
    ├── controller/         # @RestController
    └── exception/          # @RestControllerAdvice

为每一层创建占位类：

• infrastructure/config/OpenApiConfig.java — SpringDoc OpenAPI 配置 Bean
• presentation/exception/GlobalExceptionHandler.java — 带有标准错误处理的 @RestControllerAdvice
• application/dto/ErrorResponse.java — 标准错误响应 record

5. 配置应用属性

创建 src/main/resources/application.properties，并添加所选服务。

始终包含：

# Application
spring.application.name=${artifactId}

# SpringDoc OpenAPI
springdoc.swagger-ui.doc-expansion=none
springdoc.swagger-ui.operations-sorter=alpha
springdoc.swagger-ui.tags-sorter=alpha

如果选择了 PostgreSQL：

# PostgreSQL / JPA
spring.datasource.driver-class-name=org.postgresql.Driver
spring.datasource.url=jdbc:postgresql://localhost:5432/${POSTGRES_DB:postgres}
spring.datasource.username=${POSTGRES_USER:postgres}
spring.datasource.password=${POSTGRES_PASSWORD:changeme}
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

如果选择了 Redis：

# Redis
spring.data.redis.host=localhost
spring.data.redis.port=6379
spring.data.redis.password=${REDIS_PASSWORD:changeme}

如果选择了 MongoDB：

# MongoDB
spring.data.mongodb.host=localhost
spring.data.mongodb.port=27017
spring.data.mongodb.authentication-database=admin
spring.data.mongodb.username=${MONGO_USER:root}
spring.data.mongodb.password=${MONGO_PASSWORD:changeme}
spring.data.mongodb.database=${MONGO_DB:test}

6. 设置 Docker Compose

在项目根目录创建 docker-compose.yaml，仅包含用户选择的服务。

services:
  # Include if PostgreSQL selected
  postgresql:
    image: postgres:17
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-postgres}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-changeme}
      POSTGRES_DB: ${POSTGRES_DB:-postgres}
    volumes:
      - ./postgres_data:/var/lib/postgresql/data

  # Include if Redis selected
  redis:
    image: redis:7
    ports:
      - "6379:6379"
    command: redis-server --requirepass ${REDIS_PASSWORD:-changeme}
    volumes:
      - ./redis_data:/data

  # Include if MongoDB selected
  mongodb:
    image: mongo:8
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: ${MONGO_USER:-root}
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD:-changeme}
    volumes:
      - ./mongo_data:/data/db

7. 创建 Docker Compose 的 .env 文件

在项目根目录创建 .env 文件，并为本地开发设置默认凭据：

# PostgreSQL
POSTGRES_USER=postgres
POSTGRES_PASSWORD=changeme
POSTGRES_DB=postgres

# Redis
REDIS_PASSWORD=changeme

# MongoDB
MONGO_USER=root
MONGO_PASSWORD=changeme
MONGO_DB=test

仅包含用户选择的服务所需的变量。Docker Compose 会自动加载此文件。

8. 更新 .gitignore

将 Docker Compose 卷目录和 .env 文件追加到 .gitignore：

# Docker Compose
.env
postgres_data/
redis_data/
mongo_data/

9. 验证构建

运行 Maven 构建，确认项目可以编译且测试通过：

./mvnw clean verify

如果构建成功，请告知用户。如果失败，请先诊断并修复问题，再继续操作。

10. 向用户展示摘要

显示所创建项目的摘要：

Project Created Successfully

  Artifact:      <artifactId>
  Spring Boot:   <version>
  Java:          <javaVersion>
  Architecture:  <DDD | Layered>
  Build Tool:    Maven
  Docker:        <services list>

  Directory:     ./<artifactId>/

  Next Steps:
    1. cd <artifactId>
    2. docker compose up -d
    3. ./mvnw spring-boot:run
    4. Open http://localhost:8080/swagger-ui.html

架构模式

分层架构

采用职责分离明确的传统三层架构：

层	包	职责
表现层	controller/	HTTP 端点、请求／响应映射
业务层	service/	业务逻辑、事务管理
数据访问层	repository/	通过 Spring Data 执行数据库操作
领域层	model/	JPA 实体和 DTO

适用于： 简单的 CRUD 应用、小型到中型服务，以及刚开始使用 Spring Boot 的团队。

DDD 架构

采用六边形边界的领域驱动设计：

层	包	职责
领域层	domain/	实体、值对象、领域服务（不依赖框架）
应用层	application/	用例、编排、DTO 映射
基础设施层	infrastructure/	JPA 适配器、外部集成、配置
表现层	presentation/	REST 控制器、错误处理

适用于： 复杂的业务领域、包含丰富业务逻辑的微服务，以及长期维护的项目。

示例

示例 1：使用 PostgreSQL 的简单 REST API（分层架构）

用户请求：“创建一个使用 PostgreSQL 的 Spring Boot REST API 项目”

curl -s https://start.spring.io/starter.zip \
  -d type=maven-project \
  -d bootVersion=3.4.5 \
  -d groupId=com.example \
  -d artifactId=my-api \
  -d packageName=com.example.myapi \
  -d javaVersion=21 \
  -d dependencies=web,data-jpa,postgresql,validation,testcontainers \
  -o starter.zip

结果：采用分层架构的项目，包含 controller/、service/、repository/、model/ 包、PostgreSQL Docker Compose 和 SpringDoc OpenAPI。

示例 2：采用 DDD 和多个存储的微服务

用户请求：“使用 DDD、PostgreSQL 和 Redis 搭建一个 Spring Boot 3 微服务”

curl -s https://start.spring.io/starter.zip \
  -d type=maven-project \
  -d bootVersion=3.4.5 \
  -d groupId=com.acme \
  -d artifactId=order-service \
  -d packageName=com.acme.order \
  -d javaVersion=21 \
  -d dependencies=web,data-jpa,postgresql,data-redis,validation,testcontainers \
  -o starter.zip

结果：采用 DDD 的项目，包含 domain/、application/、infrastructure/、presentation/ 包、PostgreSQL + Redis Docker Compose 和 SpringDoc OpenAPI。

最佳实践

• 始终使用 Spring Initializr 生成项目，以获得正确的依赖管理和父 POM。
• 使用 Java record 定义 DTO，它们不可变且简洁。
• 在 DDD 架构中保持领域层不依赖框架，不要在 domain/ 中使用 Spring 注解。
• 在生产环境中使用环境变量配置敏感信息（如数据库密码）。
• 在 docker-compose.yaml 中固定 Docker 镜像版本，避免意外的破坏性变更。
• 设置完成后运行 ./mvnw clean verify，确保所有内容均可编译且测试通过。
• 为集成测试添加 Testcontainers，而不是依赖 Docker Compose。

限制与警告

• Spring Initializr 需要访问互联网——此技能无法离线运行。
• Spring Boot 4.x 是否可用取决于当前发布周期——请访问 start.spring.io 查看最新版本。
• Docker Compose 凭据从 .env 文件（已加入 Git 忽略）加载——切勿将密钥提交到版本控制中。
• spring.jpa.hibernate.ddl-auto=update 设置仅用于开发环境——生产环境请使用 Flyway 或 Liquibase。
• ArchUnit 版本必须与 Spring Boot 捆绑的 JUnit 5 版本兼容。