CHARLIE SAYS

上一篇讲了为什么选 JHipster，这一篇动手：从零把环境搭好，生成第一个应用，跑起来登录进管理界面。JHipster 9.x 对环境的要求比以往更严格——Java 21 是底线、Node 22 是必须——先把这些对齐，能省掉后面 90% 的奇怪报错。

环境准备

JHipster 9.x 的版本基线：Spring Boot 4.0.x、Java 21 必须（Java 25 已支持，Java 17 已淘汰）、Node 22 必须、Maven 3.9 或 Gradle 9.4。逐项确认：

# Java 21+（Java 25 也可以）
java -version

# Node 22（JHipster 9 硬性要求，版本不符会在生成时直接报错）
node -v

# git 必须有，生成器依赖它做版本初始化
git --version

# Maven 3.9+（也可以只用项目自带的 mvnw wrapper，本机可不装）
mvn -v

三个都通过后，安装生成器：

npm install -g generator-jhipster
jhipster --version

建议给 Node 换上国内镜像（npm config set registry），否则安装生成器和后续前端依赖会很慢。Java 这边推荐用 SDKMAN 管理多版本，团队里统一 sdk install java 21，避免各装各的。

另外提前装好 Docker——不是必需项，但开发期的 Keycloak（第 8 篇）、生产数据库、Testcontainers（第 17 篇）都靠它，早晚要用。

交互式问答全解

进入空目录执行 jhipster，会依次问十几个问题。第一次跑会眼花，我们把每个问题按实际推荐讲一遍（括号内是我们团队的选择）：

mkdir demo && cd demo
jhipster

问题	选项	我们的选择与理由
应用类型	Monolithic / Microservice / Gateway	Monolithic（多数业务单体起步，第 5 篇详述）
应用名	自由输入	demo（会成为包名与目录名的一部分）
基础包名	默认 com.mycompany	保持默认或公司域名倒序
认证方式	JWT / OAuth 2.0 / OIDC / Session	JWT（内网系统零外部依赖；要接统一身份就选 OIDC，第 8 篇）
数据库	SQL（H2/MySQL/PostgreSQL…）/ NoSQL	SQL + PostgreSQL（dev 时自动用 H2 内存库，零配置）
缓存	Hazelcast / Redis / Memcached / No	单体选 Hazelcast（内置 HTTP session + Hibernate 二级缓存，第 10 篇）
测试框架	JHipster 元框架 / 换 Cucumber	默认（本质是 JUnit 5 + Testcontainers，第 17 篇）
前端框架	Angular / React / Vue	Angular（本系列主线；React 19 同样是一等公民）
其他	i18n、GraalVM 原生镜像等	按需

全部选完，生成器会跑上几分钟：下载依赖、生成几百个文件、执行 npm install、git init 并打初始 commit。结束后终端会打印启动说明。

我们的习惯是问答跑完后先检查 .yo-rc.json——它记录了你的全部选择，是应用的”基因”。把它提交进版本库，任何人拿到仓库都能用相同配置再生成。改主意了不用从头答一遍，直接编辑这个文件再跑 jhipster 即可。

用 JDL 一键生成

交互式问答适合第一次探索，日常更高效的方式是 JDL（JHipster Domain Language）。把应用配置与实体建模写在一个 .jdl 文件里，一条命令全部生成：

application {
  config {
    applicationType monolith
    baseName demo
    authenticationType jwt
    databaseType sql
    prodDatabaseType postgresql
    devDatabaseType h2disk
    cacheProvider hazelcast
    buildTool maven
    clientFramework angular
    testFrameworks []
  }
}

entity Customer {
  name String required minLength(2) maxLength(100)
  email String required pattern(/^[^@\s]+@[^@\s]+\.[^@\s]+$/)
  level CustomerLevel
}

enum CustomerLevel {
  BASIC, VIP, SVIP
}

relationship OneToMany {
  Customer{order} to Order{customer(email required)}
}

entity Order {
  orderNo String required unique
  amount BigDecimal required min(0)
  orderDate Instant required
}

paginate Customer, Order with pagination
dto Customer, Order with mapstruct
service Customer, Order with serviceClass

保存为 app.jdl，然后：

jhipster jdl app.jdl

一个带两个业务实体、完整前后端、Liquibase 迁移脚本、单元测试与集成测试的应用就生成了。JDL 语法本身第 6 篇深讲，这里先感受”建模即代码”的效率。JDL Studio（在线编辑器）可以实时预览 ER 图，团队评审领域模型时很好用。

启动应用

JHipster 是标准 Maven 项目，启动后端：

./mvnw

首次启动会下载大量依赖，之后很快。注意不需要显式 spring-boot:run，JHipster 配置的默认 goal 就是它。后端起来后，另开一个终端启动前端：

npm start

浏览器打开 http://localhost:9000。注意不是后端的 8080——开发期访问的是 Vite dev server，它会把 /api 请求代理到 8080（第 4 篇展开这套联调机制）。

默认账号

JWT 认证（dev 环境）下，Liquibase 初始化数据里内置了两个用户：

账号	密码	角色	用途
admin	admin	ROLE_ADMIN	管理菜单全开：用户/角色/权限、指标、配置、审计、日志
user	user	ROLE_USER	普通业务用户，验证权限隔离

登进去后先逛管理员菜单：User Management 里能看到完整的用户-权限体系（第 9 篇的主角），Administration 下有 metrics、health、configuration、audits 等运维页面——这些全部是生成的，一行没写。

目录结构导览

生成的项目长这样（只列主干）：

demo/
├── src/main/java/com/mycompany/demo/
│   ├── config/            # 配置类：Security、Cache、Database、Web、Async…
│   ├── domain/            # JPA 实体（+ enum）
│   ├── repository/        # Spring Data JPA Repository
│   ├── service/           # 业务服务（含 dto/、mapper/）
│   ├── web/rest/          # REST Controller（资源层）
│   └── security/          # 认证授权相关（JWT 时有 TokenProvider 等）
├── src/main/resources/
│   ├── config/liquibase/  # 数据库迁移（master.xml + changelog/）
│   ├── config/application-*.yml  # dev/prod 等 profile 配置
│   └── application.yml
├── src/main/webapp/       # Angular 前端（app/、i18n/ 等）
├── src/test/…             # 后端测试（含 Testcontainers 的 IT）
├── .jhipster/             # 每个实体的 .json 定义（增量更新的真源，进版本库）
├── .yo-rc.json            # 应用级生成配置
├── app.jdl                # 建模文件（建议保留并提交）
└── pom.xml

三个值得特别注意的文件：.yo-rc.json 决定”这个应用怎么生成”，.jhipster/*.json 决定”每个实体怎么生成”，config/liquibase/ 决定”数据库怎么演进”。理解了这三处，就理解了 JHipster 项目的骨架。后续几篇会依次深入。

常见安装问题速查

• Node 版本不符：nvm 切到 22，别硬试。
• npm install 卡死：换镜像源；Windows 下路径过长报错，把项目放进浅目录。
• 端口冲突：8080/9000 被占用，改 application-dev.yml 与 Vite 配置里的端口。
• H2 起不来：通常是之前异常退出留了锁文件，清掉 target/h2db 再启动。

小结

• 环境基线：Java 21+、Node 22、git，Maven 用 wrapper 即可；Docker 建议装上。
• 交互式 jhipster 适合探索，.yo-rc.json 记录全部答案可复用；日常用 jhipster jdl app.jdl 建模生成。
• ./mvnw + npm start 双终端启动，访问 9000 端口，默认账号 admin/admin、user/user。
• 目录结构是标准 Spring Boot 分层 + Angular 前端 + Liquibase 迁移，三处”真源”：.yo-rc.json、.jhipster/*.json、Liquibase changelog。

系列导航

• 上一篇：为什么选 JHipster——一次生成，十年维护
• 下一篇：技术栈全景图
• 延伸阅读：开发工作流——热重载与前后端联调 · JDL 从入门到驯服