Java 開發避坑指南：從零開始記錄的實戰經驗與工具鏈技巧

前言

Java 知識點碎雜、工具鏈豐富，初學者極易踩坑。本文記錄從零開始的實戰避坑經驗，聚焦「網上難搜、官方文檔不明說」的邊角知識。

坑一：java 命令執行類的包路徑陷阱

錯誤現象

> cd com/example
> java Main.class
錯誤: 找不到或無法加載主類 Main.class

根因

• java 後跟的是全限定類名 (包名+類名)，而非檔案路徑。
• 類文件必須位於與包結構對應的目錄樹下。

正確姿勢

# 專案根目錄下
> javac com/example/Main.java
> java com.example.Main  # 無 .class 後綴，用點分隔包名

原理

Class 文件內部儲存著包名 (如 package com.example;)，JVM 類加載器按包名轉路徑 (com/example/Main.class) 尋找文件。若當前目錄不在 classpath 根，需 java -cp . com.example.Main。

坑二：IDE 版本滯後於類庫導致誤判相容性問題

典型場景

• 升級 Spring Boot 3.2 / JDK 21，IntelliJ IDEA 仍停留在 2022.x。
• 報紅：Record patterns、Virtual Threads、String Templates 語法錯誤。
• Maven 編譯卻通過 (編譯器版本正確)。

鐵律

IDE 必須同步升級到支援目標 JDK/框架版本的最新穩定版。

• IntelliJ IDEA：Help → Check for Updates，或下載最新 EAP/正式版。
• Eclipse：安裝最新 Java Development Tools、Maven Integration。
• VS Code：更新 Extension Pack for Java、Language Support for Java。

副作用

將 IDE 支援問題誤判為「類庫不相容」、「JDK Bug」、「語法錯誤」，浪費大量排查時間。

坑三：Maven 依賴傳遞衝突與版本鎖定

現象

專案引入 A、B 兩個 Starter，間接依賴同一庫 (如 Netty) 不同版本，運行時 NoSuchMethodError、ClassNotFoundException。

解決

1. mvn dependency:tree -Dverbose 定位衝突路徑。
2. 在 <dependencyManagement> 統一鎖定版本：

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-all</artifactId>
      <version>4.1.100.Final</version> <!-- 強制統一 -->
    </dependency>
  </dependencies>
</dependencyManagement>

3. 或用 <exclusion> 排除傳遞依賴。

坑四：編碼地雷 — 來源文件、控制台、資料庫、JVM 三處不一

檢查清單

坑五：日誌門面與實現雙重綁定 (SLF4J + Logback + Log4j2)

現象

SLF4J: Class path contains multiple SLF4J bindings.
SLF4J: Found binding in [jar:logback-classic-1.2.3.jar!/org/slf4j/impl/StaticLoggerBinder.class]
SLF4J: Found binding in [jar:log4j-slf4j-impl-2.17.1.jar!/org/slf4j/impl/StaticLoggerBinder.class]

解決

• 排除傳遞依賴中的綁定：<exclusion><groupId>org.apache.logging.log4j</groupId><artifactId>log4j-slf4j-impl</artifactId></exclusion>。
• 統一門面：SLF4J API + Logback 實現 (Spring Boot 預設) 或 SLF4J API + Log4j2 實現，二選一。

坑六：測試依賴污染主代碼 (JUnit / Mockito / AssertJ)

現象

主代碼誤用 org.junit.jupiter.api.Test 註解，打包部署到生產環境帶入測試框架 Jar。

規範

• 測試依賴 必須 <scope>test</scope>。
• Maven 編譯插件配置 <compilerArgs><arg>-Xlint:unchecked</arg></compilerArgs> 可預警。

持續更新中…

Java 坑深似海，歡迎在評論區補充你的避坑經驗，共建「Java 開發避坑知識庫」。