零基础后端入门：JDK21 + PostgreSQL+Java项目

文档说明

本文面向零基础后端开发者（尤其是前端需要了解后端，或者工作中本地联调提高效率），记录了从传统 JDK1.8 + MySQL 项目迁移至 JDK21 + PostgreSQL 的完整流程，包含PostgreSQL安装、环境配置、问题排查、不同JDK环境的项目和maven配置，前后端联调等核心步骤，全程基于实际项目实操，所有问题均为真实踩坑，解决方案可直接复用，最终实现项目成功启动并完成前后端通信。

一、前期准备

1. 项目基础：基于Spring Boot 3.3.0 + Druid + MyBatis + Vue 的后台管理项目（若依改造版）
2. 目标环境：JDK21、PostgreSQL 16、Maven 3.9+、Redis 5.0+（复用原有配置，无需额外修改）
3. 工具准备：IDEA 2023+、pgAdmin 4（PostgreSQL可视化工具）、CMD命令行、浏览器
4. 注意：打开相关软件或者执行命令，尽量用管理员权限

二、核心环境切换说明

三、Step1：PostgreSQL 安装步骤（Windows环境）

3.1 下载安装包

1. 官网下载：PostgreSQL 官方下载地址
2. 选择「Windows x86-64 Installer」（对应64位系统），下载完成后双击运行安装包

3.2 分步安装配置

1. 欢迎界面：点击「Next」，同意许可协议后继续「Next」
2. 安装路径：默认路径C:\Program Files\PostgreSQL\16（可自定义，建议路径无中文、无空格，本文示例D:\PostgreSQL）
3. 组件选择：默认勾选「PostgreSQL Server」「pgAdmin 4」「Command Line Tools」，无需额外修改，「Next」
4. 数据存储路径：默认与安装路径关联，「Next」
5. 超级用户密码：设置postgres用户密码（务必牢记，后续连接数据库需使用，示例密码123456）
6. 端口配置：默认5432（无需修改，若端口被占用可更换，后续项目配置需同步对应）
7. 区域设置：默认「Chinese (Simplified), China」，「Next」
8. 开始安装：点击「Install」，等待安装完成（约5-10分钟）
9. 完成界面：取消「Launch Stack Builder at exit」（无需额外安装插件），点击「Finish」

3.3 配置PostgreSQL 系统环境变量（关键，确保命令行可用）

补充：该步骤为命令行工具（psql、pg_dump等）正常使用的前提，缺失则CMD中执行PostgreSQL命令会提示「不是内部或外部命令」

1. 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
2. 系统变量→找到Path→「编辑」→「新建」
3. 添加PostgreSQL的bin目录路径：D:\PostgreSQL\bin（对应你的安装路径，核心目录）
4. （可选）额外添加lib目录（增强兼容性）：D:\PostgreSQL\lib

验证环境变量配置：关闭原有CMD窗口，重新打开CMD，输入psql --version，若显示以下信息即配置成功

 psql (PostgreSQL) 16.2 

3.4 验证安装是否成功

1. 启动PostgreSQL服务：右键「此电脑」→「管理」→「服务和应用程序」→「服务」，找到「postgresql-x64-16」，确认服务状态为「正在运行」（若未运行，右键「启动」）
2. 打开pgAdmin 4：桌面双击「pgAdmin 4」，首次启动需设置pgAdmin登录密码，登录后可看到默认服务器「localhost:5432」
3. 连接默认服务器：右键「localhost:5432」→「Connect Server」，输入步骤3.2中设置的postgres用户密码，连接成功即说明安装完成
4. 命令行验证（可选）：CMD输入psql -h localhost -p 5432 -U postgres，输入密码后进入psql交互界面（显示postgres=#），即命令行工具可用

四、Step2：JDK21 环境配置与Maven配置

4.1 JDK21 配置（仅配置IDEA与项目，不配置系统环境变量）

说明：本次项目改造未配置JDK21系统环境变量，仅在IDEA内为项目单独配置JDK21，避免影响电脑其他项目环境

1. 下载JDK21（已有的可跳过）：Oracle JDK21 下载地址（或OpenJDK，兼容性一致）
2. 解压安装：将下载的JDK21解压至无中文、无空格路径（示例D:\Java\jdk-21，妥善保存该路径，后续IDEA配置需使用）
3. 无需配置系统环境变量（JAVA_HOME、Path均无需新增/修改），直接进入IDEA项目配置步骤

4.2 Maven 配置（适配JDK21）

1. 下载Maven （已有的可跳过）：Maven 官方下载地址，选择「apache-maven-3.8.8-bin.zip」（或更高版本）
2. 解压安装：解压至无中文、无空格路径（示例D:\Apache\maven-3.8.8）
3. 配置系统环境变量：
   • 系统变量→「新建」，变量名MAVEN_HOME，变量值D:\Apache\maven-3.8.8
   • 系统变量→Path→「编辑」→「新建」，添加%MAVEN_HOME%\bin
4. 配置Maven镜像与JDK版本（关键，适配JDK21）：
   • 打开Maven解压目录→conf→settings.xml
5. 验证Maven配置：打开CMD，输入mvn -v，若显示Maven版本与对应JDK（后续IDEA项目关联后生效）即配置成功

配置国内镜像（加速依赖下载），在<mirrors>标签内添加

 <mirror> <id>aliyunmaven</id> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/public</url> <mirrorOf>central</mirrorOf> </mirror> 

4.3 IDEA 项目环境配置（核心，关联JDK21与Maven）

1. 打开项目：IDEA→「Open」，选择项目根目录，等待项目加载
2. 配置项目JDK（仅当前项目生效，不影响系统）：
   • 步骤1：File→Project Structure→Project→SDK，点击「New」，选择解压后的JDK21路径（D:\Java\jdk-21）
   • 步骤2：SDK版本选择「jdk-21」，Project language level选择「21 (Preview)」（或「21」，根据IDEA版本适配）
   • 步骤3：点击「Apply」→「OK」，完成项目全局JDK配置
3. 配置模块JDK（确保所有子模块统一）：
   • File→Project Structure→Modules，选择所有项目子模块（如ruoyi-admin、ruoyi-system，可以检查一下都添加了没有，一般上个步骤做了都会自动添加）
   • 右侧「Dependencies」标签，SDK选择「jdk-21」，点击「Apply」→「OK」
4. 配置IDEA默认Maven与JDK（确保后续新建项目兼容）：
   • File→Settings→Build, Execution, Deployment→Build Tools→Maven
   • 配置Maven home directory（D:\Apache\maven-3.8.8）、User settings file（D:\Apache\maven-3.8.8\conf\settings.xml）
   • （可选）配置Runner→JRE，选择「jdk-21」，确保Maven命令使用JDK21执行
5. 修改根目录下边的pom.xml文件（maven-compiler-plugin配置）：找见代码中的build标签，里边添加如下代码：

<plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.11.0</version><configuration><parameters>true</parameters><!-- 复用properties中定义的java.version，无需硬编码21，更易维护 --><source>${java.version}</source><target>${java.version}</target><encoding>${project.build.sourceEncoding}</encoding><executable>C:\Program Files\Java\jdk-21.0.9\bin\javac.exe</executable></configuration></plugin></plugins>

6. 刷新Maven依赖：右键项目→Maven→Reload Project，等待依赖下载完成（无红色报错即正常）
7. 验证项目JDK配置：打开项目启动类RuoyiApplication.java，查看顶部import语句无红色报错，右键能正常显示「Run」选项，即配置成功

五、Step3：PostgreSQL 数据库脚本执行（两种方式）

5.1 方式1：pgAdmin 4 执行（可视化操作，推荐零基础）

1. 创建目标数据库：
   • 打开pgAdmin 4，连接localhost服务器
   • 右键「Databases」→「Create」→「Database」
   • 填写数据库名称「如：wms」，所有者选择「postgres」，其他默认，点击「Save」
2. 执行SQL文件：
   • 右键「如：wms」数据库→「Query Tool」
   • 点击「Open File」，选择项目中的SQL脚本（postgresql.sql）
   • 注意：删除/注释脚本中的\connect wms（该命令为psql专属，pgAdmin不支持）
   • 点击「执行」（F5），等待脚本执行完成（无红色报错，显示「CREATE TABLE」「INSERT 0 1」即正常）
   • 重复上述步骤，执行postgresql_view.sql脚本
3. 验证执行结果：刷新「wms」数据库→展开「Tables」「Views」，可看到创建的表和视图即执行成功

5.2 方式2：psql 命令行执行（适配原始脚本，无需修改）

1. 打开CMD，无需切换目录（已配置系统环境变量，直接执行命令）
2. 退出psql：输入\q，回车即可
3. 验证执行结果：通过pgAdmin 4查看数据库表和视图即确认

执行SQL脚本：输入以下命令（替换为实际脚本路径，正斜杠或双反斜杠）

 \i D:/project/wms/sql/postgresql.sql; \i D:/project/wms/sql/postgresql_view.sql; 

连接数据库：输入以下命令，回车后输入postgres密码

 psql -h localhost -p 5432 -U postgres -d wms 

5.3 常见问题与解决方案

六、Step4：项目配置文件修改（适配PostgreSQL）

6.1 核心配置文件：application-druid.yml

补充缺失配置（解决占位符解析失败）

 druid: # 补充缺失的配置项，避免代码注入报错 connectTimeout: 30000 socketTimeout: 60000 # 其他原有配置（initialSize、minIdle等）保留不变 

修正数据库用户名和密码（匹配本地PostgreSQL配置）

 username: postgres password: 123456 # 替换为你的postgres真实密码 

修正数据库驱动（已正确，无需修改，确认保留）

 driverClassName: org.postgresql.Driver 

修正数据库连接URL（移除MySQL专属参数）

 # 原有MySQL URL（删除） # 如url: jdbc:mysql://192.155.1.1:3306/wms?useUnicode=true&characterEncoding=UTF-8&allowMultiQueries=true&serverTimezone=Asia/Beijing # 新PostgreSQL URL（本地连接，无额外参数） url: jdbc:postgresql://localhost:5432/wms 

6.2 其他配置文件修改

启动类配置（确认保留，排除默认数据源自动配置，根据自己的项目自行配置，可参考Ruoyi系统）

 @SpringBootApplication(exclude = {DataSourceAutoConfiguration.class}) @EnableAsync @MapperScan("com.ruoyi.**.mapper") // 补充Mapper扫描，避免注入失败 public class RuoyiApplication { public static void main(String[] args) { SpringApplication.run(RuoyiApplication.class, args); System.out.println("启动成功 WMS STARTED..."); } } 

application.yml：分页插件适配PostgreSQL

 pagehelper: helperDialect: postgresql # 原有为mysql，修改为postgresql reasonable: true supportMethodsArguments: true params: count=countSql 

七、Step5：项目启动问题排查与解决（核心踩坑记录）

7.1 问题1：Logback 日志目录不存在，启动失败

1. 报错信息：Failed to create parent directories for [D:\wms\logs\sys-info.log]
2. 问题原因：Logback无法自动创建多级目录，D:\wms\logs\不存在
3. 解决方案（二选一）：
   • 快速解决：手动在D盘创建wms\logs\目录
   • 长期优化：修改logback.xml，为每个RollingFileAppender添加<createParentDirs>true</createParentDirs>，自动创建目录

7.2 问题2：配置占位符解析失败，数据源创建失败

1. 报错信息：Could not resolve placeholder 'spring.datasource.druid.connectTimeout'
2. 问题原因：配置文件中删除了connectTimeout，但代码中仍在注入该配置项
3. 解决方案（二选一）：
   • 快速解决：在application-druid.yml中补充connectTimeout: 30000socketTimeout: 60000
   • 长期优化：全局搜索代码中的${spring.datasource.druid.connectTimeout}，移除对应的@Value注入注解

7.3 问题3：数据源创建失败，连锁引发Bean注入异常

1. 报错信息：UnsatisfiedDependencyException: Error creating bean with name 'captchaController'
2. 问题原因：占位符解析失败导致Druid数据源无法创建，进而引发MyBatis、Mapper、Controller等Bean注入失败
3. 解决方案：先解决占位符解析问题，再验证数据库连接配置（密码、端口、数据库名是否正确），最后刷新Maven依赖重启项目

7.4 项目启动成功标志

1. 控制台打印「启动成功 WMS STARTED…」
2. 控制台显示「Tomcat started on port(s): 8080 (http)」
3. 无红色报错，进程保持运行（IDEA控制台右上角无红色停止按钮）
4. D:\wms\logs\目录下生成正常日志文件（sys-info.log等）

八、Step6：前后端联调（实现前端正常访问）

8.1 后端接口验证（先验证后端，再配置前端）

1. 访问Swagger接口文档：浏览器输入http://localhost:8080/dev-api/swagger-ui/index.html
2. 验证结果：能看到接口列表，无404错误即后端接口正常

8.2 前端配置修改（适配后端地址）

修正请求头配置（src/utils/request.js）

 // 确保请求头与后端token配置一致 config.headers['Authorization'] = token // 匹配后端token.header: Authorization 

修改跨域代理配置（vue.config.js）

 const { defineConfig } = require('@vue/cli-service') module.exports = defineConfig({ transpileDependencies: true, devServer: { port: 8081, // 避免与后端8080端口冲突 open: true, proxy: { '/dev-api': { target: 'http://localhost:8080', changeOrigin: true, pathRewrite: { '^/dev-api': '' } } } } }) 

修改环境配置文件（.env.development）

 NODE_ENV = 'development' VUE_APP_BASE_API = '/dev-api' VUE_APP_SERVER_URL = 'http://localhost:8080' 

8.3 前端启动与访问

1. 前端根目录执行npm install（安装依赖）
2. 执行npm run dev（启动前端项目）
3. 访问地址：http://localhost:8081
4. 登录验证：输入默认账号admin、密码123456，输入数字计算验证码（后端captchaType: math），登录成功即前后端联调完成

九、总结与后续优化

9.1 核心流程总结

1. 环境搭建：PostgreSQL安装（含系统环境变量）→ JDK21解压（仅IDEA项目配置）→ Maven配置→ IDEA项目关联
2. 数据库操作：创建数据库→执行SQL脚本（排除psql专属命令）
3. 项目配置：修改数据源配置→解决占位符/日志目录问题→启动后端项目
4. 前后端联调：配置前端代理→验证接口访问→完成登录验证

9.2 零基础避坑指南

1. 密码牢记：PostgreSQL的postgres密码、项目数据库密码需保持一致
2. 配置一致：前后端的/dev-api路径、Authorization请求头需完全匹配
3. 端口不冲突：后端8080、前端8081，避免端口占用导致启动失败
4. 脚本无冗余：PostgreSQL脚本中需移除\开头的psql专属命令
5. 命令行可用：PostgreSQL必须配置系统环境变量，否则psql命令无法执行
6. JDK隔离：仅在IDEA中配置项目JDK，可避免影响电脑其他旧项目（如JDK1.8项目）
7. 权限问题：权限不够打开软件，以及执行命令尽量用管理员权限

9.3 后续优化方向

1. 配置文件优化：将数据库密码等敏感信息提取到配置中心，避免硬编码
2. 日志优化：配置Logback日志滚动策略，自动清理过期日志
3. 生产环境部署：使用Nginx转发解决跨域，配置PostgreSQL主从复制提高可用性
4. 性能优化：优化Druid连接池配置，适配PostgreSQL的查询优化语法

附录：常用命令与地址汇总

1. PostgreSQL psql 连接命令：psql -h localhost -p 5432 -U postgres -d shuttle_wms
2. PostgreSQL 执行脚本命令：\i D:/project/wms/sql/postgresql.sql;
3. PostgreSQL 版本验证命令：psql --version
4. 后端基础地址：http://localhost:8080
5. Swagger文档地址：http://localhost:8080/dev-api/swagger-ui/index.html
6. 前端访问地址：http://localhost:8081
7. 日志存储目录：D:\wms\logs
8. 文件上传目录：D:\wms\uploadPath