文檔說明

本文面向零基礎后端開發(fā)者（尤其是前端需要了解后端，或者工作中本地聯(lián)調提高效率），記錄了從傳統(tǒng) JDK1.8 + MySQL 項目遷移至 JDK21 + PostgreSQL 的完整流程，包含PostgreSQL安裝、環(huán)境配置、問題排查、不同JDK環(huán)境的項目和maven配置，前后端聯(lián)調等核心步驟，全程基于實際項目實操，所有問題均為真實踩坑，解決方案可直接復用，最終實現(xiàn)項目成功啟動并完成前后端通信。

一、前期準備

1. 項目基礎：基于Spring Boot 3.3.0 + Druid + MyBatis + Vue 的后臺管理項目（若依改造版）

2. 目標環(huán)境：JDK21、PostgreSQL 16、Maven 3.9+、Redis 5.0+（復用原有配置，無需額外修改）

3. 工具準備：IDEA 2023+、pgAdmin 4（PostgreSQL可視化工具）、CMD命令行、瀏覽器

4. 注意：打開相關軟件或者執(zhí)行命令，盡量用管理員權限

二、核心環(huán)境切換說明

三、Step1：PostgreSQL 安裝步驟（Windows環(huán)境）

3.1 下載安裝包

1. 官網(wǎng)下載：PostgreSQL 官方下載地址  或者點擊這里直接下載

2. 選擇「Windows x86-64 Installer」（對應64位系統(tǒng)），下載完成后雙擊運行安裝包

3.2 分步安裝配置

1. 歡迎界面：點擊「Next」，同意許可協(xié)議后繼續(xù)「Next」

2. 安裝路徑：默認路徑C:\Program Files\PostgreSQL\16（可自定義，建議路徑無中文、無空格，本文示例D:\PostgreSQL）

3. 組件選擇：默認勾選「PostgreSQL Server」「pgAdmin 4」「Command Line Tools」，無需額外修改，「Next」

4. 數(shù)據(jù)存儲路徑：默認與安裝路徑關聯(lián)，「Next」

5. 超級用戶密碼：設置postgres用戶密碼（務必牢記，后續(xù)連接數(shù)據(jù)庫需使用，示例密碼123456）

6. 端口配置：默認5432（無需修改，若端口被占用可更換，后續(xù)項目配置需同步對應）

7. 區(qū)域設置：默認「Chinese (Simplified), China」，「Next」

8. 開始安裝：點擊「Install」，等待安裝完成（約5-10分鐘）

9. 完成界面：取消「Launch Stack Builder at exit」（無需額外安裝插件），點擊「Finish」

3.3 配置PostgreSQL 系統(tǒng)環(huán)境變量（關鍵，確保命令行可用）

補充：該步驟為命令行工具（psql、pg_dump等）正常使用的前提，缺失則CMD中執(zhí)行PostgreSQL命令會提示「不是內部或外部命令」

1. 右鍵「此電腦」→「屬性」→「高級系統(tǒng)設置」→「環(huán)境變量」

2. 系統(tǒng)變量→找到Path→「編輯」→「新建」

3. 添加PostgreSQL的bin目錄路徑：D:\PostgreSQL\bin（對應你的安裝路徑，核心目錄）

4. （可選）額外添加lib目錄（增強兼容性）：D:\PostgreSQL\lib

5. 驗證環(huán)境變量配置：關閉原有CMD窗口，重新打開CMD，輸入psql --version，若顯示以下信息即配置成功

   psql (PostgreSQL) 16.2
   

3.4 驗證安裝是否成功

1. 啟動PostgreSQL服務：右鍵「此電腦」→「管理」→「服務和應用程序」→「服務」，找到「postgresql-x64-16」，確認服務狀態(tài)為「正在運行」（若未運行，右鍵「啟動」）

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 環(huán)境配置與Maven配置

4.1 JDK21 配置（僅配置IDEA與項目，不配置系統(tǒng)環(huán)境變量）

說明：本次項目改造未配置JDK21系統(tǒng)環(huán)境變量，僅在IDEA內為項目單獨配置JDK21，避免影響電腦其他項目環(huán)境

1. 下載JDK21（已有的可跳過）：Oracle JDK21 下載地址（或OpenJDK，兼容性一致）

2. 解壓安裝：將下載的JDK21解壓至無中文、無空格路徑（示例D:\Java\jdk-21，妥善保存該路徑，后續(xù)IDEA配置需使用）

3. 無需配置系統(tǒng)環(huán)境變量（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. 配置系統(tǒng)環(huán)境變量：

   • 系統(tǒng)變量→「新建」，變量名MAVEN_HOME，變量值D:\Apache\maven-3.8.8

   • 系統(tǒng)變量→Path→「編輯」→「新建」，添加%MAVEN_HOME%\bin

4. 配置Maven鏡像與JDK版本（關鍵，適配JDK21）：

   • 打開Maven解壓目錄→conf→settings.xml

   • 配置國內鏡像（加速依賴下載），在<mirrors>標簽內添加

     <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（后續(xù)IDEA項目關聯(lián)后生效）即配置成功

4.3 IDEA 項目環(huán)境配置（核心，關聯(lián)JDK21與Maven）

1. 打開項目：IDEA→「Open」，選擇項目根目錄，等待項目加載

2. 配置項目JDK（僅當前項目生效，不影響系統(tǒng)）：

   • 步驟1：File→Project Structure→Project→SDK，點擊「New」，選擇解壓后的JDK21路徑（D:\Java\jdk-21）

   • 步驟2：SDK版本選擇「jdk-21」，Project language level選擇「21 (Preview)」（或「21」，根據(jù)IDEA版本適配）

   • 步驟3：點擊「Apply」→「OK」，完成項目全局JDK配置

3. 配置模塊JDK（確保所有子模塊統(tǒng)一）：

   • File→Project Structure→Modules，選擇所有項目子模塊（如ruoyi-admin、ruoyi-system，可以檢查一下都添加了沒有，一般上個步驟做了都會自動添加）

   • 右側「Dependencies」標簽，SDK選擇「jdk-21」，點擊「Apply」→「OK」

4. 配置IDEA默認Maven與JDK（確保后續(xù)新建項目兼容）：

   • 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執(zhí)行

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 數(shù)據(jù)庫腳本執(zhí)行（兩種方式）

5.1 方式1：pgAdmin 4 執(zhí)行（可視化操作，推薦零基礎）

1. 創(chuàng)建目標數(shù)據(jù)庫：

   • 打開pgAdmin 4，連接localhost服務器

   • 右鍵「Databases」→「Create」→「Database」

   • 填寫數(shù)據(jù)庫名稱「如：wms」，所有者選擇「postgres」，其他默認，點擊「Save」

2. 執(zhí)行SQL文件：

   • 右鍵「如：wms」數(shù)據(jù)庫→「Query Tool」

   • 點擊「Open File」，選擇項目中的SQL腳本（postgresql.sql）

   • 注意：刪除/注釋腳本中的\connect wms（該命令為psql專屬，pgAdmin不支持）

   • 點擊「執(zhí)行」（F5），等待腳本執(zhí)行完成（無紅色報錯，顯示「CREATE TABLE」「INSERT 0 1」即正常）

   • 重復上述步驟，執(zhí)行postgresql_view.sql腳本

3. 驗證執(zhí)行結果：刷新「wms」數(shù)據(jù)庫→展開「Tables」「Views」，可看到創(chuàng)建的表和視圖即執(zhí)行成功

5.2 方式2：psql 命令行執(zhí)行（適配原始腳本，無需修改）

1. 打開CMD，無需切換目錄（已配置系統(tǒng)環(huán)境變量，直接執(zhí)行命令）

2. 連接數(shù)據(jù)庫：輸入以下命令，回車后輸入postgres密碼

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

3. 執(zhí)行SQL腳本：輸入以下命令（替換為實際腳本路徑，正斜杠或雙反斜杠）

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

4. 退出psql：輸入\q，回車即可

5. 驗證執(zhí)行結果：通過pgAdmin 4查看數(shù)據(jù)庫表和視圖即確認

5.3 常見問題與解決方案

六、Step4：項目配置文件修改（適配PostgreSQL）

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

1. 修正數(shù)據(jù)庫連接URL（移除MySQL專屬參數(shù)）

   # 原有MySQL URL（刪除）
   # 如url: jdbc:mysql://192.155.1.1:3306/wms?useUnicode=true&characterEncoding=UTF-8&allowMultiQueries=true&serverTimezone=Asia/Beijing
   # 新PostgreSQL URL（本地連接，無額外參數(shù)）
   url: jdbc:postgresql://localhost:5432/wms

2. 修正數(shù)據(jù)庫驅動（已正確，無需修改，確認保留）

   driverClassName: org.postgresql.Driver

3. 修正數(shù)據(jù)庫用戶名和密碼（匹配本地PostgreSQL配置）

   username: postgres
   password: 123456 # 替換為你的postgres真實密碼

4. 補充缺失配置（解決占位符解析失?。?/p>

   druid:
       # 補充缺失的配置項，避免代碼注入報錯
       connectTimeout: 30000
       socketTimeout: 60000
       # 其他原有配置（initialSize、minIdle等）保留不變

6.2 其他配置文件修改

1. application.yml：分頁插件適配PostgreSQL

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

2. 啟動類配置（確認保留，排除默認數(shù)據(jù)源自動配置，根據(jù)自己的項目自行配置，可參考Ruoyi系統(tǒng)）

   @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無法自動創(chuàng)建多級目錄，D:\wms\logs\不存在

3. 解決方案（二選一）：

   • 快速解決：手動在D盤創(chuàng)建wms\logs\目錄

   • 長期優(yōu)化：修改logback.xml，為每個RollingFileAppender添加<createParentDirs>true</createParentDirs>，自動創(chuàng)建目錄

7.2 問題2：配置占位符解析失敗，數(shù)據(jù)源創(chuàng)建失敗

1. 報錯信息：Could not resolve placeholder 'spring.datasource.druid.connectTimeout'

2. 問題原因：配置文件中刪除了connectTimeout，但代碼中仍在注入該配置項

3. 解決方案（二選一）：

   • 快速解決：在application-druid.yml中補充connectTimeout: 30000 socketTimeout: 60000

   • 長期優(yōu)化：全局搜索代碼中的${spring.datasource.druid.connectTimeout}，移除對應的@Value注入注解

7.3 問題3：數(shù)據(jù)源創(chuàng)建失敗，連鎖引發(fā)Bean注入異常

1. 報錯信息：UnsatisfiedDependencyException: Error creating bean with name 'captchaController'

2. 問題原因：占位符解析失敗導致Druid數(shù)據(jù)源無法創(chuàng)建，進而引發(fā)MyBatis、Mapper、Controller等Bean注入失敗

3. 解決方案：先解決占位符解析問題，再驗證數(shù)據(jù)庫連接配置（密碼、端口、數(shù)據(jù)庫名是否正確），最后刷新Maven依賴重啟項目

7.4 項目啟動成功標志

1. 控制臺打印「啟動成功 WMS STARTED…」

2. 控制臺顯示「Tomcat started on port(s): 8080 (http)」

3. 無紅色報錯，進程保持運行（IDEA控制臺右上角無紅色停止按鈕）

4. D:\wms\logs\目錄下生成正常日志文件（sys-info.log等）

八、Step6：前后端聯(lián)調（實現(xiàn)前端正常訪問）

8.1 后端接口驗證（先驗證后端，再配置前端）

1. 訪問Swagger接口文檔：瀏覽器輸入http://localhost:8080/dev-api/swagger-ui/index.html

2. 驗證結果：能看到接口列表，無404錯誤即后端接口正常

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

1. 修改環(huán)境配置文件（.env.development）

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

2. 修改跨域代理配置（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': ''
           }
         }
       }
     }
   })

3. 修正請求頭配置（src/utils/request.js）

   // 確保請求頭與后端token配置一致
   config.headers['Authorization'] = token // 匹配后端token.header: Authorization

8.3 前端啟動與訪問

1. 前端根目錄執(zhí)行npm install（安裝依賴）

2. 執(zhí)行npm run dev（啟動前端項目）

3. 訪問地址：http://localhost:8081

4. 登錄驗證：輸入默認賬號admin、密碼123456，輸入數(shù)字計算驗證碼（后端captchaType: math），登錄成功即前后端聯(lián)調完成

九、總結與后續(xù)優(yōu)化

9.1 核心流程總結

1. 環(huán)境搭建：PostgreSQL安裝（含系統(tǒng)環(huán)境變量）→ JDK21解壓（僅IDEA項目配置）→ Maven配置→ IDEA項目關聯(lián)

2. 數(shù)據(jù)庫操作：創(chuàng)建數(shù)據(jù)庫→執(zhí)行SQL腳本（排除psql專屬命令）

3. 項目配置：修改數(shù)據(jù)源配置→解決占位符/日志目錄問題→啟動后端項目

4. 前后端聯(lián)調：配置前端代理→驗證接口訪問→完成登錄驗證

9.2 零基礎避坑指南

1. 密碼牢記：PostgreSQL的postgres密碼、項目數(shù)據(jù)庫密碼需保持一致

2. 配置一致：前后端的/dev-api路徑、Authorization請求頭需完全匹配

3. 端口不沖突：后端8080、前端8081，避免端口占用導致啟動失敗

4. 腳本無冗余：PostgreSQL腳本中需移除\開頭的psql專屬命令

5. 命令行可用：PostgreSQL必須配置系統(tǒng)環(huán)境變量，否則psql命令無法執(zhí)行

6. JDK隔離：僅在IDEA中配置項目JDK，可避免影響電腦其他舊項目（如JDK1.8項目）

7. 權限問題：權限不夠打開軟件，以及執(zhí)行命令盡量用管理員權限

9.3 后續(xù)優(yōu)化方向

1. 配置文件優(yōu)化：將數(shù)據(jù)庫密碼等敏感信息提取到配置中心，避免硬編碼

2. 日志優(yōu)化：配置Logback日志滾動策略，自動清理過期日志

3. 生產環(huán)境部署：使用Nginx轉發(fā)解決跨域，配置PostgreSQL主從復制提高可用性

4. 性能優(yōu)化：優(yōu)化Druid連接池配置，適配PostgreSQL的查詢優(yōu)化語法

附錄：常用命令與地址匯總

1. PostgreSQL psql 連接命令：psql -h localhost -p 5432 -U postgres -d shuttle_wms

2. PostgreSQL 執(zhí)行腳本命令：\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

總結

到此這篇關于零基礎后端入門之JDK21+PostgreSQL+Java項目實操指南的文章就介紹到這了,更多相關JDK21 + PostgreSQL+Java項目內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！

最新評論