Java 連線 Oracle 資料庫完整指南：JDBC 驅動安裝、Classpath 設定、IDE 專案整合、常見錯誤排解

Java 開發者初次連線 Oracle 常遇到 ClassNotFoundException: oracle.jdbc.driver.OracleDriver 或 No suitable driver found。本文從驅動下載、Classpath 設定、Eclipse/IntelliJ/Maven/Gradle 專案整合、連線字串、連線池、模組化 (JPMS) 相容性，提供完整可複製貼上的解決方案。

1. 取得正確 JDBC 驅動

• 檔案名：ojdbc8.jar (JDK 8/11/17/21 通用)、ojdbc11.jar (JDK 11+ 專用、支援新特性)
• 來源：Oracle 官網 JDBC 下載頁 或 Maven Central (com.oracle.database.jdbc:ojdbc8 / ojdbc11)。
• 版本對應：驅動版本 ≥ 資料庫版本（如 19c 資料庫用 19.x/21.x 驅動）。

2. Classpath 設定三種方式

方式 A：Maven/Gradle 專案（推薦）

<!-- Maven pom.xml -->
<dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc11</artifactId>
    <version>23.4.0.0</version>
</dependency>

// Gradle build.gradle
implementation 'com.oracle.database.jdbc:ojdbc11:23.4.0.0'

注意：Oracle JDBC 驅動在 Maven Central 發布需接受 OTN License，首次建置會提示互動確認，CI/CD 需設定 oracle.license.accept=true 系統屬性或使用 Oracle Maven Plugin。

方式 B：IDE 手動匯入（非建構工具專案）

• Eclipse：專案右鍵 → Build Path → Configure Build Path → Libraries → Classpath → Add External JARs → 選擇 ojdbc8.jar。
• IntelliJ IDEA：File → Project Structure → Modules → Dependencies → + → JARs or directories → 選擇 ojdbc8.jar → Scope: Compile。
• VS Code (Java Extension Pack)：.classpath 或 settings.json 的 java.project.referencedLibraries 加入 lib/ojdbc8.jar。

方式 C：系統環境變數 CLASSPATH（不推薦生產）

# Windows CMD
set CLASSPATH=.;C:\oracle\jdbc\lib\ojdbc8.jar;%CLASSPATH%

# Linux/Bash
export CLASSPATH=.:/opt/oracle/jdbc/lib/ojdbc8.jar:$CLASSPATH

缺點：專案間相衝、版本難控、部署複雜。

3. 連線字串與基本程式碼

Thin Driver (純 Java，無需 Oracle Client)

// JDBC URL 格式
// 1. SID 格式 (舊版)
jdbc:oracle:thin:@host:port:SID
// 2. Service Name 格式 (推薦)
jdbc:oracle:thin:@//host:port/service_name
// 3. TNS 別名格式 (需 tnsnames.ora + oracle.net.tns_admin 系統屬性)
jdbc:oracle:thin:@tns_alias

// 完整範例
String url = "jdbc:oracle:thin:@//192.168.1.100:1521/ORCLPDB1";
String user = "app_user";
String pwd  = "secure_password";

try (Connection conn = DriverManager.getConnection(url, user, pwd)) {
    // 自動載入驅動 (JDBC 4.0+ SPI，無需 Class.forName)
    try (PreparedStatement ps = conn.prepareStatement("SELECT SYSDATE FROM dual");
         ResultSet rs = ps.executeQuery()) {
        if (rs.next()) System.out.println("DB Time: " + rs.getTimestamp(1));
    }
}

OCI Driver (厚驅動，需 Oracle Instant Client)

僅在需 Oracle Client 特定功能 (如 TAF、進階加密、外部程序) 時使用。需安裝 Instant Client、設定 LD_LIBRARY_PATH/PATH、URL 用 jdbc:oracle:oci:@。

4. 連線池：HikariCP (生產標準)

// Maven
implementation 'com.zaxxer:HikariCP:5.0.1'

// 配置
HikariConfig config = new HikariConfig();
config.setJdbcUrl("jdbc:oracle:thin:@//host:1521/service_name");
config.setUsername("app_user");
config.setPassword("pwd");
config.setMaximumPoolSize(20);
config.setMinimumIdle(5);
config.setConnectionTimeout(30000);
config.setIdleTimeout(600000);
config.setMaxLifetime(1800000);
config.addDataSourceProperty("oracle.net.CONNECT_TIMEOUT", "10000");
config.addDataSourceProperty("oracle.jdbc.ReadTimeout", "60000");

HikariDataSource ds = new HikariDataSource(config);
// Spring Boot: spring.datasource.hikari.* 對應上述屬性

5. 進階功能與常見坑

6. 快速驗證清單

• ☐ ojdbc8/11.jar 在 Classpath/依賴中
• ☐ URL 使用 //host:port/service_name 格式
• ☐ 防火牆開放 1521 (或指定埠)
• ☐ Listener 啟動且服務 READY (lsnrctl status)
• ☐ 帳號解鎖、密碼正確、權限足夠
• ☐ 連線池參數調整 (生產環境)

遵循「Maven 管理依賴 → Thin Driver + Service Name URL → HikariCP 連線池 → 標準 JDBC API」這條主流路徑，能避開 90% 的連線問題，專注於業務開發。