SpringBoot-Microservice-Gen 一键生成 Spring Boot 微服务工程骨架（跨平台）

适用场景

当用户希望在当前工作空间中生成一个功能完备的 Spring Boot 后端骨架时使用本 Skill。生成工程包含：

• Spring CLI 安装/验证（spring 命令，来自 spring-attic/spring-cli）
• spring initializr new 生成 Maven + Web 基础项目
• RESTful CRUD：User 实体的完整增删改查接口（/api/users）+ 分页查询（/api/users/page）
• MyBatis-Plus + MySQL：数据访问层 + 分页插件配置
• Redis：Spring Cache 缓存（@Cacheable/@CacheEvict）+ JSON 序列化配置
• Nacos 配置中心：bootstrap.yml + @RefreshScope 动态刷新示例（配置使用 Nacos）
• Nacos 服务发现（Discovery）：/api/discovery/services 列出已注册服务与实例
• OpenFeign 远程调用：/api/feign/users 声明式调用下游服务，含降级工厂
• Actuator：健康检查 /actuator/health + 指标监控 /actuator/metrics
• 单元测试：JUnit 5 + Mockito（WebMvcTest + 纯单测），mvn test 运行
• Docker Compose 编排：MySQL（含初始化脚本）、Redis、Nacos、Prometheus、Grafana、ELK、SkyWalking 一键启动
• 监控栈：Prometheus 抓取 /actuator/prometheus、Grafana 预置数据源、ELK 日志采集（logstash profile）、SkyWalking 链路追踪
• 启动/停止脚本：跨平台 start.sh / start.cmd（start|stop|restart|status，自动打包 + 后台运行）
• 应用 Docker 化：多阶段 Dockerfile + docker-build.sh / docker-build.cmd（build|run|compose），docker-compose.yml 内置 app 服务一键构建容器化运行
• 统一响应封装 Result<T>、Lombok、参数校验

⚠️ 注意：本 Skill 使用的是 spring-attic/spring-cli（新版 Spring CLI），
与旧版 Spring Boot CLI（spring-boot-cli-*-bin.zip）是两个不同的项目。
新版 Spring CLI 使用 spring boot new / spring initializr new 命令，不再支持旧版的 spring init，
且运行 CLI 本身需要 JDK 17+。

Nacos 配置中心使用 Spring Cloud Alibaba spring-cloud-starter-alibaba-nacos-config
（Spring Boot 3.2+ 必须用此方案，旧版 nacos-config-spring-boot-starter 仅支持到 3.1.x）。

跨平台实现

核心脚本是 Python 实现，Windows / macOS / Linux 通用，无需 perl/envsubst/find/awk/unzip 等平台相关工具，仅需本机已安装：

• JDK 17+（Spring CLI 运行依赖）
• Python 3（运行本脚本；Windows 可用 python / py，macOS/Linux 通常自带）

脚本位置：

springboot-microservice-gen/scripts/springboot-microservice-gen.py

推荐做法：直接运行脚本

Windows（PowerShell / CMD）

python springboot-microservice-gen\scripts\springboot-microservice-gen.py

macOS / Linux

python3 springboot-microservice-gen/scripts/springboot-microservice-gen.py

指定项目目录名

python springboot-microservice-gen\scripts\springboot-microservice-gen.py my-app

脚本完成后会输出：

• 进入目录命令
• 启动命令（Windows: mvnw.cmd spring-boot:run；Unix: ./mvnw spring-boot:run）
• 示例接口地址（GET /api/users）

Maven 多环境配置（local / dev / test / prod 四环境切换）

工程通过 Maven profile + 资源过滤 实现四环境一键切换，同时支持本地调试与 Nacos 配置中心：

# ① 本地调试（默认，无需 Nacos；使用本地 MySQL/Redis）
mvnw.cmd clean package -Plocal
mvnw.cmd spring-boot:run            # 默认即 local

# ② 接入 Nacos 配置中心（dev / test / prod）
mvnw.cmd clean package -Pdev        # 或 -Ptest / -Pprod
mvnw.cmd spring-boot:run -Pdev

• pom.xml：定义 local(默认)/dev/test/prod 四个 profile，经 maven-resources-plugin 资源过滤把 @env@ 注入 application.yml 的 spring.profiles.active（定界符 @ 避免与 Spring ${...} 冲突）
• bootstrap.yml：走 bootstrap 直连 Nacos 配置中心，按活跃 profile 自动拉取环境独立配置（dataId=<服务名>-<env>.yaml）
• application.yml：公共配置（端口/日志/MyBatis-Plus/Actuator 等），不包含 datasource/redis（各环境不同，放 Nacos）
• application-local.yml：本地调试专用，配置 localhost 数据源/Redis，并禁用 Nacos 服务注册与配置拉取（完全脱离 Nacos）
• 各环境（dev/test/prod）的 datasource/redis 等配置，统一写在 Nacos 控制台的独立 dataId（<服务名>-dev.yaml / -test.yaml / -prod.yaml）
• ConfigController（@RefreshScope）演示 app.greeting 配置动态刷新

资源地址引用原则：不硬编码 IP。本地调试用 localhost（application-local.yml）；Docker 部署用 compose 服务名（mysql/redis/nacos）作为主机名，由 docker-compose 的 environment 注入覆盖（见下文）。

脚本做了什么（给 Agent 的操作指引）

1. 检查 JDK 17+（Spring CLI 运行依赖）
2. 检测 spring 是否可用；不可用时从 GitHub Release 下载 spring-cli-<version>.zip 并解压安装

- 下载地址：https://github.com/spring-attic/spring-cli/releases/download/v<version>/spring-cli-<version>.zip - 优先用 java -jar 方式调用 fat jar，避免 shell 脚本平台差异

1. 执行 spring initializr new --project maven-project --dependencies web ... 生成项目

- 若 CLI 不可用或执行失败，回退到直接调用 start.spring.io 下载项目压缩包

1. 修改 pom.xml（纯字符串替换，幂等）：

- properties：java.version / spring-cloud.version / spring-cloud-alibaba.version - dependencyManagement：Spring Cloud BOM + Spring Cloud Alibaba BOM - dependencies：MyBatis-Plus、MySQL、Redis、Validation、Actuator、Micrometer Prometheus、Logstash Logback Encoder、Nacos Config、Nacos Discovery、OpenFeign、LoadBalancer、Spring Cloud Bootstrap、Spring Boot Test、Lombok

1. 通过模板生成示例代码与配置：

- controller：UserController（CRUD + 分页）、ConfigController（Nacos 配置）、FeignController（OpenFeign）、DiscoveryController（服务发现） - service / service.impl：UserService + UserServiceImpl（@Cacheable/@CacheEvict Redis 缓存 + 分页） - entity：User（含 @NotBlank/@NotNull 校验） - mapper：UserMapper（BaseMapper） - feign：UserFeignClient + UserFeignClientFallbackFactory（OpenFeign 声明式调用与降级） - config：RedisConfig（JSON 序列化 + @EnableCaching） - common：Result 统一响应封装 - 根包：MybatisPlusConfig（分页插件）+ Application（@EnableDiscoveryClient / @EnableFeignClients） - src/test：UserControllerTest（WebMvcTest）+ UserServiceImplTest（Mockito） - resources：bootstrap.yml（Nacos 配置中心引导）+ application.yml（公共配置）+ application-local.yml（本地调试，localhost）+ logback-spring.xml（ELK 日志）+ README.md - 根目录：start.sh / start.cmd（启动停止）、Dockerfile + .dockerignore + docker-build.sh / docker-build.cmd（应用镜像构建） - deploy/：docker-compose.yml（应用 app，默认）+ docker-compose.middleware.yml（中间件 MySQL/Redis/Nacos）+ docker-compose.monitor.yml（监控 Prometheus/Grafana/ELK/SkyWalking）+ mysql/init.sql + Prometheus/Grafana/ELK 配置

生成后接口一览

Docker Compose 部署与监控

生成工程的 deploy/ 目录内置一键启动编排，应用 / 中间件 / 监控分为三个 compose 文件，可独立启停：

cd <projectName>/deploy
docker compose up -d                                     # 应用 app（默认 docker-compose.yml）
docker compose -f docker-compose.middleware.yml up -d    # 中间件：MySQL/Redis/Nacos
docker compose -f docker-compose.monitor.yml up -d       # 监控：Prometheus/Grafana/ELK/SkyWalking

• MySQL：mysql/init.sql 首次启动自动建库建表 + 示例数据
• Redis：本地 6379，AOF 持久化
• Nacos：本地 8848，配置中心 + 注册中心
• Prometheus：抓取应用 /actuator/prometheus
• Grafana：localhost:3000（admin/admin），预置 Prometheus 数据源
• ELK：Elasticsearch + Logstash + Kibana；应用启用 logstash profile 后日志 JSON 入 ES
• SkyWalking：OAP + UI（localhost:80，默认端口已从 8080 改为 80）。应用镜像内置 SkyWalking Java Agent（-javaagent），无侵入链路追踪，上报到 skywalking-oap:11800；服务名/上报地址由环境变量 SWAGENTNAME / SWAGENTCOLLECTORBACKENDSERVICES 配置

三个 compose 位于同一 deploy/ 目录，默认 project 同名，共享同一个 <project>_default 网络，因此 app 可直接用服务名访问 mysql/redis/nacos。启动顺序建议：先中间件，再应用。

可选环境变量

• SPRINGCLIVERSION：默认 0.9.0（对应 spring-attic/spring-cli 的 Release 版本）
• SPRINGCLIINSTALL_DIR：默认 ~/.cache/springboot-microservice-gen
• SPRINGCLIZIP：指定本地下载的 spring-cli-<version>.zip 路径（网络受限时使用）
• SPRINGBOOTVERSION：生成工程使用的 Spring Boot 版本，留空则使用 start.spring.io 官方默认
• SPRINGCLOUDVERSION：默认 2023.0.1（兼容 Spring Boot 3.2/3.3）
• SPRINGCLOUDALIBABA_VERSION：默认 2023.0.1.3（Nacos 配置中心 + 服务发现）

若生成的 Spring Boot 版本变化，请同步调整 SPRINGCLOUDVERSION / SPRINGCLOUDALIBABA_VERSION。

资源地址与环境变量（不硬编码 IP）

工程不在配置里写死 IP，中间件地址通过环境变量注入，可在不同部署形态间切换：

• 本地调试：application-local.yml 用 localhost（MySQL/Redis 起在宿主机即可）。
• Docker 部署：deploy/docker-compose.yml 用 compose 服务名（mysql/redis/nacos）作为主机名注入 environment，同一 <project>_default 网络内 DNS 解析，无需 IP。
• dev/test/prod：datasource/redis 等写在 Nacos 各环境 dataId 中。

代码生成器（MyBatis-Plus Generator，按表生成 CRUD）

工程内置 MyBatis-Plus 官方代码生成器，可从数据库表一键生成 entity / mapper / service / serviceImpl / controller（含分页），模板可自定义。

• 初始化工具放 src/test/java/.../generator/CodeGenerator.java（test scope 依赖，不打入运行时 jar）
• Freemarker 模板位于 src/main/resources/templates/generator/*.ftl，对齐本项目分层风格（Result<T>、service 接口+impl、/page 分页、Lombok、@Mapper）

使用步骤：

1. 修改 CodeGenerator 里的 URL/USERNAME/PASSWORD 与 TABLES 表名；
2. 运行 main（IDE 直接运行，或 mvn test-compile exec:java -Dexec.mainClass=<...>.generator.CodeGenerator）；
3. Java 代码生成到 src/main/java，XML 生成到 src/main/resources/mapper。

示例对话触发词

• “帮我安装 Spring CLI 并用 spring initializr 生成项目”
• “在当前目录生成一个带 CRUD、Redis、MySQL、Nacos、健康检查的 Spring Boot 工程”
• “像脚手架一样生成 springboot 项目，带 RESTful CRUD、分页、Redis 缓存、Nacos 配置与发现、OpenFeign 调用、单元测试”