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

晨旭缘2026-01-13 11:20

文档说明

本文面向零基础后端开发者（尤其是前端需要了解后端，或者工作中本地联调提高效率），记录了从传统 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. 注意：打开相关软件或者执行命令，尽量用管理员权限

二、核心环境切换说明

环境/组件 原有配置 新配置 切换说明
JDK版本 1.8 21 Spring Boot 3.x 推荐JDK17+，JDK21为长期支持版，兼容性更好
数据库 MySQL 8.0 PostgreSQL 16 替换数据库驱动、修改连接配置、适配SQL语法差异
数据库驱动 com.mysql.cj.jdbc.Driver org.postgresql.Driver 移除MySQL专属依赖，引入PostgreSQL驱动
分页插件 helperDialect: mysql helperDialect: postgresql 适配PostgreSQL分页语法
SQL语法 支持use 数据库、@字段转义 支持SELECT version()、""字段转义 移除MySQL专属SQL参数，兼容PostgreSQL语法

三、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

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

    Plain 复制代码 
    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

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

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

  5. 验证Maven配置：打开CMD，输入mvn -v，若显示Maven版本与对应JDK（后续IDEA项目关联后生效）即配置成功

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标签，里边添加如下代码：

xml 复制代码 
  <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>
  1. 刷新Maven依赖：右键项目→Maven→Reload Project，等待依赖下载完成（无红色报错即正常）
  2. 验证项目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. 连接数据库：输入以下命令，回车后输入postgres密码

    Bash 复制代码 
    psql -h localhost -p 5432 -U postgres -d wms

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

    SQL 复制代码 
    \i D:/project/wms/sql/postgresql.sql;
\i D:/project/wms/sql/postgresql_view.sql;

  4. 退出psql：输入\q，回车即可

  5. 验证执行结果：通过pgAdmin 4查看数据库表和视图即确认

5.3 常见问题与解决方案

问题现象 报错信息 解决方案
执行脚本报错 ERROR: syntax error at or near "" 删除/注释脚本中的\connect等psql专属元命令
无法连接数据库 FATAL: password authentication failed 确认postgres密码输入正确，数据库服务已启动
脚本执行无反应 无任何提示 确认当前连接的数据库为「wms」，脚本路径正确
CMD执行psql命令无效 'psql' 不是内部或外部命令 重新配置PostgreSQL环境变量，关闭原有CMD窗口重新打开验证

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

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

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

    YAML 复制代码 
    # 原有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

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

    YAML 复制代码 
    driverClassName: org.postgresql.Driver

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

    YAML 复制代码 
    username: postgres
password: 123456 # 替换为你的postgres真实密码

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

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

6.2 其他配置文件修改

  1. application.yml：分页插件适配PostgreSQL

    YAML 复制代码 
    pagehelper:
  helperDialect: postgresql # 原有为mysql，修改为postgresql
  reasonable: true
  supportMethodsArguments: true
  params: count=countSql

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

    Java 复制代码 
    @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...");
    }
}

七、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: 30000 socketTimeout: 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 前端配置修改（适配后端地址）

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

    Plain 复制代码 
    NODE_ENV = 'development'
VUE_APP_BASE_API = '/dev-api'
VUE_APP_SERVER_URL = 'http://localhost:8080'

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

    JavaScript 复制代码 
    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': ''
        }
      }
    }
  }
})

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

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

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

相关推荐
萧曵 丶2 小时前
MySQL InnoDB 实现 MVCC 原理
数据库·mysql·mvcc
BullSmall2 小时前
SpringBoot 项目日志规范（企业级标准 + 最佳实践）
java·spring boot·spring
better_liang2 小时前
每日Java面试场景题知识点之-线程池
java·线程池·并发编程·juc·企业级开发
一直都在5722 小时前
SpringBoot：自动配置原理
java·spring boot·spring
ss2732 小时前
ruoyi 新增每页分页条数
java·数据库·mybatis
benpaodeDD2 小时前
黑马SpringBoot2自动配置原理
java·spring boot·后端
编程大师哥2 小时前
Java web
java·开发语言·前端
万粉变现经纪人2 小时前
如何解决 pip install mysqlclient 报错 ‘mysql_config’ not found 问题
数据库·python·mysql·pycharm·bug·pandas·pip
电商API_180079052472 小时前
大麦网API实战指南：关键字搜索与详情数据获取全解析
java·大数据·前端·人工智能·spring·网络爬虫
热门推荐
01GitHub 镜像站点02Labelme从安装到标注：零基础完整指南03网站改了域名，如何查找？04Linux下V2Ray安装配置指南05安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）06【踩坑笔记】50系显卡适配的 PyTorch 安装072025-04-03 Latex学习1——本地配置Latex + VScode环境08Claude Code 2.1.2 升级报错？别折腾了，一行命令搞定09CentOS的ISO镜像下载10KGG转MP3工具|非KGM文件|解密音频