SZHN Spring CLI

核心流程

按以下 4 步执行：

1. 检查环境

检查 Node.js：

node --version

• 未安装或版本 < 14 → 提示安装/升级
• 已安装 → 继续

强制更新 CLI：

npm update -g @szhn/spring-cli

如未安装：

npm config set registry https://npmmirror.digitalhainan.com.cn/
npm install -g @szhn/spring-cli

2. 执行命令

⚠️ 参数校验规则

必填参数：

• ✅ 项目名称：唯一必填项，必须用户提供

可选参数（有默认值）：

• -d 依赖列表：未提供则无依赖
• -D 数据库类型：默认 kingbase
• -t 模板：默认 default
• -o 输出目录：默认当前目录

当用户未提供项目名称时：

1. ❌ 严禁 AI 自动生成或猜测项目名称
2. ❌ 严禁直接执行 szhn-spring create 命令
3. ✅ 必须暂停执行，引导用户输入项目名称

询问模板：

❓ 请提供项目名称以创建项目。

您希望项目名称是什么？

基本命令：

szhn-spring create <project-name> [options]

常用参数：

参数	说明	示例
-d	依赖列表	-d redis,mybatis,security
-D	数据库类型	-D mysql (默认 kingbase)
-t	模板	-t default
-o	输出目录	-o ./projects

可用依赖： security, redis, mybatis, oss, license, es, sch-job, dubbo

详细参考： references/commands.md | references/dependencies.md

确认项目名称后，根据用户需求拼接命令并执行。

3. 代码检查

编译验证：

cd <project-name>
mvn clean compile

结果处理：

• ✅ BUILD SUCCESS → 进入步骤 4
• ❌ BUILD FAILURE → 自动修复后重试

自动修复策略：

• 依赖缺失 → mvn dependency:resolve + mvn clean install -U
• 代码错误 → 定位文件并修正
• 配置错误 → 检查 application.yml
• 版本问题 → 检查 Java 版本

每次修复后重新编译，最多尝试 3 次。

详细指南： references/structure.md

4. 后续指引

读取配置： 从 <project-name>-start/src/main/resources/application.yml 提取：

• server.port（默认 8080）
• server.servlet.context-path（默认空）

输出生成的指引：

✅ 项目编译验证通过！

📌 后续操作：

1️⃣ 启动项目（先 cd <project-name>）：
   • mvn spring-boot:run -pl <project-name>-start
   • 或在 IDE 中运行 Application 主类

2️⃣ 访问 Swagger（启动后）：
   • Knife4j：http://localhost:{port}/{context-path}doc.html
   
   💡 {配置提示}

配置提示示例：

• 默认：💡 使用默认端口 8080
• 自定义端口：💡 检测到自定义端口：{port}
• 两者都有：💡 检测到自定义配置：端口 {port}，上下文路径 {context-path}

详细配置解析： references/swagger-config.md

关键原则

• ✅ 环境检查时主动修复
• ✅ 编译失败时自动诊断修复
• ✅ 动态读取配置生成准确 URL
• ❌ 禁止自动启动服务或打开浏览器

常见问题

1. 本地启动时日志路径错误

问题描述： 在本地 macOS/Linux 环境启动时，出现日志路径错误导致启动失败：

ERROR in ch.qos.logback.core.rolling.RollingFileAppender - Failed to create parent directories for [/home/app/<project-name>/logs/digitalhainan/2026-05-13-info.0.log]
java.io.FileNotFoundException: /home/app/<project-name>/logs/digitalhainan/2026-05-13-info.0.log (No such file or directory)

原因： 默认配置的日志路径 /home/app/${spring.application.name}/logs 是服务器部署路径，本地开发环境不存在该路径。

解决方案： 通过 JVM 参数指定

mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Ddigitalhainan.logback.loghome=./logs/digitalhainan"

2. UserAutoConfiguration Bean 缺失

问题描述： 启动时出现 Bean 缺失错误：

Parameter 0 of method defaultUserManagerStrategyContext in cn.com.digitalhainan.user.conf.UserAutoConfiguration 
required a bean of type 'cn.com.digitalhainan.user.client.uaa.UaaUserApioneClient' that could not be found.

原因： Nacos 配置中心的 common-v3.yml 中包含了 user 模块的自动配置，但项目中没有配置 UAA 客户端（未添加 security 依赖）。

解决方案：

在启动类中排除 UserAutoConfiguration：

@SpringBootApplication(exclude = {
    cn.com.digitalhainan.user.conf.UserAutoConfiguration.class
})
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

注意事项：

• 如果项目需要使用用户认证功能，应添加 security 依赖：szhn-spring create my-project -d security,redis,mybatis
• 排除自动配置仅适用于不需要用户认证模块的简单项目

3. Nacos 配置中心连接失败

问题描述： 启动时无法连接到 Nacos 配置中心：

connect to server failed, serverIp=10.111.32.90, port=8998

解决方案：

• 检查 Nacos 服务器地址是否正确（配置在 application-local.yml 中）
• 确认网络是否可达 Nacos 服务器
• 如果只是本地开发，可以考虑暂时禁用 Nacos：

spring:
  cloud:
    nacos:
      config:
        enabled: false

4. 数据库连接失败

问题描述： 启动时数据库连接失败：

com.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failure

解决方案：

• 检查 Nacos 配置中心的数据库配置（poc-demo-local.yml）
• 确认数据库服务是否运行
• 检查数据库地址、端口、用户名、密码是否正确
• 本地开发可修改为本地数据库配置